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 created from the Blaxel console, or through a classic OAuth 2.0 flow.

API keys allow you to get started quickly. Simply generate an API key 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:

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.

See the reference documentation below for more information:

Inference API

Run inference requests on your deployments.

Billing API

Programmatically retrieve cost and usage metrics.

Management API

Manage agents, functions, policies and much more.

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:

curl

curl 'https://api.blaxel.ai/v0/agents' \
  -H 'X-Blaxel-Authorization: Bearer YOUR-API-KEY' \
  -H 'Blaxel-Version: 2026-04-16'

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

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.

Pinning to a Specific Version

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

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:

{
  "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

Version	Released	Status	Notes
2026-04-16	2026-04-16	Stable	Initial version

Pagination

Pagination is currently only available for the Management API.

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.

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.

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.

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.

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:

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:

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.