Versioning and changelog

Versioning

The version is in the path: /api/v1. Within v1 we only make additive changes:

Additive (can happen any time)	Breaking (only in a new version)
new endpoints	removing or renaming an endpoint or field
new optional request fields	a new required field
new response fields	changing a field’s type or meaning
new values in enums (status, error code)	removing an enum value
new error codes	making a valid request invalid

So write clients that ignore fields they don’t know and handle unknown enum values and error codes gracefully. A breaking change would ship as /api/v2, announced here first, with v1 kept running alongside it.

Changelog

2026-10-08 — ad schedule

• New: schedule — show a campaign only on chosen weekdays and hours. Set it on create, PATCH /v1/campaigns/{ad_id}, copy, or many campaigns at once with the bulk action set_schedule; null removes it. GET /v1/campaigns/{ad_id} returns it. Format: Schedule. It doesn’t switch the campaign on or off.
• Pausing, resuming and editing a campaign keep its schedule; copies and recreated campaigns inherit it.
• Fix: PATCH /v1/campaigns/{ad_id} with only cpm, active and/or schedule sent the campaign back to Telegram’s review. These now go through Telegram’s own bid and status forms and never trigger a review; other fields still do (Telegram’s rule) — see Edit.
• Fix: setting a schedule on a campaign with no budget could send it back to review. Such a campaign now answers 400 with param: "schedule" and is left untouched — add budget first, then set the schedule.
• GET /v1/campaigns/{ad_id} is now current: it re-reads the ad from Telegram when our copy is older than 5 minutes, so schedule, text and views_per_user reflect changes made directly in Telegram. New field synced_at says when the ad was last read. See Freshness.

2026-10-08 — campaign management

• New: write access. Keys can now carry Manage campaigns: POST /v1/campaigns (create, up to 100 per call), PATCH /v1/campaigns/{ad_id}, POST …/pause, …/resume, …/budget, …/copy, POST /v1/campaigns/bulk, DELETE /v1/campaigns/{ad_id}, POST /v1/media. Existing keys stay read-only until you switch it on.
• New reads: GET /v1/campaigns/{ad_id} (one campaign with targeting), GET /v1/tasks/{id}, GET /v1/groups, GET /v1/targeting.
• Agency team members can create keys; a key reaches the cabinets shared with the member, at their access level. The agency owner sees all team keys (API & Webhooks → Team keys) and can revoke them.
• Idempotency-Key required on create, copy, bulk and budget.
• Separate write rate limit: 30 requests per minute, apart from the 60 reads.
• GET /v1/account/info adds access_level, currency, balance, balance_updated_at, min_budget, features.
• Errors add code and request_id next to the unchanged error text. A 500 no longer includes internal error text.
• account_id is accepted everywhere accountId was (both work).
• Fix: GET /v1/stats?period=all returned cost per click as cpa; it is now cost per action, like every other period.

2026-10-04

• URL filters apply to both webhooks; status_change only reaches keys whose owner can see the cabinet.

2026-09-18

• Conversions get their own budget (20 events/s) apart from the read limit; batches of up to 1,000 events.

2026-06-30

• Inbound conversions: POST /v1/postback, GET /v1/ingest/{token}, GET /v1/conversions.

Earlier

• GET /v1/campaigns with cursor pagination and the bot_username, promote_domain and type filters; stats endpoints; status_change and hourly_digest webhooks.