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

# Introduction

> Programmatic access to CNAP resources for automation, CLI tools, and integrations

The CNAP API is a RESTful API that lets you manage workspaces, clusters, templates, products, and deployments programmatically. It powers the [CNAP CLI](/cli) and can be used to build custom integrations.

## Base URL

All API requests are made to:

```
https://api.cnap.tech/v1
```

## Authentication

Every request requires a `Authorization: Bearer` header with either a Personal Access Token (PAT) or a JWT.

```bash theme={null}
curl https://api.cnap.tech/v1/workspaces \
  -H "Authorization: Bearer cnap_pat_abc123..."
```

Workspace-scoped endpoints also require the `X-Workspace-Id` header:

```bash theme={null}
curl https://api.cnap.tech/v1/installs \
  -H "Authorization: Bearer cnap_pat_abc123..." \
  -H "X-Workspace-Id: your-workspace-id"
```

<Card title="Authentication Guide" icon="key" href="/apis/authentication">
  Learn how to create tokens, authenticate with the CLI, and use JWTs
</Card>

## Conventions

The API uses `snake_case` for all field names. This keeps responses consistent regardless of the client language and matches the format you see in curl, logs, and debugging tools.

## Response Format

**Single objects** are returned directly — no wrapper:

```json theme={null}
{
  "id": "j572abc123def456",
  "name": "my-workspace",
  "created_at": 1734567890000
}
```

**List responses** wrap results in `data` with pagination:

```json theme={null}
{
  "data": [
    { "id": "j572abc123def456", "name": "my-workspace", "created_at": 1734567890000 }
  ],
  "pagination": {
    "cursor": "eyJpZCI6...",
    "has_more": true
  }
}
```

**Error responses** use an `error` envelope:

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Install not found"
  }
}
```

## Pagination

List endpoints support cursor-based pagination with two query parameters:

| Parameter | Type    | Default | Description                     |
| --------- | ------- | ------- | ------------------------------- |
| `limit`   | integer | 50      | Items per page (1-100)          |
| `cursor`  | string  | —       | Cursor from a previous response |

To paginate through results:

```bash theme={null}
# First page
curl "https://api.cnap.tech/v1/installs?limit=10" \
  -H "Authorization: Bearer cnap_pat_..."  \
  -H "X-Workspace-Id: ..."

# Next page (use cursor from previous response)
curl "https://api.cnap.tech/v1/installs?limit=10&cursor=eyJpZCI6..." \
  -H "Authorization: Bearer cnap_pat_..." \
  -H "X-Workspace-Id: ..."
```

## Error Codes

| HTTP Status | Code               | Description                    |
| ----------- | ------------------ | ------------------------------ |
| 400         | `bad_request`      | Malformed request              |
| 401         | `unauthorized`     | Missing or invalid token       |
| 403         | `forbidden`        | Not a member of the workspace  |
| 404         | `not_found`        | Resource does not exist        |
| 409         | `conflict`         | Resource already exists        |
| 422         | `validation_error` | Request body failed validation |
| 500         | `internal_error`   | Unexpected server error        |

## Interactive Docs

The API spec is also available as an interactive reference powered by Scalar:

<CardGroup cols={2}>
  <Card title="Scalar API Reference" icon="flask" href="https://api.cnap.tech/v1/docs">
    Interactive API explorer with request builder
  </Card>

  <Card title="OpenAPI Spec" icon="file-code" href="https://api.cnap.tech/v1/openapi.json">
    Raw OpenAPI 3.1 specification (JSON)
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/apis/authentication">
    Create tokens and learn about supported auth methods
  </Card>

  <Card title="CLI" icon="terminal" href="/cli">
    Install the CNAP CLI for terminal-based workflows
  </Card>

  <Card title="Platform MCP" icon="robot" href="/ai/platform-mcp">
    Let AI agents call the API through Code Mode
  </Card>

  <Card title="AI & Agents" icon="plug" href="/ai/index">
    Connect AI tools to CNAP docs and infrastructure
  </Card>
</CardGroup>