> ## Documentation Index
> Fetch the complete documentation index at: https://docs.osintcat.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Authentication, plans, limits, billing and errors for every OsintCat API endpoint

The OsintCat API gives you the lookups of the OsintCat dashboard over HTTPS, with JSON responses.

## Base URL

```
https://www.osintcat.net/api
```

Every endpoint answers `GET` (most also accept `POST`); parameters always go in the query string.

## Authentication

Send your API key in the `X-API-KEY` header with every request:

```bash theme={null}
curl "https://www.osintcat.net/api/user" -H "X-API-KEY: YOUR_API_KEY"
```

Create keys in your account under **[Settings → Developer](https://www.osintcat.net/account/developer)**. A key is shown once, when you create it: store it then. Keys start with `cat_`; your account's CatID is not an API key.

When you create a key you choose when it expires: in 7, 30 or 90 days, in a year, never, or on a date you pick. An expired key is refused like a revoked one (`403`); keys are not renewed, so create a new key and delete the old one. You can rename a key at any time.

> [!WARNING]
>
> Treat a key like a password. Keep it on your server, never in a website, app or public repository. If a key may have leaked, revoke it in Settings → Developer and create a new one.

### Scopes

Each key carries one or more scopes:

| Scope | Allows |
| - | - |
| `*` | Everything (the default for a new key) |
| `osint:read` | All lookups and [Modules](https://docs.osintcat.net/api-reference/endpoint/modules.md) |
| `account:read` | [Account](https://docs.osintcat.net/api-reference/endpoint/user.md) |
| `billing:read` | Your balance: `GET /api/_/user/balance` answers `{"balance": 12.5}` (euros) |

A request outside the key's scopes is refused with `403 insufficient_scope`.

### Allowed IP addresses

In Settings → Developer you can list the IP addresses your requests come from. With a list set, requests from any other address are refused with `403 IP_UNAUTHORIZED`. Leave the list empty to allow every address (for example for serverless platforms whose addresses change). A list holds up to 1 address on Researcher, 3 on Investigator and 10 on Max.

## Plans and daily allowance

API access is part of these plans:

| Plan | Lookups per day | API keys |
| - | - | - |
| Researcher | 300 | 1 |
| Investigator | 750 | 3 |
| Max | Unlimited | 5 |

Free and Starter plans have no API access (`403 UPGRADE_REQUIRED`). Prices are on the [pricing page](https://www.osintcat.net/pricing).

* Each lookup counts once against the daily allowance, including answers served from a cache.
* The allowance resets at 00:00 UTC. [Account](https://docs.osintcat.net/api-reference/endpoint/user.md) shows what is left; many lookups also return it in `_meta.lookups_left`.
* [Account](https://docs.osintcat.net/api-reference/endpoint/user.md), [Modules](https://docs.osintcat.net/api-reference/endpoint/modules.md) and polling a task do not count.

### When the allowance is used up

Most lookups continue at a per-lookup price charged to your account balance; the module's page in the dashboard shows the price. You are charged only when the lookup finds something, and never for a lookup that fails. Without enough balance the request is refused with `402 INSUFFICIENT_BALANCE`. Lookups that have no per-lookup price are refused with `429 LIMIT_REACHED` until the allowance resets.

Each endpoint's page says how it is counted under **Usage**.

## Rate limits

* **3 requests per second** per account, across all endpoints.
* **5,000 requests per hour** per endpoint from one IP address.

Over a limit, the request is refused with `429 rate_limit`; the `Retry-After` header says how many seconds to wait. Keep well inside the limits: repeatedly exceeding them can pause API access for your account for a while.

## Responses

Responses are JSON. A successful lookup answers `200` even when nothing was found; the endpoint's page shows how an empty result looks. Errors carry an `error` field, usually with a `message`, and every error answer names its `request_id`. A server error (`5xx`) also names an `error_id`. Quote them to support so we can find the request; the `X-Request-Id` header carries the request id on every response, successful ones included.

## Errors

| Status | `error` | Meaning |
| - | - | - |
| 400 | `query error` and others | A required parameter is missing or invalid. |
| 401 | `API key required` | No `X-API-KEY` header. |
| 402 | `INSUFFICIENT_BALANCE` | The lookup would be charged and your balance does not cover it. |
| 403 | `Unauthorized` / `Invalid API key` | The key does not exist, was revoked, or has expired. |
| 403 | `insufficient_scope` | The key lacks the scope this endpoint needs. |
| 403 | `UPGRADE_REQUIRED` | Your plan has no API access. |
| 403 | `ACCESS_DENIED` | Your plan does not include this module, or it is currently unavailable. [Modules](https://docs.osintcat.net/api-reference/endpoint/modules.md) shows which you can use. |
| 403 | `IP_UNAUTHORIZED` | The request came from an address that is not on your allowed list. |
| 403 | `ACCOUNT_REQUIRES_VERIFICATION` | Verify your account in the dashboard first. |
| 403 | `account_frozen` | API access for the account is suspended; contact support. |
| 410 | `ENDPOINT_RETIRED` | The endpoint no longer exists. |
| 429 | `LIMIT_REACHED` | The daily allowance is used up. |
| 429 | `rate_limit` | Too many requests; see `Retry-After`. |
| 500 | `internal_server_error` | Something failed on our side; quote the `error_id` and `request_id` to support. |
| 424 | (varies) | The lookup could not be completed: a data source failed or was too slow. The `X-Upstream-Status` header says which (`502` or `504`). Not charged; quote the `request_id` to support. |
| 503 | (varies) | The lookup is under maintenance. Not charged. |

## Endpoints

> [card] [Account](https://docs.osintcat.net/api-reference/endpoint/user.md)
>
> Plan and today's allowance

> [card] [Modules](https://docs.osintcat.net/api-reference/endpoint/modules.md)
>
> Which lookups your plan includes

> [card] [Breach Lookup](https://docs.osintcat.net/api-reference/endpoint/breach.md)
>
> Breach and leak indexes

> [card] [Database Search](https://docs.osintcat.net/api-reference/endpoint/database-search.md)
>
> Stealer logs and combo lists

> [card] [Email OSINT](https://docs.osintcat.net/api-reference/endpoint/email-osint.md)
>
> Where an address is registered

> [card] [Phone OSINT](https://docs.osintcat.net/api-reference/endpoint/phone-osint.md)
>
> Carrier, line type, risk

> [card] [Machine Viewer](https://docs.osintcat.net/api-reference/endpoint/machine-viewer.md)
>
> Infected machine records

> [card] [IP Lookup](https://docs.osintcat.net/api-reference/endpoint/ip.md)
>
> Services and location of an IP

The navigation lists every endpoint.

## Responsible use

Use the API only for lawful purposes such as security research, fraud prevention and investigations you are entitled to carry out, and in line with the [Terms of Service](https://www.osintcat.net/tos) and the data protection law that applies to you.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.