> ## Documentation Index
> Fetch the complete documentation index at: https://blaxel-pm-2441-firewall.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API overview

> Authenticate and interact with all Blaxel resources using REST APIs, with support for API key and OAuth 2.0 authentication methods.

Blaxel APIs allow you to interact with all resources inside of and across your workspace(s).

## Get started

Authentication to the Blaxel APIs can either be done using [API keys](../Security/Access-tokens) created from the Blaxel console, or through a [classic OAuth 2.0 flow](../Security/Access-tokens).

**API keys** allow you to get started quickly. Simply [generate an API key](../Security/Access-tokens) for your user or service account and use the API key as a bearer token in place of the authorization headers `Authorization` or `X-Blaxel-Authorization` in any call to the Blaxel APIs.

For example, to list models:

```bash theme={null}
curl 'https://api.blaxel.ai/v0/models' \
  -H 'accept: application/json, text/plain, */*' \
  -H 'X-Blaxel-Authorization: Bearer YOUR-API-KEY'
```

To use **short-lived JWTs**, see [the guide on using an OAuth 2.0 flow](../Security/Access-tokens).

See the reference documentation below for more information:

<Card title="Inference API" icon="earth-americas" href="/api-reference/inference">Run inference requests on your deployments. </Card>

<Card title="Billing API" icon="code" href="/api-reference/billing">
  Programmatically retrieve cost and usage metrics.
</Card>

<Card title="Management API" icon="cubes" href="/api-reference/agents/list-all-agents">Manage agents, functions, policies and much more.</Card>

## API Versioning

The Blaxel API uses header-based versioning to evolve response formats and behavior without breaking existing clients.

### Version Header

All requests should include the `Blaxel-Version` header:

<CodeGroup>
  ```bash curl theme={null}
  curl 'https://api.blaxel.ai/v0/agents' \
    -H 'X-Blaxel-Authorization: Bearer YOUR-API-KEY' \
    -H 'Blaxel-Version: 2026-04-16'
  ```
</CodeGroup>

### Version Format

Versions follow a Stripe-style date-based format:

* **Stable**: `YYYY-MM-DD` (e.g., `2026-04-16`)
* **Preview**: `YYYY-MM-DD.preview` (e.g., `2026-04-16.preview`)

### Default Behavior

<Note>If you omit the `Blaxel-Version` header, the API defaults to the earliest stable version (`2026-04-16`). This ensures backward compatibility — existing clients work without changes.</Note>

### Pinning to a Specific Version

To guarantee consistent response shapes across API updates, pin your client to a specific version:

```bash theme={null}
curl -H 'Blaxel-Version: 2026-04-20' https://api.blaxel.ai/v0/agents
```

Once a new version is released, you can update your client at your own pace.

### Unknown Versions

If you send an unsupported version, the API returns `400 Bad Request`:

```json theme={null}
{
  "error": "invalid_api_version",
  "message": "Unknown API version \"2026-99-99\". Valid versions: 2026-04-16. See https://docs.blaxel.ai/api-reference/introduction#api-versioning for the list of supported versions."
}
```

Update your client to use a version from the table below.

### Version History

<table>
  <thead>
    <tr>
      <th>Version</th>
      <th>Released</th>
      <th>Status</th>
      <th>Notes</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>2026-04-16</code></td>
      <td>2026-04-16</td>
      <td>Stable</td>
      <td>Initial version</td>
    </tr>
  </tbody>
</table>

## Pagination

<Warning>
  Pagination is currently only available for the Management API.
</Warning>

List operations on the Management API return paginated results. Each response includes a `data` array and a `meta` object with cursor information for fetching subsequent pages.

<Note>
  Pagination requires `Blaxel-Version: 2026-04-28` or later. Requests without this header use the earliest stable version, which returns a bare array without pagination metadata.
</Note>

### Request parameters

| Parameter | Type      | Description                                                                                                                                                                                                            |
| --------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cursor`  | `string`  | Opaque cursor returned by a previous response's meta.nextCursor. Only valid for the same query (workspace + filters); the server rejects cursors bound to a different query or older than 24h. Omit on the first page. |
| `limit`   | `integer` | Maximum number of items to return per page. Defaults to 50, maximum `200`.                                                                                                                                             |
| `sort`    | `string`  | Sort order. Options: `createdAt:desc` (default), `createdAt:asc`, `name:asc`, `name:desc`.                                                                                                                             |

<Tip>
  For accounts with multiple workspaces, specify the workspace as an additional request parameter, such as `?workspace=WORKSPACE_NAME&...`, or via an additional `X-Blaxel-Workspace: WORKSPACE_NAME` header in the request.
</Tip>

### Response metadata

Each paginated response includes a `meta` object:

| Field        | Type      | Description                                                                                |
| ------------ | --------- | ------------------------------------------------------------------------------------------ |
| `hasMore`    | `boolean` | `true` when additional pages are available.                                                |
| `nextCursor` | `string`  | Opaque cursor to pass as `cursor` on the next request. Empty when there are no more pages. |
| `total`      | `integer` | Total number of items in the workspace, ignoring filters.                                  |

### Fetch pages manually

Request the first page:

```bash theme={null}
curl 'https://api.blaxel.ai/v0/agents?limit=50' \
  -H 'X-Blaxel-Authorization: Bearer YOUR-API-KEY' \
  -H 'Blaxel-Version: 2026-04-28'
```

The response includes `meta.nextCursor`. Pass it as `cursor` to fetch the next page:

```bash theme={null}
curl 'https://api.blaxel.ai/v0/agents?limit=50&cursor=NEXT_CURSOR' \
  -H 'X-Blaxel-Authorization: Bearer YOUR-API-KEY' \
  -H 'Blaxel-Version: 2026-04-28'
```

Continue fetching pages until `meta.hasMore` is `false`.