Download asset

POST https://api.iconscout.com/v3/items/{item}/api-download

Download a specific asset by UUID. Returns a temporary signed URL valid for a short time.

Requires both Client-ID and Client-Secret headers.

Format Reference by Asset Type

Asset	Supported `format` values
`icon`	`svg`, `png`
`illustration`	`svg`, `png`, `eps`
`3d`	`png`, `gltf`, `glb`, `obj`, `fbx`, `blend`
`lottie`	`json`, `lottie`, `gif`, `mp4`
`ai-image`	`png`, `jpg`

Width & Height

For png downloads, width controls the output size (e.g., 512 for 512×512).
For vector formats (svg, json, lottie), set width and height to 0.
For 3D/glTF formats, width and height are ignored.

Parameters

Name	In	Type	Notes
`item`	path	`string`	required UUID of the asset to download. Obtain from search results or the asset detail endpoint.

Responses

Status	Meaning
`200`	Download URL returned successfully
`400`	Either the request was malformed (`data.reason` is `invalid_request`), or no subscription on this client covers this asset (`data.reason` is `asset_not_covered`). The second case is distinct from the `422` below and they are not interchangeable: a `422` carries `subscription_required` and means the client has no active API plan at all, while this `400` carries `asset_not_covered` and means it has one that does not cover this asset type. Branch on `data.reason`, not on the status alone.
`401`	Unauthorized — missing or invalid Client-ID / Client-Secret. `data.reason` is `invalid_credentials`.
`402`	The download would take the current billing period past its spend ceiling, on an account where that ceiling is enforced. `data.reason` is `credit_limit_reached`. Where the ceiling is not enforced, usage past the allowance is recorded and reported — the usage emails and `GET /v3/credits` — rather than refused, so handle this response but do not rely on it to cap your spend. Free billing periods run from the day the app was created, not from the 1st of the month — read `period_start` and `period_end` from `GET /v3/credits` rather than assuming a calendar boundary. Upgrading the app lifts the limit immediately.
`404`	No asset with that UUID (`data.reason` is `item_not_found`), or the requested `format` does not apply to this asset type (`data.reason` is `format_not_available`, and the message names the formats that do).
`422`	This client holds no active API subscription at all. `data.reason` is `subscription_required`. See the `400` above for `asset_not_covered`, the case where it holds one that does not cover this asset.
`429`	Rate limit exceeded for this client. `data.reason` is `rate_limit_exceeded`. Limits are per client, per product family and per method, and are set by your plan — support can raise them for an individual client. Read the `X-RateLimit-*` headers, which are returned on every response the limiter admits and not only this one, rather than hard-coding a number; back off on `Retry-After`. They are absent only where the call is refused before the limiter runs — a `401` on invalid credentials. Distinct from the credit allowance, which refuses with `quota_exhausted` and is not cleared by waiting.

Examples

Download SVG icon

curl -X POST 'https://api.iconscout.com/v3/items/a1b2c3d4-e5f6-7890-abcd-ef1234567890/api-download' \
  -H 'Client-ID: your-client-id' \
  -H 'Client-Secret: your-client-secret' \
  -H 'Content-Type: application/json' \
  -d '{"format": "svg", "width": 0, "height": 0}'

Download PNG icon at 512px

curl -X POST 'https://api.iconscout.com/v3/items/a1b2c3d4-e5f6-7890-abcd-ef1234567890/api-download' \
  -H 'Client-ID: your-client-id' \
  -H 'Client-Secret: your-client-secret' \
  -H 'Content-Type: application/json' \
  -d '{"format": "png", "width": 512, "height": 512}'

Download Lottie as JSON

curl -X POST 'https://api.iconscout.com/v3/items/b2c3d4e5-f6a7-8901-bcde-f12345678901/api-download' \
  -H 'Client-ID: your-client-id' \
  -H 'Client-Secret: your-client-secret' \
  -H 'Content-Type: application/json' \
  -d '{"format": "json", "width": 0, "height": 0}'

Node.js fetch

const uuid = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
const res = await fetch(
  `https://api.iconscout.com/v3/items/${uuid}/api-download`,
  {
    method: 'POST',
    headers: {
      'Client-ID': 'your-client-id',
      'Client-Secret': 'your-client-secret',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ format: 'svg', width: 0, height: 0 }),
  }
);
const { response } = await res.json();
console.log(response.download.download_url);

Python requests

import requests

uuid = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
resp = requests.post(
    f'https://api.iconscout.com/v3/items/{uuid}/api-download',
    headers={
        'Client-ID': 'your-client-id',
        'Client-Secret': 'your-client-secret',
    },
    json={
        'format': 'svg',
        'width': 0,
        'height': 0,
    },
)
download_url = resp.json()['response']['download']['download_url']
print(download_url)

Try it in the interactive reference →