From e9a48f2e603372df5e374720f71b15d0c4c10669 Mon Sep 17 00:00:00 2001
From: tiennm99 <tiennm99@outlook.com>
Date: Sat, 9 May 2026 09:13:58 +0700
Subject: [PATCH] docs: document POST API and add AI-agents usage callout

---
 README.md | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/README.md b/README.md
index fa078dc..f89df20 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,31 @@
 # MiTi-Telegram
 
 A Cloudflare Worker that forward message to [My Telegram](http://t.me/tiennm5)
+
+## Usage
+
+POST a JSON body to `https://miti-telegram.miti99.workers.dev/` with a `text` field. Any other method returns 405; missing/empty `text` returns 400.
+
+```bash
+curl -X POST https://miti-telegram.miti99.workers.dev/ \
+  -H 'Content-Type: application/json' \
+  -d '{"text": "Hello from miti-telegram"}'
+```
+
+`application/x-www-form-urlencoded` (`text=...`) is also accepted. Responses are CORS-permissive (`Access-Control-Allow-Origin: *`).
+
+The worker prepends request metadata (IP, geo, UA, timestamp) to every message before forwarding to Telegram — that's expected, not an info leak (it's *your* Telegram).
+
+### For AI agents / Claude Code routines
+
+Read this section first, do not probe.
+
+- **One POST per intended message.** Do not send a `"test"` payload to verify the endpoint — every successful POST forwards to Telegram, so probes spam the inbox.
+- **Exact request:**
+  ```
+  POST https://miti-telegram.miti99.workers.dev/
+  Content-Type: application/json
+  {"text": "<your message>"}
+  ```
+- **Success:** any 2xx. **Auth-related errors:** 500 (worker missing `TELEGRAM_TOKEN` / `TELEGRAM_CHAT_ID` env vars — that's a deploy-time issue, not something a caller can fix).
+- **Do not retry on 2xx.** Each POST is a separate Telegram message; a retry would duplicate.