> ## Documentation Index
> [HTML page](https://blode.co/iconsmith/docs/api)
> [Documentation index](https://blode.co/iconsmith/docs/llms.txt)
> Use the index to discover all available pages before exploring further.

# HTTP API

POST /api/v1/icons is the whole generate contract. GET /api/v1/models describes the served model.

The zone is `https://blode.co/iconsmith`. Every path below is under that prefix.

## Draw

`POST /api/v1/icons`

Body: `{ model?, prompt?, concept?, images?, cut?, n?, stream? }`, at least one of `prompt`, `concept` or `images`.

- `prompt` is free text (500 characters)
- `concept` is an explicit slug; otherwise it derives from the prompt
- `images` is up to four `{ mime, base64 }` PNG, JPEG or WebP entries (base64 only)
- `cut` defaults to the house cut (24px, stroke 2, radius 3, outlined)
- `n` is 1 or 2
- unknown fields are refused with `param` naming them
- any `model` other than `iconsmith-1` is `model_not_found`
- `stream: true` answers `text/event-stream`

Response: `{ id, object: "icon.draw", created, model, revision, concept, prompt, images, cut, data, usage, credits?, took_ms }`. Image bytes are never echoed. `usage` is `null` when the provider has not reported token counts; it does not mean the draw was free.

Every response carries `X-Request-ID`. Errors are `{ status, code, message, request_id, param?, retry_after? }`.

## Models

- `GET /api/v1/models`
- `GET /api/v1/models/iconsmith-1`

## Keys

- `ism_live_…` spends a credit when credits are on; otherwise `invalid_api_key`
- `ism_test_…` is the sandbox on any deployment: no provider call, `credits: 0`
- browser draws require sign-in and monthly USD usage billing