> Parel documentation. Index of every page: https://parel.si/docs/llms.txt. This page in HTML: https://parel.si/docs/quickstart-code

# Your own code

> Call Parel's REST API from curl, Node or Python with an API key in a header, and make retries safe with an idempotency key.

<!-- Generated from packages/core/src/clients.ts by `npm run docs:quickstarts`. Edit the client there, not this file. -->

## Before you start

Create an account at [app.parel.si/signup](https://app.parel.si/signup). ₹100 of welcome credit is on the balance at once; no card is asked for.

## Set up Your own code

**Step 1.** Create an API key: in the dashboard open **Getting started**, pick **Your own code**, choose **Use an API key** and create the key there, so it is filled into these steps (or create one under **API keys**). It is shown once. Keep the default permissions and set a daily cap in rupees.

**Step 2.** Every tool runs through one request: `POST https://api.parel.si/v1/run` with the key in `Authorization: Bearer`, a JSON body with `tool` and `input`, and optionally `idempotency_key` and `client_tag`. From a terminal:

```bash
curl https://api.parel.si/v1/run \
  -H "Authorization: Bearer $PAREL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"search_web","input":{"q":"best protein bar","country":"in","language":"en","limit":10},"idempotency_key":"first-search"}'
```

**Step 3.** The same call from Node 18 or newer:

```javascript
const r = await fetch("https://api.parel.si/v1/run", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PAREL_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    tool: "find_email",
    input: { domain: "zomato.com", full_name: "Deepinder Goyal" },
    idempotency_key: "lead-1842",
  }),
});
const out = await r.json();
if (out.ok) {
  console.log(out.class, out.cost_paise, "paise", out.data);   // "ok" and the price, or "ok_free" and 0 on a miss
} else {
  console.log(out.error, out.message, "charged", out.charged_paise); // always 0
}
```

**Step 4.** And from Python:

```python
import os, requests

r = requests.post(
    "https://api.parel.si/v1/run",
    headers={"Authorization": f"Bearer {os.environ['PAREL_KEY']}"},
    json={"tool": "verify_email", "input": {"email": "deepinder@zomato.com"}},
)
out = r.json()
if out["ok"]:
    print(out["class"], out["cost_paise"], out["data"])
else:
    print(out["error"], out["message"], out["charged_paise"])  # failed calls are ₹0
```

**Step 5.** Check the key for free first: `GET https://api.parel.si/v1/balance` with the same header answers with `balance_paise`; the agent prompt below does the same over MCP.

```bash
curl https://api.parel.si/v1/balance -H "Authorization: Bearer $PAREL_KEY"
```

## Check it works

Over MCP the same check is the free `check_balance` tool; from an agent, ask:

```text
Check my Parel balance.
```

Then try a paid call:

```text
Using Parel, what are the latest 10 news articles about D2C brands in India? Title, source, date and link.
```

That runs `search_news` for ₹0.20; an empty result list is ₹0. Every call shows up in the dashboard's Usage page with its price.

## Good to know

- Store the key as an environment variable (`PAREL_KEY` in the examples); never put it in a URL or a repository.
- Send the same `idempotency_key` on a retry: a finished call is replayed for ₹0, so a retry never pays twice.

## Read the headers too

| Header | On | Meaning |
|---|---|---|
| `X-Request-Id` | every response | Quote it to support. Also `request_id` in every error body. |
| `X-Call-Id` | every call that was recorded | The `call_id` to look up with `GET /v1/runs/:id`. |
| `X-Cost-Paise` | every `POST /v1/run` response | What this call cost, in paise. `0` on every failure. |
| `X-Balance-Paise` | when the balance is known | Your balance after the call. |
| `X-RateLimit-Limit`, `X-RateLimit-Remaining` | `POST /v1/run` | 300 paid calls per minute per key by default. |

## Make retries safe

Send the same `idempotency_key` on a retry. A finished call is replayed from storage for ₹0 (`class: "replay"`) for 24 hours; a failed call runs again; a key still in flight answers `409 in_progress`. If your side timed out and you have the `call_id`, read [`GET /v1/runs/:id`](https://parel.si/docs/api/runs.md) before running again. Every outcome: [Conventions](https://parel.si/docs/api/conventions.md#idempotency).

## Before you run many

- [`POST /v1/quote`](https://parel.si/docs/api/quote.md) returns the estimated charge and the hold for an input, free, so a loop can add up its cost before spending.
- `client_tag` (up to 64 characters) attributes spend to a client of yours in the dashboard.
- Give the key a daily cap. A capped call is refused with [`budget_exceeded`](https://parel.si/docs/errors.md#budget_exceeded) before anything is spent.

## Next

- [Examples](https://parel.si/docs/examples.md): a prompt for each tool and what it costs.
- [Playbooks](https://parel.si/docs/playbooks.md): six ready-made jobs with the tools they use and a typical run's cost.
- [Conventions](https://parel.si/docs/api/conventions.md): money units, time format, every header, idempotency.
- [Errors](https://parel.si/docs/errors.md): every code, what you pay (₹0 in every row but one), whether to retry.
