API

CoCalc HTTP API and API keys

Use the limited CoCalc HTTP API carefully, and prefer cocalc-cli for most automation.

What the HTTP API is for

The CoCalc HTTP API is for narrow integrations that need to call CoCalc from an external service. It is not the primary automation surface for most CoCalc-ai workflows.

Use the CoCalc CLI first when you are automating CoCalc from a terminal, agent, local script, or development environment. The CLI has richer typed workflows for docs, browser sessions, notebooks, project hosts, and authenticated local development.

API keys in CoCalc-ai

New API keys require at least one explicit capability. Choose only the capabilities needed by the integration. Keys with project:read, project:write, file:read, file:write, project:exec, or codex:run also require at least one allowed project ID. Set that allowlist to the projects the integration needs.

Treat API keys like credentials:

  1. Create keys only for specific integrations.
  2. Give each key a clear name and the smallest useful capability set.
  3. Rotate or delete keys that are no longer needed.
  4. Store keys outside source files, notebooks, chat messages, and terminal history.
  5. For code running inside a project, store external service tokens as project secrets, not as files.

Authentication shape

The HTTP API uses basic authentication. Put the API key in the username field and leave the password blank.

The following command shows the authentication syntax while requesting the /api/v2 reference index. Fetching that index does not verify that a key is valid or permitted to run an operation. Select the intended operation from the reference and follow its documented URL, HTTP method, request fields, and permissions.

curl -u "$COCALC_API_KEY:" https://cocalc.ai/api/v2

For local development, use the local site origin instead of https://cocalc.ai.

When to use something else

Use cocalc-cli for project, browser, docs, notebook, and host workflows when a typed command exists. Use project secrets for credentials consumed by code inside a project. Use Codex or browser-session docs actions when the job is to open or verify a UI destination in the current session.

Why this matters in CoCalc

CoCalc-ai is designed around authenticated, typed control paths instead of one large ambient API key. That keeps the attack surface smaller while still giving humans and agents practical ways to automate the product.