# Create a response

`POST https://api.azta.ai/v1/responses`

Ask a question and get an answer from the law, with its sources.

Set exactly one of `stream` and `background` to `true`. `stream` answers `200` with server-sent events; `background` answers `202` with the response at `status: queued`, which you poll with `getResponse` and which sends a webhook when it ends.

This API is stateless: `input` is a string, or the whole conversation as items whose last item has the role `user`. `conversation` and `previous_response_id` are refused. Unknown fields are accepted and ignored.

A response is charged to the organisation's credit balance (see `usage.cost`); a request the ledger refuses starts nothing.

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | header | no | Makes a retry safe. A repeat of the same request answers with the stored result and `Idempotent-Replayed: true`, and is never charged again; the same key on a different request is `idempotency_key_reused`. Without it, a retry is a new, charged request. |
| `X-Jurisdiction` | header | no | The countries whose law is read, comma-separated, in any case and spacing; `hu` without it. Allowed: `at`, `be`, `ch`, `cz`, `de`, `dk`, `es`, `fi`, `fr`, `gb`, `ge`, `hr`, `hu`, `ie`, `it`, `li`, `lu`, `mc`, `nl`, `no`, `pl`, `pt`, `ro`, `rs`, `se`, `si`, `sk`. Any other code, `us`, `oecd` and `ifrs` included, is `unsupported_jurisdiction`. |

## Request body

Required. Content type: `application/json`.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `background` | boolean | no | Answer `202` with the response queued, to be polled. Exactly one of `stream` and `background` must be `true`. |
| `conversation` | string or null | no | Not supported: refused with `unsupported_parameter`. |
| `depth` | string (`standard`, `deep`) | no | `deep` may research further before it answers, and is priced higher; `standard` never runs deep web research. Echoed on the response. |
| `input` | string or array of object | yes | The question as a string, or the whole conversation as items whose last item has the role `user`. Only the most recent turns are used. A string, or an item's `content`, is at most 50,000 characters. |
| `model` | string | no | A label, echoed back on the response. It selects nothing. |
| `previous_response_id` | string or null | no | Not supported: refused with `unsupported_parameter`. |
| `stream` | boolean | no | Answer as server-sent events. Exactly one of `stream` and `background` must be `true`. |

## Responses

### 200

With `stream: true`, a server-sent event stream of the Responses events `response.created`, `response.in_progress`, `response.output_item.added`, `response.content_part.added`, `response.output_text.delta` (many), `response.output_text.done` (the whole text, and authoritative), `response.content_part.done`, `response.output_item.done`, then `response.completed`, or `response.failed`, which also ends a cancelled response, with `status: cancelled`. A `: ping` comment arrives every 15 seconds. Annotations and `sources` arrive only in the closing frames. Dropping the connection does not cancel the response.

A repeat of an earlier create under the same `Idempotency-Key` answers with the response object as JSON, as it is now, whether the original streamed or not.

