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

# API Reference

> Authenticate and interact with the OneCLI API to manage agents, secrets, policy rules, and app connections programmatically.

The OneCLI API gives you programmatic access to manage your agents, secrets, policy rules, and app connections.

## Base URL

<CodeGroup>
  ```bash Cloud theme={null}
  https://api.onecli.sh/v1
  ```

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

## Authentication

All API endpoints require authentication. Include your API key as a Bearer token in the `Authorization` header:

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

### Getting your API key

1. Open the OneCLI dashboard
2. Go to **Settings** and copy your API key

API keys start with `oc_` and are scoped to a single project.

### Organization-scoped keys

Organization API keys start with `oc_org_` and can operate across projects. Include the `X-Project-Id` header to specify which project:

```bash theme={null}
curl https://api.onecli.sh/v1/agents \
  -H "Authorization: Bearer oc_org_your_key_here" \
  -H "X-Project-Id: proj_abc123"
```

### Partner keys

Partner API keys start with `oc_partner_` and let resellers and agencies provision and manage organizations for their customers. See the [Partner API](/api-reference/partner) for the full workflow.

## Errors

The API returns standard HTTP status codes. Error responses include a JSON body with an `error` field:

```json theme={null}
{
  "error": "Agent with this identifier already exists"
}
```

| Status | Meaning                               |
| ------ | ------------------------------------- |
| `400`  | Validation error or bad request       |
| `401`  | Missing or invalid authentication     |
| `404`  | Resource not found                    |
| `409`  | Conflict (e.g., duplicate identifier) |

## Rate limits

The gateway enforces rate limits on proxied requests via [policy rules](/guides/rules).