# Search provisions

`POST https://api.azta.ai/v1/provisions/search`

Search the current provisions of the law in force, with no model call.

The words of `query` are all required, and one word is enough. A word starting with `-` is dropped and phrases are not searched. A hit without a `unit_id` is left out. `X-Jurisdiction` names at most 3 countries; when none of them can be searched by provision the call is `unsupported_jurisdiction`, and free.

Charged per call. A sandbox key gets sample records.

## 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 |
| --- | --- | --- | --- |
| `limit` | integer | no | How many hits to return. |
| `query` | string | yes | The words to search for. All are required, and one is enough; a word starting with `-` is dropped and phrases are not searched. |

## Responses

### 200

The hits, best first.

Content type: `application/json`.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array of object | yes |  |
| `data[].act` | object | yes | The act a provision belongs to. |
| `data[].act.identifier` | string or null | yes |  |
| `data[].act.short_title` | string or null | yes |  |
| `data[].act.title` | string | yes | Empty when the act has none. |
| `data[].country` | string | yes | A lower-case country code. |
| `data[].excerpt` | string or null | yes | At most 300 characters, whitespace collapsed. |
| `data[].kind` | string (`provision`) | yes |  |
| `data[].section` | string or null | yes |  |
| `data[].title` | string | yes | A display label: the act's short title, then the section. |
| `data[].unit_id` | string | 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>`. |
| `data[].url` | string | yes | An absolute URL, always present. |
| `data[].url_kind` | string (`official`, `viewer`) | yes | `official` is the publisher's own page, `viewer` our provision or document viewer. |
| `data[].version` | object or null | yes | The version read. Null for a version that never commenced. |
| `object` | string (`list`) | yes |  |
| `usage` | object | yes | What a provision lookup cost. |
| `usage.cost` | object | yes | An amount billed, in the account's currency. |
| `usage.cost.amount` | string | yes | Two decimals, as a string. |
| `usage.cost.currency` | string (`EUR`, `HUF`) | yes |  |

### 400

The request was refused.

- `invalid_request`: The body or a header is invalid; `param` names the field.
- `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.

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 |  |