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
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, 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, 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):
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.
Time
Timestamps are ISO 8601 in UTC with milliseconds: "2026-10-27T20:36:21.744Z" (created_at, finished_at on GET /v1/runs/:id). 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 (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, retryable: true, with the running call_id when known. Poll GET /v1/runs/:id or retry shortly. | ₹0 |
| Same key, different tool or input | HTTP 422 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 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 and at the foot of the error table.
This page as Markdown: /docs/api/conventions.md. Something wrong or missing: hello@parel.si.