API Reference

We offer a powerful REST API to interact with your Cosmic content. We recommend using one of the available SDKs which provide an enhanced development experience.

API base URL

The base URL for all requests is noted below.

Base URL

https://api.cosmicjs.com

API status

You can check the API status at the following endpoint. You can also subscribe to status updates on the Cosmic status page.

Status endpoint

https://api.cosmicjs.com/v3/status

The following examples include methods using the Cosmic JavaScript SDK. To run the examples, first install the NPM module using one of the following commands. Make sure you have Node.js installed on your machine (recomended version: v18.*).

Install the Cosmic JavaScript SDK

yarn add @cosmicjs/sdk
# OR
pnpm add @cosmicjs/sdk
# OR
npm install @cosmicjs/sdk
# OR
bun add @cosmicjs/sdk

Install the Swift SDK

In certain cases, there are also methods that use the Cosmic Swift SDK. To run the examples, first install the Swift package using Swift Package Manager.

Install the Cosmic Swift SDK

.package(url: "https://github.com/cosmicjs/cosmic-sdk-swift.git", from: "1.0.0")

FAQ

What is the base URL?

https://api.cosmicjs.com/v3

Where is the OpenAPI document?

https://www.cosmicjs.com/openapi.json

How much does Cosmic cost?

Project plans are Free ($0), Builder ($99/mo), Team ($299/mo), Business ($499/mo), Enterprise (custom pricing). Yearly billing saves 10%. Workspace plans are Small Workspace ($999/mo) and Large Workspace ($2,999/mo), and they start with a 30-day free trial. Allowances, add-on rates, and the rest of the pricing FAQ are plain text at https://www.cosmicjs.com/pricing.md.

Are API keys required, and is content private?

Each Bucket has a read key and a write key in Bucket Settings > API Access. GET requests use the read key. POST, PATCH, and DELETE use the write key as Authorization: Bearer. Do not put the write key in a browser bundle, a mobile app, or a NEXT_PUBLIC_ variable. SAML single sign-on is on Large Workspace and Enterprise. The audit log is append-only. Text versions: https://www.cosmicjs.com/security.md and https://www.cosmicjs.com/docs/dashboard/audit-log.md.

Can an agent create a Cosmic project without an existing account?

Yes. POST https://dapi.cosmicjs.com/v3/agents/sign-up provisions a free-tier project and bucket tied to a human email, with no existing Cosmic account. The human claims it with the emailed one-time code. The playbook is https://www.cosmicjs.com/docs/ai-onboarding.md.