# Irmu documentation

Source: https://irmu.com/docs

## Quickstart

1. Create an API key in the dashboard.
2. Export it: `export IRMU_API_KEY=irmu_sk_live_...`
3. Send your first request against `https://app.irmu.com/api`.

```bash
curl -X GET "https://app.irmu.com/api/crawl?url=&premium=&js=&ai_query=&key=" \
  -H "Authorization: Bearer $IRMU_API_KEY"
```

### Authentication

Every request carries a bearer token: `Authorization: Bearer $IRMU_API_KEY`. Keys are created in the dashboard under **API keys**, and you can create as many as you want.

Use one key per environment (local, staging, production) so you can revoke a leaked key without taking the rest of your pipeline down. Each key reports its own usage and success rate.

```bash
export IRMU_API_KEY="irmu_sk_live_..."

# every request carries the same header
curl -H "Authorization: Bearer $IRMU_API_KEY" ...
```

Manage keys in the dashboard: https://irmu.com/docs/dashboard#keys

### Handling errors

Errors are typed and stable. Retry `429` (you exceeded your plan concurrency) with exponential backoff, and retry `502` a couple of times — the target was unreachable after our own retries and you were not billed.

Do not retry `400` or `401`: the request or the key is wrong and retrying will fail identically. `402` means the credit pool is exhausted, so top up or wait for the reset instead of hammering the endpoint.

## Core concepts

The handful of ideas that explain every parameter and every bill.

### Credits & billing

Everything is priced in credits, and only successful requests are billed. If a fetch fails after our internal retries, you are not charged for it.

Cost per request depends on what you asked for: plain fetches are cheapest, JavaScript rendering and premium geo-routing cost more. The response includes `credits_used` so you can attribute spend per job.

See plans and credit volumes: https://irmu.com/pricing

### Retries & idempotency

Irmu retries transient failures server-side — blocked responses, timeouts, proxy hiccups — before returning anything to you. What reaches your code is either a usable response or a typed error.

Reads are idempotent: re-sending the same request returns the same shape and bills again only if it succeeds. Make your own retry loop bounded and jittered so a bad target does not burn your daily budget.

### Rate limits & concurrency

Limits are expressed as concurrent requests, not requests per second: Free 1, Lite 5, Standard 50, Pro 100. Enterprise plans go higher.

Going over your concurrency returns `429`. Cap your worker pool at your plan's number rather than relying on retries, and add a per-domain cap of your own so one slow target cannot starve the rest of the queue.

### Sessions & cookies

Pass a `session_id` to keep the same exit IP across a series of requests. That is what you want for multi-step flows — search results, pagination, anything where a target ties state to the client.

Use a fresh session per logical job and drop it when the job ends; long-lived sessions get stale and are more likely to be challenged.

### Rendering JavaScript

Set `render=true` when the markup you need is produced client-side. The page is loaded in a real browser and you get the DOM after execution instead of the initial HTML shell.

Rendering is slower and costs more credits, so leave it off by default. A quick test: fetch the page without rendering, and if the field you need is missing from the HTML, turn rendering on for that route only.

### Geo-targeting

Pass a `country` code to route the request through a proxy in that country. Use it for localized pricing, regional search results and geo-fenced content.

The response echoes the country actually used, so you can assert on it in tests rather than assuming the routing worked.

## Operating in production

What to watch, what to cap and how to keep keys safe once you are past the first crawl.

### Observability

The dashboard reports success rate and usage per API key, and credit consumption broken down by day, website and key. Tagging jobs with their own key is the cheapest way to get per-pipeline telemetry without building it yourself.

Watch success rate per site rather than in aggregate — a single target changing its defences is invisible in a global number.

Quota and usage views: https://irmu.com/docs/dashboard#quota

### Cost control

Set a daily credit limit in organization settings. It is the most your organization may spend in a day; a crawl that would go over it is refused until midnight. Leave it empty for no limit.

For crawls that ask a question about a page, plug in your own language model in settings — extraction then runs on your model and no additional credits are charged.

Configure limits in settings: https://irmu.com/docs/dashboard#settings

### Security best practices

Keep keys in your secret manager, never in source control or client-side code. Rotate on a schedule and immediately after anyone with access leaves.

Because keys are unlimited and individually revocable, prefer many narrow keys over one shared key: revoking a compromised key should never require a coordinated redeploy.

## Dashboard

Full guide: https://irmu.com/docs/dashboard

- **API keys** — Create, monitor and revoke the credentials your code uses.
- **Team** — Invite colleagues and work across organizations.
- **Plan & billing** — See what you are on and change it when you outgrow it.
- **Quota** — Understand where your credits went.
- **Organization settings** — Rename the organization, cap daily spend and bring your own model.

## APIs

### Crawl

- `GET /crawl` — Crawl a url

## Error taxonomy

| Status | Meaning |
| --- | --- |
| 401 | No key, an unknown key, or a caller that is not an organization --
a signed-in dashboard user reaches this endpoint as a user and is
refused here, since a user has no credits to spend.
 |
| 402 | The organization's balance will not cover the crawl. Nothing is charged and nothing is recorded. |
| 422 | The request did not validate. |

Full reference in markdown: https://irmu.com/api-reference.md