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

# API Reference: Authentication, Errors & Endpoints

> Authenticate with the Buckle API to manage workspaces, agents, credential grants, secrets, app connections, conversations, and organization policy.

The Buckle API gives you programmatic access to everything behind the gateway: workspaces, agents and what each agent may use, secrets, app connections, organization policy, and, for hosted agents, their conversations, schedules, memory, skills, and Slack channels.

Per-agent access is written through the **Grants** endpoints (attach a connection or secret to an agent, optionally with per-tool allow and approval lists and resource scoping; see [Agent access](/docs/guides/agent-access.md)). Organization-wide guardrails live under `/org/policy`; the workspace `/policy` endpoints are read-only reflections of the enforced result.

Every endpoint page states which [editions](/docs/api-reference/editions.md) it is available on.

## Base URL

```bash Cloud theme={null}
https://api.buckle.dev/v1
```

```bash Self-hosted (Docker) theme={null}
http://localhost:10254/v1
```

The approvals long-poll endpoints are served by the **gateway** instead (`https://gw.buckle.dev` on Cloud, `http://localhost:10255` self-hosted). `GET /gateway-url` returns the right origin for any deployment. SCIM has its own base path, `/scim/v2`, and its own tokens.

## Authentication

All API endpoints require authentication unless their page says otherwise. Include your API key as a Bearer token in the `Authorization` header:

```bash theme={null}
curl https://api.buckle.dev/v1/agents \
  -H "Authorization: Bearer oc_your_api_key_here"
```

### Workspace keys

Workspace API keys start with `oc_` and are scoped to a single workspace. A workspace key always operates on its own workspace. Read yours from the dashboard, or with `GET /user/api-key`.

### Organization keys

Organization API keys start with `oc_org_` and operate across workspaces. For workspace-scoped endpoints, include the `X-Workspace-Id` header to name the workspace (without it, workspace endpoints return `401`):

```bash theme={null}
curl https://api.buckle.dev/v1/agents \
  -H "Authorization: Bearer oc_org_your_key_here" \
  -H "X-Workspace-Id: ws_abc123"
```

Organization endpoints (`/org/...`) need no workspace header. Where roles are enforced (Cloud and Enterprise) they require the admin or owner role; the Community edition runs a flat team where every member passes.

> [!NOTE]
>
> `X-Workspace-Id` replaced `X-Project-Id`, and `/v1/workspaces` replaced `/v1/projects`. The old header, the `?_project` query bridge, and the `/v1/projects` path alias still work for a deprecation window and answer with a `Deprecation: true` header. Migrate to the new names.

### Dashboard sessions

The web dashboard calls the same API with its own session: a bearer JWT on Cloud, the session cookie on self-hosted deployments. A few endpoints are session-only (deleting your account, accepting an invitation, claiming a provisioned account), because they act for the person rather than a workspace or organization. API keys are refused there.

## Errors

The API returns standard HTTP status codes. Validation errors return a flat `error` string; authentication and service errors use an envelope with `message` and `type`:

```json Validation error theme={null}
{
  "error": "Label is required"
}
```

```json Auth / service error theme={null}
{
  "error": {
    "message": "Invalid API key or token.",
    "type": "authentication_error"
  }
}
```

| Status | Meaning |
| - | - |
| `400` | Validation error or bad request |
| `401` | Missing or invalid authentication, or a missing `X-Workspace-Id` |
| `403` | Insufficient permissions, a plan or quota limit (Cloud), or an Enterprise feature on a Community deployment |
| `404` | Resource not found |
| `409` | Conflict (duplicate identifier, a turn already in flight, a stale reorder) |
| `410` | Endpoint retired; the message names the replacement |
| `413` | Upload too large |
| `422` | The body parsed but violates a validation law |
| `429` | Rate limited |

See [Errors](/docs/api-reference/errors.md) for the full reference, including the retired-endpoint inventory. Errors on an agent's **proxied** traffic (including the `409` account-selection protocol) are a separate surface: [Gateway errors](/docs/api-reference/gateway-errors.md) and [Multiple accounts](/docs/api-reference/multi-account.md).

## Rate limits

The gateway enforces rate limits on proxied requests via [policy rules](/docs/guides/rules.md). A handful of management endpoints are throttled too (the SSO lookup, SSO connection tests, and SCIM), and say so on their page.


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