> Parel documentation. Index of every page: https://parel.si/docs/llms.txt. This page in HTML: https://parel.si/docs/api/conventions

# Conventions

> Base URL, JSON in and out, the response headers, money in paise, time in UTC, and every outcome of an idempotency key.

## Base URL and format

```text
https://api.parel.si
```

Every request body is JSON with `Content-Type: application/json`; every response is JSON. Request bodies are limited to 1 MB ([`body_too_large`](https://parel.si/docs/errors.md#body_too_large), HTTP 413). Responses are never cached (`Cache-Control: no-store`).

Every success body has `ok: true`. Every error body has `ok: false`, an `error` code from the [error table](https://parel.si/docs/errors.md), a plain-English `message`, `charged_paise: 0` wherever money was at stake, `retryable` where a retry is meaningful, and `request_id`.

## Response headers

| Header | On | Meaning |
|---|---|---|
| `X-Request-Id` | every response | A unique id for the request; also `request_id` in every error body. Quote it to support. |
| `X-Call-Id` | every response for a recorded call | The call's id (`call_id` in the body). A refusal that made no call row (a confirmation request, an in-flight key) has none. |
| `X-Cost-Paise` | every `POST /v1/run` response, and a slow job's final poll | What the call cost. `0` on every failure. |
| `X-Balance-Paise` | when the balance is known after the call | The team balance after settlement. |
| `X-RateLimit-Limit`, `X-RateLimit-Remaining` | `POST /v1/run` | The per-key limit (300 paid calls per minute by default) and what is left in the current minute. |
| `Retry-After` | 429 responses, and 202 polls of a slow job | Seconds to wait. |

Captured from staging on a `POST /v1/run` that failed upstream (₹0):

```text
HTTP/2 502
x-call-id: ff83d554-fb75-4cf9-896a-bf53f91ea587
x-cost-paise: 0
x-balance-paise: 9850
x-ratelimit-limit: 300
x-ratelimit-remaining: 299
x-request-id: e2ab626c-a886-42f6-924a-115ce37a5b5f
cache-control: no-store
```

## Money

All amounts are integers in **paise** (₹1 = 100 paise): `cost_paise`, `charged_paise`, `balance_paise`, `estimate_paise`, `hold_paise`, `reserved_paise`, `per_result_paise`, `credit_paise`, `price_paise`. Where a human-readable form is given it is a string with the rupee sign: `balance` is always two decimals (`"₹98.50"`); `estimate` and `hold` keep two decimals under ₹10 and show whole rupees with Indian grouping above (`"₹2.80"`, `"₹1,500"`).

Prices are computed at the exchange rate in force when the call starts (today ₹93.93 per US dollar, 17 November 2026) and never change mid-call. Each price is the source's cost plus Parel's margin, at least ₹0.10 a call; there is no flat minimum. A charge is normally no more than the hold that preceded it. See [if a source bills more than expected](https://parel.si/docs/how-it-works.md#if-a-source-bills-more-than-expected).

## Time

Timestamps are ISO 8601 in UTC with milliseconds: `"2026-10-27T20:36:21.744Z"` (`created_at`, `finished_at` on [`GET /v1/runs/:id`](https://parel.si/docs/api/runs.md)). Durations are integers: `latency_ms`, `poll_after_seconds`, `retry_after_seconds`, `timeout_seconds`. Spend caps count days and months in India time (Asia/Kolkata).

## Identifiers

`call_id` and `request_id` are UUIDs. Tool names are lower-case with underscores (`search_web`). An `idempotency_key` is any string of 1 to 128 characters; a `client_tag` 1 to 64.

## Idempotency

Send an `idempotency_key` in the body of [`POST /v1/run`](https://parel.si/docs/api/run.md) (or the header `Idempotency-Key`; the body wins when both are present), or the `idempotency_key` argument of `run_tool` over MCP. Keys are scoped to your team. Every outcome:

| Situation | Response | You pay |
|---|---|---|
| First call with the key succeeds (`ok`, `ok_free`) | The normal response. The answer is stored for 24 hours. | the normal price |
| Same key, same tool and input, within 24 hours | HTTP 200, `class: "replay"`, `cost_paise: 0`, `replay_of` naming the first call, `data` as stored. A new call row records the replay. | ₹0 |
| Same key while the first call is still running | HTTP 409 [`in_progress`](https://parel.si/docs/errors.md#in_progress), `retryable: true`, with the running `call_id` when known. Poll [`GET /v1/runs/:id`](https://parel.si/docs/api/runs.md) or retry shortly. | ₹0 |
| Same key, different tool or input | HTTP 422 [`idempotency_key_mismatch`](https://parel.si/docs/errors.md#idempotency_key_mismatch). Keys are per exact input (the fingerprint is the tool name plus the key-sorted JSON of the input). | ₹0 |
| Same key after the stored answer was purged (24 hours) | HTTP 410 [`replay_expired`](https://parel.si/docs/errors.md#replay_expired) with `original_call_id`. Use a new key; the call runs and is charged again. | ₹0 for the refusal |
| First call with the key failed | The key is not reserved. The same key runs the call again. | as a new call |
| No key | Every call runs and is charged on its own. | as a new call |

A replayed answer is served before anything else is checked, so it does not need `confirm: true` and does not count against the rate limit's paid calls. The same key is also passed to the source, so a retry after a network failure on our side cannot be charged twice upstream either.

## Call classes

Every call has a `class`; only `ok` is charged. The seven values and what they mean are on [How it works](https://parel.si/docs/how-it-works.md#what-costs-0) and at the foot of the [error table](https://parel.si/docs/errors.md#classes).
