# Irmu API reference

Source: https://irmu.com/api-reference
Base URL: `https://app.irmu.com/api`

Authenticate every request with `Authorization: Bearer $IRMU_API_KEY`.

## Crawl

### `GET /crawl`

Crawl a url

Charges the calling organization for the crawl and tallies it against
the url's host for the day, then returns what was requested and what it
cost.

The charge is decided before the fetch: see `credits_charged` below for
the price of each combination of options.


Fetches a single URL, charges the calling organization's credit balance, and returns the response body alongside billing metadata. Costs are computed before the fetch and exposed in `credits_charged`; daily per-host tallies are recorded for rate-limiting purposes.

When to use it for one-off page retrieval where you need the raw content, a JavaScript-rendered view, or an AI-generated answer about the page. Use `premium` when standard egress IPs are blocked. Use `js=false` only when you are certain the target is static and want lower cost.

- `js` defaults to enabled; explicitly disable it for static targets to reduce charges.
- `ai_query` adds a fixed 5-credit surcharge; omit or leave empty to skip it.
- Passing `key` in the query string logs the credential in proxies and access logs; prefer the `Authorization` header.

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `url` | query | yes | string<uri> | The page to crawl. Must be `http` or `https` and must have a host. |
| `premium` | query | no | string | Fetch through the premium pool. Costs more; use it for targets that
refuse ordinary requests.

Sent as text in a query string, so the spellings a person would
reach for all work: `true`, `false`, `1`, `0`, `yes`, `no`, `on`,
`off`, in any case. Anything that is not a yes or a no is refused
rather than quietly read as `false`.
 |
| `js` | query | no | string | Render javascript before reading the page. On by default, because it
is what works on most of the web -- a caller who knows their target
is static turns it off and pays less. Accepts the same spellings as
`premium`.
 |
| `ai_query` | query | no | string | A question to answer about the page once it has been retrieved.
Costs 5 credits on top of the fetch. An empty value is the same as
asking nothing and costs nothing extra.
 |
| `key` | query | no | string | The API key, for callers that cannot set a header. Accepted on this
route only -- a key in a url is copied into access logs, proxy logs
and `Referer` headers, which is a fair trade for a
machine-to-machine endpoint and a bad one for anything else.
Ignored when an `Authorization` header is present.
 |

**cURL**

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

**Node.js**

```javascript
const res = await fetch("https://app.irmu.com/api/crawl", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.IRMU_API_KEY}`,
    "Content-Type": "application/json",
  }
});

const data = await res.json();
```

**Python**

```python
import os, requests

res = requests.get(
    "https://app.irmu.com/api/crawl",
    headers={"Authorization": f"Bearer {os.environ['IRMU_API_KEY']}"}
)

print(res.json())
```

**Responses**

- `200` — The crawl was charged and recorded.

```json
{
  "url": "https://www.Example.COM/products?page=2",
  "domain": "www.example.com",
  "premium": false,
  "js": true,
  "ai_query": "",
  "credits_charged": 5,
  "credits_remaining": 995
}
```

- `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.


```json
{
  "message": "string"
}
```

- `402` — The organization's balance will not cover the crawl. Nothing is charged and nothing is recorded.

```json
{
  "message": "This organization does not have enough credits for that crawl."
}
```

- `422` — The request did not validate.

```json
{
  "message": "The url field is required.",
  "errors": {
    "url": [
      "The url field is required."
    ]
  }
}
```


## Errors

| 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. |