The CloudCannon API An API (Application Programming Interface) is a set of methods and rules that allow one piece of software to interact with another using code to call specific functions for reading data, triggering actions, or responding to events, rather than a graphical interface. A workspace in CloudCannon that groups together Sites, team members, and shared resources. It is also the unit CloudCannon bills for. You can define permissions for your Organization, controlling the access each team member has to resources on CloudCannon. You can create and be a part of multiple Organizations. A way to group multiple Sites from the same Git Repository, allowing you to define a main branch, as well as branching and publishing rules. You can access the Projects Browser using the Projects link in the App Sidebar. A website in CloudCannon that includes all the files, content, configuration, and settings needed to edit, build, and host a complete website. The process of converting all your Site files into a single, functional website using the method specified by your SSG. Building on CloudCannon is optional, but is required for specific features, such as the Visual Editor, preview screenshots for output files in your Collection Browser, and the Testing Domain and Custom Domain.API
Organization
Project
Site
Build
The API is versioned under the /api/v0/ path. While it is on a v0 version, endpoints and fields may change. Deprecated endpoints are marked in this reference.
If CloudCannon changes an endpoint you use, you will receive an email alert. However, we recommend using the SDK, which we update to match changes to the API.
Working with the API#
We recommend working with the CloudCannon API is through one of our official tools, as they handle authentication, request signing, and pagination for you:
- CloudCannon CLI — manage your Organizations, Sites, Builds, files, and form submissions from the terminal.
- TypeScript SDK — a typed client with a sub-client for each resource and built-in pagination, sorting, and filtering.
However, if you need direct access, such as for another language or a use case the tools don't cover, this reference documents the underlying HTTP API.
OpenAPI specification#
This reference is generated from CloudCannon's OpenAPI specification, which is published as a machine-readable document at:
https://app.cloudcannon.com/api/v0/openapi.jsonPoint your tooling at this URL to generate API clients, explore endpoints in a tool like Postman or Insomnia, or give an AI agent the complete, structured definition of every endpoint, parameter, and response in one request.
Download the specification to a file with curl:
curl https://app.cloudcannon.com/api/v0/openapi.json -o openapi.jsonDownloading the specification gives an AI agent or code generator the entire API in a single file, instead of reading this reference page by page.
Base URL#
All API requests are made to:
https://app.cloudcannon.com/api/v0Authentication#
Every request must be authenticated. The CloudCannon API supports two types of credentials:
- API Keys— scoped to an Organization. Best for server-to-server integrations, and the method this reference documents.Glossary term
API Key
A credential that lets programs act on behalf of your Organization through the CloudCannon API, such as a program built with the CloudCannon SDK. An API Key is scoped to the permissions you choose when you create it and belongs to a single Organization. CloudCannon shows the key only once, and you manage your keys on the API Keys page in your Organization Settings.
- Access Keys— scoped to an individual user. Created and used by the CloudCannon CLI to act on that user's behalf.Glossary term
Access Key
A personal credential that lets programs act in CloudCannon on your behalf, such as the CloudCannon CLI or a program built with the CloudCannon SDK. An Access Key is tied to your user account and inherits your full account access across every Organization and Site you belong to. CloudCannon shows the secret only once, when you create the key, and you manage your keys on the Access Keys page in your Account Settings.
API Keys
An API Key authenticates as an Organization and grants access to that Organization's resources, limited to the permissions granted to the key when it was created. A request for an action the key doesn't have permission for returns 403 Forbidden. To create an API Key, please read our documentation on creating an API key, then pass it in the X-API-KEY header on every request:
curl https://app.cloudcannon.com/api/v0/orgs \
-H "X-API-KEY: <your-api-key>"Keep your API Key on your server. It grants access to your Organization, so never expose it in client-side code or commit it to source control.
Many endpoints are scoped to an Organization and include its Organization UUID in the path. Your Organization UUID appears alongside your keys on the API Keys page.
Access Keys
You can only make an Access Key for your own account. Access Keys should never be shared.
An Access Key authenticates as an individual account, with their Permissions across all the Organizations they belong to. You can create an Access Key yourself on the Access Keys page under Account Settings, or let the CloudCannon CLI create one for you when you run cloudcannon login. You can manage or revoke your keys from the same page. Requests made with an Access Key are cryptographically signed; the CLI and SDK handle this for you.
For direct HTTP access we recommend using an API Key. If you need to sign Access Key requests in another language, see the signRequest method in the SDK for a reference implementation of the signing scheme.
Requests without valid credentials return a 401 Unauthorized response.
Pagination#
List endpoints accept page and items query parameters to page through results, and sort_attribute and sort_direction to control ordering. sort_direction accepts ASC or DESC and defaults to DESC. The available sort_attribute values vary by endpoint and are listed with each endpoint's parameters.
curl "https://app.cloudcannon.com/api/v0/orgs/<org_uuid>/sites?page=2&items=50" \
-H "X-API-KEY: <your-api-key>"Rate limiting#
Requests to the API are rate limited by IP address. Requests over the limit receive a 429 Too Many Requests response — back off and retry when you get one. Because the limit is per IP address, requests that share an IP (for example, several keys running from the same CI server) count against the same limit.
Endpoints#
Endpoints are grouped by resource. Select a resource to see its endpoints, parameters, and example requests, or browse them using the navigation on the left.