Content type: `application/json`.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `completed_at` | integer or null | yes | Unix seconds at which the response ended, whatever its status. |
| `created_at` | integer | yes | Unix seconds. |
| `depth` | string (`standard`, `deep`) or null | yes | Echoed from the request; null for a response made before depth existed. |
| `error` | object or null | yes |  |
| `id` | string | yes |  |
| `incomplete_details` | object or null | yes |  |
| `instructions` | string or null | yes |  |
| `metadata` | object | yes |  |
| `model` | string | yes | The label the request named, echoed. |
| `object` | string (`response`) | yes |  |
| `output` | array of object | yes | Empty until the response is `completed`: there is no partial text. |
| `output[].content` | array of object | yes |  |
| `output[].content[].annotations` | array of object | yes |  |
| `output[].content[].annotations[].end_index` | integer | yes | Where the label ends, exclusive. |
| `output[].content[].annotations[].source_number` | integer | yes | The `number` of the source in `sources`. |
| `output[].content[].annotations[].start_index` | integer | yes | Where the label starts, counted in Unicode code points of `text`, so `text[start_index:end_index]` is the label. |
| `output[].content[].annotations[].title` | string | yes |  |
| `output[].content[].annotations[].type` | string (`url_citation`) | yes |  |
| `output[].content[].annotations[].url` | string | yes |  |
| `output[].content[].text` | string | yes |  |
| `output[].content[].type` | string (`output_text`) | yes |  |
| `output[].id` | string | yes |  |
| `output[].role` | string (`assistant`) | yes |  |
| `output[].status` | string (`completed`) | yes |  |
| `output[].type` | string (`message`) | yes |  |
| `parallel_tool_calls` | boolean | yes |  |
| `previous_response_id` | string or null | yes |  |
| `reasoning` | object | yes |  |
| `reasoning.effort` | string or null | yes |  |
| `reasoning.summary` | string or null | yes |  |
| `sources` | array of object | yes | What the answer cites, numbered by first citation. Empty until the response is `completed`. |
| `sources[].act` | object or null | yes |  |
| `sources[].country` | string or null | yes | A lower-case country code. |
| `sources[].excerpt` | string or null | yes | At most 300 characters, whitespace collapsed. |
| `sources[].kind` | string (`provision`, `passage`, `web`) | yes |  |
| `sources[].number` | integer | yes | `source_number` of the annotations that cite it. |
| `sources[].section` | string or null | yes |  |
| `sources[].title` | string | yes | A display label: the act's short title, then the section. |
| `sources[].unit_id` | string or null | yes | A provision's id, the same across versions and re-ingestion: pass it to `POST /v1/provisions/fetch`. A Hungarian id is `hu:njt:<njt id>:<path>`. Null for a passage, a web page, and a provision whose id is not stable. |
| `sources[].url` | string | yes | An absolute URL, always present. |
| `sources[].url_kind` | string (`official`, `viewer`, `web`) | yes | `official` is the publisher's own page, `viewer` our provision or document viewer, `web` a web page's own URL. |
| `sources[].version` | object or null | yes | The version cited. Null for a passage, a web page and a version that never commenced. |
| `status` | string (`queued`, `in_progress`, `completed`, `failed`, `cancelled`) | yes |  |
| `store` | boolean | yes |  |
| `temperature` | number | yes |  |
| `text` | object | yes |  |
| `text.format` | object | yes |  |
| `text.format.type` | string (`text`) | yes |  |
| `tool_choice` | string | yes |  |
| `tools` | array of object | yes |  |
| `top_p` | number | yes |  |
| `truncation` | string (`auto`, `disabled`) | yes |  |
| `usage` | object or null | yes | Present once the response has ended. |

### 202

With `background: true`, the response at `status: queued`.

Content type: `application/json`.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `completed_at` | integer or null | yes | Unix seconds at which the response ended, whatever its status. |
| `created_at` | integer | yes | Unix seconds. |
| `depth` | string (`standard`, `deep`) or null | yes | Echoed from the request; null for a response made before depth existed. |
| `error` | object or null | yes |  |
| `id` | string | yes |  |
| `incomplete_details` | object or null | yes |  |
| `instructions` | string or null | yes |  |
| `metadata` | object | yes |  |
| `model` | string | yes | The label the request named, echoed. |
| `object` | string (`response`) | yes |  |
| `output` | array of object | yes | Empty until the response is `completed`: there is no partial text. |
| `output[].content` | array of object | yes |  |
| `output[].content[].annotations` | array of object | yes |  |
| `output[].content[].annotations[].end_index` | integer | yes | Where the label ends, exclusive. |
| `output[].content[].annotations[].source_number` | integer | yes | The `number` of the source in `sources`. |
| `output[].content[].annotations[].start_index` | integer | yes | Where the label starts, counted in Unicode code points of `text`, so `text[start_index:end_index]` is the label. |
| `output[].content[].annotations[].title` | string | yes |  |
| `output[].content[].annotations[].type` | string (`url_citation`) | yes |  |
| `output[].content[].annotations[].url` | string | yes |  |
| `output[].content[].text` | string | yes |  |
| `output[].content[].type` | string (`output_text`) | yes |  |
| `output[].id` | string | yes |  |
| `output[].role` | string (`assistant`) | yes |  |
| `output[].status` | string (`completed`) | yes |  |
| `output[].type` | string (`message`) | yes |  |
| `parallel_tool_calls` | boolean | yes |  |
| `previous_response_id` | string or null | yes |  |
| `reasoning` | object | yes |  |
| `reasoning.effort` | string or null | yes |  |
| `reasoning.summary` | string or null | yes |  |
| `sources` | array of object | yes | What the answer cites, numbered by first citation. Empty until the response is `completed`. |
| `sources[].act` | object or null | yes |  |
| `sources[].country` | string or null | yes | A lower-case country code. |
| `sources[].excerpt` | string or null | yes | At most 300 characters, whitespace collapsed. |
| `sources[].kind` | string (`provision`, `passage`, `web`) | yes |  |
| `sources[].number` | integer | yes | `source_number` of the annotations that cite it. |
| `sources[].section` | string or null | yes |  |
| `sources[].title` | string | yes | A display label: the act's short title, then the section. |
| `sources[].unit_id` | string or null | yes | A provision's id, the same across versions and re-ingestion: pass it to `POST /v1/provisions/fetch`. A Hungarian id is `hu:njt:<njt id>:<path>`. Null for a passage, a web page, and a provision whose id is not stable. |
| `sources[].url` | string | yes | An absolute URL, always present. |
| `sources[].url_kind` | string (`official`, `viewer`, `web`) | yes | `official` is the publisher's own page, `viewer` our provision or document viewer, `web` a web page's own URL. |
| `sources[].version` | object or null | yes | The version cited. Null for a passage, a web page and a version that never commenced. |
| `status` | string (`queued`, `in_progress`, `completed`, `failed`, `cancelled`) | yes |  |
| `store` | boolean | yes |  |
| `temperature` | number | yes |  |
| `text` | object | yes |  |
| `text.format` | object | yes |  |
| `text.format.type` | string (`text`) | yes |  |
| `tool_choice` | string | yes |  |
| `tools` | array of object | yes |  |
| `top_p` | number | yes |  |
| `truncation` | string (`auto`, `disabled`) | yes |  |
| `usage` | object or null | yes | Present once the response has ended. |

