API documentation

Four steps from zero to a published post. The API key is the only secret your agent needs — platform credentials stay on our side, encrypted.

# 1. Sign up at https://agentpost.dietsoda.dev/register
# 2. Mint a key at /keys  ->  ap_live_xxxxxxxx
# 3. Connect at least one platform at /connections
# 4. Publish:

curl -X POST https://agentpost.dietsoda.dev/v1/publish \
  -H "X-API-Key: $AGENTPOST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platforms": ["x", "discord"],
    "text": "Shipped v2.0 🚀"
  }'

Authenticate with the X-API-Key header. The body is flat: platforms and text are required, and the remaining fields (title, subreddit, link_url, parse_mode) are optional and only read by the platforms that need them. The endpoint is strict: unknown fields are rejected with a 400, so send exactly the fields documented here.

Posting to a single platform? Send "platform": "x" instead of the array — the two forms are interchangeable.

{
  "platforms": ["x", "reddit", "telegram", "discord"],
  "text": "Shipped v2.0 — changelog in the thread.",
  "title": "Shipped v2.0",
  "subreddit": "SideProject",
  "link_url": "https://example.com/changelog",
  "parse_mode": "MarkdownV2"
}

The response returns one entry per requested platform, in the order you asked for them, plus your usage after the call.

{
  "results": [
    { "platform": "x", "ok": true, "post_id": "18...", "url": "https://x.com/you/status/18..." },
    { "platform": "discord", "ok": false, "error": "webhook returned 404" }
  ],
  "usage": { "used": 12, "limit": 1000, "period": "2026-07" }
}

Partial success is the normal case. A dead Discord webhook should not stop your X post from going out, so a per-platform failure is reported inside a 200 rather than failing the whole request. Only request-level problems (auth, quota, malformed body) use a non-2xx status.

// A per-platform failure does not fail the request.
// HTTP 200 with ok:false entries means "some went out, some did not".
const res = await fetch("https://agentpost.dietsoda.dev/v1/publish", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.AGENTPOST_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ platforms: ["x", "discord"], text }),
});

const body = await res.json();
if (res.status === 402) throw new Error("out of posts this period");
const failed = body.results.filter((r) => !r.ok);

Open Connections, click Connect X, approve the OAuth prompt. You are redirected straight back. Nothing to copy, nothing to store.

Discord uses a channel webhook — no bot to create, invite or host.

1. In your server: Server Settings → Integrations → Webhooks.
2. Click New Webhook, pick the channel to post into, and name it (the name is what appears on your posts).
3. Click Copy Webhook URL and paste it into the Discord card on Connections.

The URL is a credential — anyone holding it can post to that channel. Delete the webhook in Discord to revoke it everywhere.

You need two values: a bot token and the chat ID it posts into.

1. Message @BotFather on Telegram and send /newbot. It replies with a token like 123456:ABC-DEF...
2. Add the bot to your channel or group as an administrator (a bot cannot post into a chat it is not in).
3. Send any message in that chat, then call getUpdates and read the chat id:

curl "https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates"
# -> {"result":[{"message":{"chat":{"id":-1001234567890, ...

Channel IDs are negative and start with -100. Paste both values into the Telegram card on Connections.

Reddit is the fiddly one — it wants a script app plus a one-time refresh token. Ten minutes, once.

1. Go to reddit.com/prefs/apps → create another app. Choose type script and set the redirect URI to http://localhost:8080.
2. Copy the client ID (the string under the app name) and the secret.
3. Mint a refresh token by visiting the authorize URL below in a browser, approving, and exchanging the returned code. Ask for duration=permanent — a temporary grant expires in an hour and gives you no refresh token.

# 1. Open in a browser, approve, copy ?code= from the redirect:
https://www.reddit.com/api/v1/authorize?client_id=CLIENT_ID&response_type=code\
&state=x&redirect_uri=http://localhost:8080&duration=permanent&scope=submit%20identity

# 2. Exchange it (the code expires in ~10 minutes):
curl -X POST https://www.reddit.com/api/v1/access_token \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -d "grant_type=authorization_code&code=THE_CODE&redirect_uri=http://localhost:8080"
# -> {"refresh_token":"...", ...}

Paste the client ID, secret and refresh token into the Reddit card on Connections. The refresh token does not expire unless you revoke the app.

Every error body is {"error": "message"}. Retry 429 and 5xx with backoff; do not retry 401, 402 or 422 — they will not resolve on their own.