# Adsly documentation

> Documentation for Adsly, starting with its REST API for the Telegram Ads cabinets in an Adsly account (Euro, TON and Stars): read campaigns and stats, create, edit, pause, fund, copy and delete campaigns, receive status webhooks and send conversions back. Base URL https://app.adsly.pro/api/v1, auth header X-API-Key.

Rules an integration must follow: send an Idempotency-Key (UUID) on POST create/copy/bulk/budget; create, copy and bulk return 202 with a task — poll GET /v1/tasks/{id}; ad_id is unique only together with account_id; decimal money fields arrive as strings — parse them before arithmetic. Each page below is short Markdown; fetch the ones you need.

## Get started

- [Adsly API — overview and quickstart](https://adsly.pro/docs/api.md): What the Adsly API does, the base URL, and a five-minute path from a new key to your first campaign created and paused from code.
- [Keys and access](https://adsly.pro/docs/api/authentication.md): How API keys work — read-only and campaign-managing keys, which cabinets a key reaches, how agency owners and team members use the API, and how to keep keys safe.
- [Build with Claude and other AI assistants](https://adsly.pro/docs/api/ai-assistants.md): Hand the Adsly API docs to Claude Code or any coding agent — the files to point it at, ready-to-paste prompts, and the rules to put in your project's CLAUDE.md so the integration is safe.

## Concepts

- [Errors](https://adsly.pro/docs/api/errors.md): The error format, every error code the API returns, what each means and what to do about it.
- [Rate limits](https://adsly.pro/docs/api/rate-limits.md): How many requests a key can make — separate budgets for reads, writes and incoming conversions — the headers that show your remaining budget, and how to back off.
- [Idempotency](https://adsly.pro/docs/api/idempotency.md): How the Idempotency-Key header makes retries safe — no duplicate campaigns, no double top-ups — and exactly how the API treats repeated, changed and concurrent requests.
- [Tasks (async operations)](https://adsly.pro/docs/api/tasks.md): Creating, copying and bulk changes run in the background. How to follow a task with GET /v1/tasks/{id}, what its statuses mean and how to read its result.
- [Pagination](https://adsly.pro/docs/api/pagination.md): How to walk through every campaign of large cabinets with cursor pagination, and when the older offset mode is still fine.

## Reference

- [Cabinets (accounts)](https://adsly.pro/docs/api/accounts.md): GET /v1/account/info — the cabinets a key reaches, with currency, balance, minimum budget, your access level and which optional ad fields each cabinet supports.
- [Campaigns — list and read](https://adsly.pro/docs/api/campaigns.md): The campaign object, its statuses, GET /v1/campaigns with filters by status, bot, website domain and ad type, GET /v1/campaigns/{ad_id} for one campaign with its targeting and schedule.
- [Create campaigns](https://adsly.pro/docs/api/create-campaigns.md): POST /v1/campaigns — create one or up to 100 Telegram ads in a call, targeting channels, bots, search queries or audiences by country, language and topic; upload images and video with POST /v1/media.
- [Manage campaigns](https://adsly.pro/docs/api/manage-campaigns.md): Change a campaign's text, link, bid and daily cap; show it only on chosen days and hours; pause and resume; add or withdraw budget; copy; delete — one campaign at a time or up to 1,000 with a bulk call.
- [Stats](https://adsly.pro/docs/api/stats.md): GET /v1/stats per campaign, /v1/stats/total for cabinet totals and charts, /v1/stats/analytics for currency split and top campaigns — periods, custom date and hour ranges.
- [Targeting codes and groups](https://adsly.pro/docs/api/targeting.md): GET /v1/targeting lists the country, language and topic codes and ad button values campaigns accept; GET /v1/groups lists campaign groups.

## Integrations

- [Webhooks](https://adsly.pro/docs/api/webhooks.md): Signed HTTPS callbacks from Adsly — status_change the moment a campaign changes status, hourly_digest with every hour's numbers — headers, payloads, signature verification in Node.js and Python, retries.
- [Conversions (postbacks in)](https://adsly.pro/docs/api/conversions.md): Send leads, deposits and sales back to Adsly from your backend or tracker (Keitaro, RedTrack, Binom, Voluum) so every campaign shows its real results; read them back with GET /v1/conversions.
- [Versioning and changelog](https://adsly.pro/docs/api/changelog.md): How the Adsly API changes without breaking integrations — what counts as a breaking change, how new fields are added — and every change so far.

## Optional

- [OpenAPI 3.1 spec](https://adsly.pro/docs/api/openapi.yaml): every endpoint, parameter, schema and error code, machine-readable
- [All docs in one file](https://adsly.pro/docs/llms-full.txt): every page above concatenated