### 400

The request was refused.

- `invalid_request`: The body or a header is invalid; `param` names the field.
- `unsupported_parameter`: `previous_response_id` or `conversation` was sent. This API is stateless: send the conversation as input items.
- `unsupported_jurisdiction`: `X-Jurisdiction` names `us`, `oecd`, `ifrs` or an unknown code; on a search, also when none of the countries it names can be searched by provision.
- `idempotency_key_reused`: The `Idempotency-Key` was used for a different request.

Content type: `application/json`.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | object | yes | What a refused request says. Branch on `code`; `message` is English and names no internal detail. |
| `error.code` | string (`invalid_request`, `unsupported_parameter`, `unsupported_jurisdiction`, `idempotency_key_reused`, `invalid_api_key`, `insufficient_credits`, `spend_cap_reached`, `account_suspended`, `not_found`, `idempotency_key_in_use`, `response_finished`, `rate_limit_exceeded`, `concurrency_limit_exceeded`, `server_error`, `ledger_unavailable`) | yes |  |
| `error.message` | string | yes |  |
| `error.param` | string or null | yes | The field or header at fault, or null when no one is. |
| `error.type` | string (`invalid_request_error`, `authentication_error`, `billing_error`, `permission_error`, `not_found_error`, `rate_limit_error`, `server_error`) | yes |  |

### 401

The request was refused.

- `invalid_api_key`: The key is missing, malformed, unknown, revoked or expired.

Content type: `application/json`.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | object | yes | What a refused request says. Branch on `code`; `message` is English and names no internal detail. |
| `error.code` | string (`invalid_request`, `unsupported_parameter`, `unsupported_jurisdiction`, `idempotency_key_reused`, `invalid_api_key`, `insufficient_credits`, `spend_cap_reached`, `account_suspended`, `not_found`, `idempotency_key_in_use`, `response_finished`, `rate_limit_exceeded`, `concurrency_limit_exceeded`, `server_error`, `ledger_unavailable`) | yes |  |
| `error.message` | string | yes |  |
| `error.param` | string or null | yes | The field or header at fault, or null when no one is. |
| `error.type` | string (`invalid_request_error`, `authentication_error`, `billing_error`, `permission_error`, `not_found_error`, `rate_limit_error`, `server_error`) | yes |  |

### 402

The request was refused.

- `insufficient_credits`: Not enough credit, or no credit account.
- `spend_cap_reached`: A company, key or postpaid monthly spend cap would be exceeded.

Content type: `application/json`.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | object | yes | What a refused request says. Branch on `code`; `message` is English and names no internal detail. |
| `error.code` | string (`invalid_request`, `unsupported_parameter`, `unsupported_jurisdiction`, `idempotency_key_reused`, `invalid_api_key`, `insufficient_credits`, `spend_cap_reached`, `account_suspended`, `not_found`, `idempotency_key_in_use`, `response_finished`, `rate_limit_exceeded`, `concurrency_limit_exceeded`, `server_error`, `ledger_unavailable`) | yes |  |
| `error.message` | string | yes |  |
| `error.param` | string or null | yes | The field or header at fault, or null when no one is. |
| `error.type` | string (`invalid_request_error`, `authentication_error`, `billing_error`, `permission_error`, `not_found_error`, `rate_limit_error`, `server_error`) | yes |  |

### 403

The request was refused.

- `account_suspended`: The credit account is suspended or closed.

