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

# Introduction

> Get an API key and make your first call to the Bitscale API.

The Bitscale API lets you use Bitscale from your own code:

| Part | What it does |
| - | - |
| [Tools](https://docs.bitscale.ai/api-reference/tools/overview.md) | Run one enrichment tool on one record (find an email, scrape a profile, ask an AI model). No grid needed. |
| [Sources](https://docs.bitscale.ai/api-reference/sources/overview.md) | Search people, companies and LinkedIn data and get rows back. No grid needed. |
| [Grid APIs](https://docs.bitscale.ai/ingredients/bitscale-api-reference.md) | Read your grids, run them with new inputs and get the outputs. |

> [!NOTE]
>
> The API is available on every **paid plan**. On the Free plan every endpoint returns `403 FEATURE_DISABLED`.

| | |
| - | - |
| **Base URL** | `https://api.bitscale.ai/api/v1` |
| **Authentication** | `X-API-KEY: <your-api-key>` |
| **Content-Type** | `application/json` |

## Get your API key

1. Log in to Bitscale.
2. Go to **Settings → Account → API Key**.
3. Copy the key.

The key belongs to the workspace, not to you: every call runs in that workspace and uses its credits. Keep it secret and never put it in client-side code or a public repository. If it leaks, rotate it from the same settings page or with [`POST /api-key/rotate`](https://docs.bitscale.ai/ingredients/bitscale-api-reference#57-rotate-api-key); the old key stops working at once.

## Authentication

Send the key in the `X-API-KEY` header on every request. No other header identifies the workspace.

```bash theme={null}
curl "https://api.bitscale.ai/api/v1/tools" \
  -H "X-API-KEY: $BITSCALE_API_KEY"
```

| HTTP | Code | When |
| - | - | - |
| `401` | `INVALID_API_KEY` | The header is missing, or the key is invalid or rotated. |
| `403` | `FEATURE_DISABLED` | The workspace is on the Free plan. |
| `503` | `SERVICE_UNAVAILABLE` | The key or plan could not be checked right now. Retry. |

## Rate limits

Each workspace can make **5 requests per second**, across all endpoints, polling included. Going over returns `429 RATE_LIMIT_EXCEEDED`. To change the limit, contact [team@bitscale.ai](mailto:team@bitscale.ai).

Every response carries these headers:

| Header | Meaning |
| - | - |
| `X-RateLimit-Limit` | Requests allowed per second. |
| `X-RateLimit-Remaining` | Requests left in the current second. |
| `Retry-After` | Seconds to wait. Only on `429` responses. |

## Errors

Every error has the same shape: a machine-readable `code` and a readable `message`.

```json theme={null}
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Missing or invalid X-API-KEY header"
  }
}
```

Each section lists its own codes: [Tools](https://docs.bitscale.ai/api-reference/tools/overview.md#errors), [Sources](https://docs.bitscale.ai/api-reference/sources/overview.md#errors), [Grid APIs](https://docs.bitscale.ai/ingredients/bitscale-api-reference.md#7-error-code-reference).

## Long-running requests

Tool runs and source searches wait up to 25 seconds for a result. If the work takes longer you get `202 Accepted` with a `poll_url`; call it every 2–5 seconds until the status is no longer `running`. Set your client timeout to at least 60 seconds.

## Credits

Calls are billed to the workspace's credits the same way as in the app. Listing tools and sources, reading schemas, counting and filter-value lookups are free. When the workspace runs out, calls return `402`.


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