Docs
API reference

Create a response

POST
/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.

Authorization

bearerAuth
headerAuthorizationBearer <token>

Header Parameters

Idempotency-Key?string

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.

Match^[ -~]+$
Length1 <= length <= 255
X-Jurisdiction?string

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

application/json
  1. body

The body of createResponse. Fields it does not name, such as temperature, are accepted and ignored.

background?boolean

Answer 202 with the response queued, to be polled. Exactly one of stream and background must be true.

Defaultfalse
conversation?|

Not supported: refused with unsupported_parameter.

Defaultnull
depth?string

deep may research further before it answers, and is priced higher; standard never runs deep web research. Echoed on the response.

Default"standard"
Value in"standard""deep"
input*|array<>

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

A label, echoed back on the response. It selects nothing.

Default"azta-agent"
previous_response_id?|

Not supported: refused with unsupported_parameter.

Defaultnull
stream?boolean

Answer as server-sent events. Exactly one of stream and background must be true.

Defaultfalse

Response Body

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.

  1. response

A response, in OpenAI's Responses shape plus depth, sources and usage.cost.

Fields OpenAI defines and this API does not use keep their defaults.

completed_at*|

Unix seconds at which the response ended, whatever its status.

created_at*integer

Unix seconds.

depth*|

Echoed from the request; null for a response made before depth existed.

error*|null
id*string
Formatuuid
incomplete_details*|null
instructions*string|null
metadata*
model*string

The label the request named, echoed.

object*string
output*array<>

Empty until the response is completed: there is no partial text.

parallel_tool_calls*boolean
previous_response_id*string|null
reasoning*
sources*array<>

What the answer cites, numbered by first citation. Empty until the response is completed.

status*string
Value in"queued""in_progress""completed""failed""cancelled"
store*boolean
temperature*number
text*
tool_choice*string
tools*array<>
top_p*number
truncation*string
Value in"auto""disabled"
usage*|

Present once the response has ended.

Example Request
curl -X POST 'https://api.azta.ai/v1/responses' \  -H 'Content-Type: application/json' \  -d '{  "input": "string"}'
Example Response
{  "completed_at": 0,  "created_at": 0,  "depth": "standard",  "error": {    "code": "server_error",    "message": "string"  },  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "incomplete_details": {    "property1": "string",    "property2": "string"  },  "instructions": "string",  "metadata": {    "property1": "string",    "property2": "string"  },  "model": "string",  "object": "response",  "output": [    {      "content": [        {          "annotations": [            {              "end_index": 0,              "source_number": 1,              "start_index": 0,              "title": "string",              "type": "url_citation",              "url": "string"            }          ],          "text": "string",          "type": "output_text"        }      ],      "id": "string",      "role": "assistant",      "status": "completed",      "type": "message"    }  ],  "parallel_tool_calls": true,  "previous_response_id": "string",  "reasoning": {    "effort": "string",    "summary": "string"  },  "sources": [    {      "act": {        "identifier": "string",        "short_title": "string",        "title": "string"      },      "country": "string",      "excerpt": "string",      "kind": "provision",      "number": 1,      "section": "string",      "title": "string",      "unit_id": "string",      "url": "http://example.com",      "url_kind": "official",      "version": {        "effective_from": "2019-08-24",        "effective_to": "2019-08-24",        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "is_current": true      }    }  ],  "status": "queued",  "store": true,  "temperature": 0,  "text": {    "format": {      "type": "text"    }  },  "tool_choice": "string",  "tools": [    {}  ],  "top_p": 0,  "truncation": "auto",  "usage": {    "cost": {      "amount": "string",      "currency": "EUR"    },    "input_tokens": 0,    "input_tokens_details": {      "cached_tokens": 0    },    "output_tokens": 0,    "output_tokens_details": {      "reasoning_tokens": 0    },    "total_tokens": 0  }}

Cancel a response POST

Stop a response. A dropped stream cancels nothing; this call does. The response comes back `cancelled` once nothing was left running, or `in_progress` while a step is still being torn down; a second cancel then also answers `200`. A response that has already finished is `response_finished`, which includes one whose answer was complete when the cancel arrived: that one completes and is charged. A response cancelled before its first text delta reached you is free; one cancelled after it is charged. The call accepts `Idempotency-Key` and stores nothing.

Fetch provisions POST

Read provisions by `unit_id`, from a source record or a search hit: at most 20 per call. A `unit_id` names a provision, not a version, so it keeps working after the law is amended. `as_of` picks the version in force that day, today in UTC without it; each record echoes the date it used. `text` is cut to 20,000 characters. An id that was not found, or that this API does not serve (`us`, an add-on corpus, a country whose ids are not yet stable), is in `not_found` and free. Charged per provision returned; a call that returns none is not charged. `X-Jurisdiction` is checked as for a search and narrows nothing.