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

HeaderOnMeaning
X-Request-Idevery responseA unique id for the request; also request_id in every error body. Quote it to support.
X-Call-Idevery response for a recorded callThe 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-Paiseevery POST /v1/run response, and a slow job's final pollWhat the call cost. 0 on every failure.
X-Balance-Paisewhen the balance is known after the callThe team balance after settlement.
X-RateLimit-Limit, X-RateLimit-RemainingPOST /v1/runThe per-key limit (300 paid calls per minute by default) and what is left in the current minute.
Retry-After429 responses, and 202 polls of a slow jobSeconds 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:

SituationResponseYou 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 hoursHTTP 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 runningHTTP 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 inputHTTP 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 failedThe key is not reserved. The same key runs the call again.as a new call
No keyEvery 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.