# IconScout API > REST API for searching, downloading and converting design assets — icons, > illustrations, 3D assets and Lottie animations — and for running AI generation > against them. One versioned contract, published as OpenAPI 3.0. The machine-readable contract is the authoritative source. Prefer it over this summary, and over anything scraped from the rendered documentation page. ## Contract - [OpenAPI document (JSON)](https://api-docs.iconscout.com/openapi.json): the complete v3 contract — every operation, schema, status code and error reason. - [Rendered reference](https://api-docs.iconscout.com/): the same document, rendered, with code samples in cURL, JavaScript and Python. ## Authentication Two headers, and they are an AND, not an OR: - `Client-ID` — required on every endpoint. - `Client-Secret` — required on downloads, reverse-image search, converters, AI, task polling and credits. There is no bearer token on v3. A missing or mismatched pair returns `401` with `data.reason` of `invalid_credentials`. ## Response shape Every JSON response carries the same envelope: { "status": "success"|"error", "response": {...}|null, "message": ..., "meta": {...}, "elements": ... } The payload is under `response`, never under `data`. On an error, `data.reason` carries a stable machine-readable code — branch on that, not on `message` and not on the HTTP status alone, because several statuses cover more than one condition. ## Credits Two meters, reported together by `GET /v3/credits`. Never add them together: downloads already count inside `credits`. - `credits` — the API credit wallet. On a paid plan, conversions and AI draw on it, and asset downloads count toward its used figure too (from your first billing period starting on or after 1 October 2026), so every download reduces what is left for conversions and AI. - `downloads` — the per-asset download allowance on your subscriptions, weighted by asset type (`cost_per_download`). This is the ceiling a download is checked against; the wallet never refuses a download on its own. On the free plan, conversions and AI do **not** spend the monthly wallet. They draw on `credits.one_time_credits`, a grant that never refills and is shared by every app on the account. Size conversion and AI work against `one_time_credits.available`, not `available_credits`; once it is spent those calls return `429` with `data.reason` `quota_exhausted` until the account moves to a paid plan. Billing periods on the free plan run from the day the app was created, not from the 1st of the month. ## Discovery over hard-coding Prices, models, formats, upload ceilings and plan availability are all published at runtime and are all configuration that can change. Read them rather than embedding them: - `GET /v3/ai/operations` and `GET /v3/ai/models` — AI operations, models, per-pair pricing. - `GET /v3/convert/operations` — conversion catalogue, credit costs, accepted and produced types. - `GET /v3/credits` — wallet, per-product caps, download allowances. These catalogues are **annotated, not filtered**: an operation your plan excludes is still listed, with `available_on_your_plan: false`. AI and file conversion are also switched on or off per app, in the API dashboard. An app with one switched off gets `403` `entitlement_required` for that family even on a plan that includes it, and its catalogue shows `available_on_your_plan: false`. The message says which of the two applies. ## Notes for summarisation - Every v3 endpoint is rate limited per client per minute, sized by plan. The `X-RateLimit-*` headers are on every admitted response. A `429` is one of two things, told apart by `data.reason`: `rate_limit_exceeded` (transient, back off on `Retry-After`) or `quota_exhausted` (credits spent, and waiting will not clear it). - An AI task for an icon or illustration from a raster model reaches `COMPLETED` before its traced SVG exists. Poll once more after completion if you need the SVG. Vector models (`recraft-vector`, `recraft-vector-pro`) return native SVG at completion. - `Idempotency-Key` is a duplicate guard, not a replay mechanism. It does not return the original response the way Stripe's does. - `GET /v3/ai/tasks/{task}` is the canonical polling endpoint. `GET /v3/ai/jobs/{job}` is a deprecated alias for it.