Content type: `application/json`.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | object | yes | What a refused request says. Branch on `code`; `message` is English and names no internal detail. |
| `error.code` | string (`invalid_request`, `unsupported_parameter`, `unsupported_jurisdiction`, `idempotency_key_reused`, `invalid_api_key`, `insufficient_credits`, `spend_cap_reached`, `account_suspended`, `not_found`, `idempotency_key_in_use`, `response_finished`, `rate_limit_exceeded`, `concurrency_limit_exceeded`, `server_error`, `ledger_unavailable`) | yes |  |
| `error.message` | string | yes |  |
| `error.param` | string or null | yes | The field or header at fault, or null when no one is. |
| `error.type` | string (`invalid_request_error`, `authentication_error`, `billing_error`, `permission_error`, `not_found_error`, `rate_limit_error`, `server_error`) | yes |  |

### 409

The request was refused.

- `idempotency_key_in_use`: A request with this `Idempotency-Key` is still being processed.

Content type: `application/json`.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | object | yes | What a refused request says. Branch on `code`; `message` is English and names no internal detail. |
| `error.code` | string (`invalid_request`, `unsupported_parameter`, `unsupported_jurisdiction`, `idempotency_key_reused`, `invalid_api_key`, `insufficient_credits`, `spend_cap_reached`, `account_suspended`, `not_found`, `idempotency_key_in_use`, `response_finished`, `rate_limit_exceeded`, `concurrency_limit_exceeded`, `server_error`, `ledger_unavailable`) | yes |  |
| `error.message` | string | yes |  |
| `error.param` | string or null | yes | The field or header at fault, or null when no one is. |
| `error.type` | string (`invalid_request_error`, `authentication_error`, `billing_error`, `permission_error`, `not_found_error`, `rate_limit_error`, `server_error`) | yes |  |

### 429

The request was refused.

- `rate_limit_exceeded`: The key's requests-per-minute limit is used up.
- `concurrency_limit_exceeded`: The key already has as many responses in progress as it may.

Content type: `application/json`.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | object | yes | What a refused request says. Branch on `code`; `message` is English and names no internal detail. |
| `error.code` | string (`invalid_request`, `unsupported_parameter`, `unsupported_jurisdiction`, `idempotency_key_reused`, `invalid_api_key`, `insufficient_credits`, `spend_cap_reached`, `account_suspended`, `not_found`, `idempotency_key_in_use`, `response_finished`, `rate_limit_exceeded`, `concurrency_limit_exceeded`, `server_error`, `ledger_unavailable`) | yes |  |
| `error.message` | string | yes |  |
| `error.param` | string or null | yes | The field or header at fault, or null when no one is. |
| `error.type` | string (`invalid_request_error`, `authentication_error`, `billing_error`, `permission_error`, `not_found_error`, `rate_limit_error`, `server_error`) | yes |  |

### 500

The request was refused.

- `server_error`: Anything else. It never carries exception text.

Content type: `application/json`.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | object | yes | What a refused request says. Branch on `code`; `message` is English and names no internal detail. |
| `error.code` | string (`invalid_request`, `unsupported_parameter`, `unsupported_jurisdiction`, `idempotency_key_reused`, `invalid_api_key`, `insufficient_credits`, `spend_cap_reached`, `account_suspended`, `not_found`, `idempotency_key_in_use`, `response_finished`, `rate_limit_exceeded`, `concurrency_limit_exceeded`, `server_error`, `ledger_unavailable`) | yes |  |
| `error.message` | string | yes |  |
| `error.param` | string or null | yes | The field or header at fault, or null when no one is. |
| `error.type` | string (`invalid_request_error`, `authentication_error`, `billing_error`, `permission_error`, `not_found_error`, `rate_limit_error`, `server_error`) | yes |  |

### 503

The request was refused.

- `ledger_unavailable`: The credit ledger could not answer, so the request fails closed. A `503` at the start of a request charges nothing; a lookup's `503` after its provisions were read may have charged it, and a retry with the same `Idempotency-Key` never charges it twice.

Content type: `application/json`.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | object | yes | What a refused request says. Branch on `code`; `message` is English and names no internal detail. |
| `error.code` | string (`invalid_request`, `unsupported_parameter`, `unsupported_jurisdiction`, `idempotency_key_reused`, `invalid_api_key`, `insufficient_credits`, `spend_cap_reached`, `account_suspended`, `not_found`, `idempotency_key_in_use`, `response_finished`, `rate_limit_exceeded`, `concurrency_limit_exceeded`, `server_error`, `ledger_unavailable`) | yes |  |
| `error.message` | string | yes |  |
| `error.param` | string or null | yes | The field or header at fault, or null when no one is. |
| `error.type` | string (`invalid_request_error`, `authentication_error`, `billing_error`, `permission_error`, `not_found_error`, `rate_limit_error`, `server_error`) | yes |  |