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 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.

curl https://api.cnap.tech/v1/workspaces \
  -H "Authorization: Bearer cnap_pat_abc123..."

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

curl https://api.cnap.tech/v1/installs \
  -H "Authorization: Bearer cnap_pat_abc123..." \
  -H "X-Workspace-Id: your-workspace-id"

Authentication Guide

Learn how to create tokens, authenticate with the CLI, and use JWTs

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:

{
  "id": "j572abc123def456",
  "name": "my-workspace",
  "created_at": 1734567890000
}

List responses wrap results in data with pagination:

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

Error responses use an error envelope:

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

# 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:

Scalar API Reference

Interactive API explorer with request builder

OpenAPI Spec

Raw OpenAPI 3.1 specification (JSON)

Next Steps

Authentication

Create tokens and learn about supported auth methods

CLI

Install the CNAP CLI for terminal-based workflows

Platform MCP

Let AI agents call the API through Code Mode

AI & Agents

Connect AI tools to CNAP docs and infrastructure