Publisher API

Authentication

Create and submit a publisher platform, wait for approval, then generate its key in Network. Store the key only on your server. Only the owner can generate it; rotation immediately revokes the previous key. Send Authorization: Bearer with each API request.

Request an ad

GET /api/network/ad?language=en returns a creative or HTTP 204 when none matches. A publisher may request up to 60 advertisements per minute. A missing or revoked key returns 401. The format is taken from the approved publisher record, not from a query parameter.

curl "https://adsgram.store/api/network/ad?language=en" \
  -H "Authorization: Bearer $ADSGRAM_PUBLISHER_KEY"

// HTTP 200 response fields
{
  "campaign_id": 12,
  "title": "Example title",
  "text": "Example message",
  "button_text": "Open",
  "image_url": null,
  "click_url": "https://adsgram.store/api/network/click/<opaque-token>",
  "delivery_token": "<opaque-token>",
  "expires_in": 3600,
  "sponsored": true,
  "billing": "pilot_non_billable"
}

Confirm delivery

POST /api/network/delivery after a successful Telegram send. Send JSON containing token from delivery_token and the same publisher Authorization header. Confirmations are idempotent. An expired or unrelated token returns 404.

curl -X POST "https://adsgram.store/api/network/delivery" \
  -H "Authorization: Bearer $ADSGRAM_PUBLISHER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token":"<delivery_token>"}'

Link lifetime and failure handling

Pilot click links expire one hour after allocation. Pausing a publisher or campaign also disables its redirects. Use the returned link only for an immediate pilot placement; it is unsuitable for permanent posts. Do not confirm a failed send. Avoid blind retries after a send timeout because Telegram may already have delivered the message.