# Cosmic Documentation

> Cosmic is a headless CMS with a hosted MCP server, in-product AI workflows, and agent signup. An agent can read and write content, generate text, images, video, and audio into the media library, chain content, code, and browser steps, or provision a new project with no existing account.

Capability table: https://www.cosmicjs.com/ai-cms

## For Agents
If you are an AI agent, start at [AI onboarding](https://www.cosmicjs.com/docs/ai-onboarding.md). It is the one-page playbook: signup (`POST /v3/agents/sign-up`), MCP, CLI, skills, and which errors to retry.

Every page is also plain markdown: add `.md` to the URL. Example: [https://www.cosmicjs.com/docs/index.md](https://www.cosmicjs.com/docs/index.md).
Full corpus: [https://www.cosmicjs.com/docs/llms-full.txt](https://www.cosmicjs.com/docs/llms-full.txt).
OpenAPI spec: [https://www.cosmicjs.com/openapi.json](https://www.cosmicjs.com/openapi.json).

## Get started
- [Introduction](https://www.cosmicjs.com/docs/index.md): Get an overview of Cosmic and its features.
- [Quickstart](https://www.cosmicjs.com/docs/quickstart.md): Get up and running with Cosmic quickly.
- [AI onboarding](https://www.cosmicjs.com/docs/ai-onboarding.md): One-page playbook for AI agents: POST /v3/agents/sign-up, hosted MCP URLs, the CLI, `npx skills add cosmicjs/skills`, and which HTTP errors to retry.
- [CLI](https://www.cosmicjs.com/docs/cli.md): Install with `npm i -g @cosmicjs/cli`. `cosmic agent-signup` provisions a project; `cosmic objects`, `cosmic types`, and `cosmic media` then run against that bucket.
- [Agent Skills](https://www.cosmicjs.com/docs/agent-skills.md): Agent onboarding for Cosmic: signup flow that provisions a free-tier project + bucket tied to a human email (POST /v3/agents/sign-up), claim via emailed OTP, plus install of the Cosmic SDK rules file for AI coding assistants.
- [MCP Server](https://www.cosmicjs.com/docs/mcp-server.md): MCP server for managing Cosmic content directly through AI assistants. Hosted endpoints at https://mcp.cosmicjs.com/v1/buckets/{bucket-slug} (bucket tools: objects, media, types, AI gen) and https://mcp.cosmicjs.com/v1/agent (signup tools: cosmic_agent_signup, cosmic_agent_verify, cosmic_agent_status). Self-hosted via `npx @cosmicjs/mcp`.
- [CAP](https://www.cosmicjs.com/docs/cap.md): Every Cosmic account is agent-ready. Publish agent.txt and visiting agents can ask your concierge through the Concierge Agent Protocol.
- [Agent Plugin](https://www.cosmicjs.com/docs/agent-plugin.md): The Cosmic MCP server and Agent Skills packaged as one portable Agent Plugin (agent-plugins.org spec 1.0.0), published at github.com/cosmicjs/cosmic-agent-plugin. One install per client for Cursor, VS Code, GitHub Copilot, and Kiro; not yet supported in ChatGPT/Codex. Declares two MCP servers: `cosmic` (stdio via `npx @cosmicjs/mcp`, reads COSMIC_BUCKET_SLUG / COSMIC_READ_KEY / COSMIC_WRITE_KEY from the environment) and `cosmic-signup` (Streamable HTTP at mcp.cosmicjs.com/v1/agent, no credentials). Ships the `cosmic-sdk` and `cosmic-content-modeling` skills.
- [Frameworks](https://www.cosmicjs.com/docs/frameworks/index.md): Learn how to integrate Cosmic with popular frameworks.
- [Examples](https://www.cosmicjs.com/docs/examples.md): See practical examples of Cosmic implementations.

## Dashboard
- [Introduction](https://www.cosmicjs.com/docs/dashboard/index.md): Cosmic offers a beautiful admin dashboard to create and manage your content.
- [Projects](https://www.cosmicjs.com/docs/dashboard/projects.md): Learn about projects; where you store and manage your Buckets, team members, usage, and billing plans.
- [Buckets](https://www.cosmicjs.com/docs/dashboard/buckets.md): Learn about Buckets; where you manage your Cosmic content, media, extensions, and add-ons.
- [Workspaces](https://www.cosmicjs.com/docs/dashboard/workspaces.md): Learn about workspaces; where you store your projects, manage your team, usage, and billing.
- [Single sign-on](https://www.cosmicjs.com/docs/dashboard/sso.md): SAML single sign-on on Large Workspace and Enterprise: enable a connection, copy ACS URL and Entity ID to your IdP, sign in with Continue with SSO, JIT Workspace User on first login, and password login blocked for members. SCIM is not included yet.
- [Roles and permissions](https://www.cosmicjs.com/docs/dashboard/roles.md): Workspace, Project, and Bucket roles, including inheritance and Contributor Object-type scoping.
- [Audit log](https://www.cosmicjs.com/docs/dashboard/audit-log.md): Append-only audit log of security-relevant actions, read under Usage > Activity > Audit log by Workspace or Project Admins. Covers sign-ins and failed sign-ins, credential changes, Cosmic support access, membership and role changes, API key and token lifecycle, billing changes, content publish and delete, media/Object type/Bucket/Project/Workspace deletion, backup downloads, and webhook, integration, extension and domain changes. AI agent actions are attributed to the agent, with unattended scheduled runs distinguished from human-prompted ones. Filterable by user, action and date range. Retention by plan: 30 days Free and Builder, 90 Team, 180 Business, 365 on Workspace and Enterprise tiers; sign-ins and credential changes are always kept 365 days. Entries cannot be edited or deleted by anyone, including Cosmic staff.
- [Search](https://www.cosmicjs.com/docs/dashboard/search.md): In this guide, we discuss how to use the global search in the Cosmic dashboard.
- [Account](https://www.cosmicjs.com/docs/dashboard/account.md): In this guide, we discuss how to use your account in the Cosmic dashboard.
- [Cosmic Pages](https://www.cosmicjs.com/docs/dashboard/cosmic-pages.md): In this guide, we discuss how to use Cosmic pages in the Cosmic dashboard.
- [Comments](https://www.cosmicjs.com/docs/dashboard/comments.md): Learn how to use Comments for collaborative feedback in your Cosmic Dashboard.
- [AI](https://www.cosmicjs.com/docs/dashboard/ai.md): In this guide, we discuss how to use AI features in the Cosmic dashboard.
- [Agents](https://www.cosmicjs.com/docs/dashboard/ai/agents.md): Agents: capabilities, channels, conversations, and plan limits.
- [Workflows](https://www.cosmicjs.com/docs/dashboard/ai/workflows.md): AI Workflows: chain agents, schedules, event triggers, and execution retention.
- [Application Workflows](https://www.cosmicjs.com/docs/dashboard/application-workflows.md): In this guide, we discuss how to use application workflow features in the Cosmic dashboard for GitHub integration, deployment pipelines, and domain management.
- [Chrome Extension](https://www.cosmicjs.com/docs/chrome-extension.md): Learn about how to use the Cosmic Chrome Extension for easy access to your Cosmic projects.

## Insights
- [Introduction](https://www.cosmicjs.com/docs/insights/index.md): Cosmic Insights: cookieless web analytics for Cosmic-built apps, attributed back to your CMS objects.
- [Events](https://www.cosmicjs.com/docs/insights/events.md): Custom events, conversions, revenue, and promotable fields in Cosmic Insights.
- [Attribution](https://www.cosmicjs.com/docs/insights/attribution.md): How Cosmic Insights attributes pageviews back to objects and traffic sources.
- [Next.js](https://www.cosmicjs.com/docs/insights/nextjs.md): Install Cosmic Insights in a Next.js app (App Router or Pages Router) with the universal script tag.
- [Astro](https://www.cosmicjs.com/docs/insights/astro.md): Install Cosmic Insights in an Astro app with the universal script tag.
- [FAQ](https://www.cosmicjs.com/docs/insights/faq.md): Frequently asked questions about Cosmic Insights.

## API reference
- [Introduction](https://www.cosmicjs.com/docs/api/index.md): Cosmic offers a powerful REST API to interact with your Cosmic content. We recommend using one of the available SDKs which provide an enhanced development experience.
- [Authentication](https://www.cosmicjs.com/docs/api/authentication.md): Bucket read key on GET (`read_key` or Bearer) and write key as `Authorization: Bearer` on POST, PATCH, and DELETE. Keys are in Bucket Settings > API Access.
- [Agent signup](https://www.cosmicjs.com/docs/api/agents.md): REST reference for Agent signup: `POST /v3/agents/sign-up` (provision a project + bucket tied to a human email, no prior account needed), `POST /v3/agents/verify` (submit the OTP from the claim email), `GET /v3/agents/status` (check claim status, limits, and recover bucket keys). Includes the `agent_key` (agk_) auth model and the unclaimed-mode 402 error code `agent_unclaimed_limit`. Not the API for sending messages to an existing agent; that is /docs/api/agent-messages.
- [Agent messages](https://www.cosmicjs.com/docs/api/agent-messages.md): REST reference for talking to an existing Cosmic agent: `POST /v3/ai/agents/:agentId/messages` (Personal Access Token, optional SSE stream), `POST /v3/ai/agents/:agentId/webhook` (per-agent secret), `GET /v3/ai/agents/:agentId/conversations` and `GET .../conversations/:conversationId`. Lives on dapi.cosmicjs.com. Distinct from Agent signup.
- [Request limits](https://www.cosmicjs.com/docs/api/request-limits.md): 100 requests/second sustained and a burst of 200 on uncached requests. Exceeding that returns 429. Timeout is 30s, body size 6MB, media upload up to 900MB.
- [Errors](https://www.cosmicjs.com/docs/api/errors.md): Status codes: 400 fix and do not retry, 401 bad key, 402 upgrade or unclaimed limit, 403 forbidden, 404 missing, 409 do not retry, 429 back off, 5xx retry.
- [Object types](https://www.cosmicjs.com/docs/api/object-types.md): Object type CRUD: GET and POST /v3/buckets/{slug}/object-types, GET/PATCH/DELETE /v3/buckets/{slug}/object-types/:slug.
- [Objects](https://www.cosmicjs.com/docs/api/objects.md): Object CRUD: GET and POST /v3/buckets/{slug}/objects, GET/PATCH/DELETE /v3/buckets/{slug}/objects/:id, POST /objects/batch (max 25), POST /objects/:id/revisions.
- [Preview tokens](https://www.cosmicjs.com/docs/api/preview.md): Short-lived preview_token JWT for dashboard live preview. Pass it with read_key on object and revision reads to get drafts. Issued from the object editor; expires in one hour.
- [Revisions](https://www.cosmicjs.com/docs/api/revisions.md): Revision history: GET /v3/buckets/{slug}/objects/:id/revisions, GET .../revisions/:revision_id, and POST .../revisions.
- [Metafields](https://www.cosmicjs.com/docs/api/metafields.md): Metafield types used to model an Object type: text, rich text, number, media, object relationships, and the rest of the field catalog.
- [Rich text & blocks](https://www.cosmicjs.com/docs/api/rich-text.md): How the `rich-text` Metafield works: values are markdown prose interleaved with `{{shortcode}}` block tokens, served verbatim. Covers the block definition shape (stored at `settings.content_blocks`), the `GET /v3/buckets/{slug}/blocks` endpoint, and rendering with `@cosmicjs/rich-text` (RichText component + per-block component overrides) or a custom renderer via the data-block HTML contract. `rich-text` replaces the deprecated `html-textarea`.
- [Media](https://www.cosmicjs.com/docs/api/media.md): Media CRUD: GET and POST /v3/buckets/{slug}/media (upload up to 900MB), GET/PATCH/DELETE /v3/buckets/{slug}/media/:id.
- [AI](https://www.cosmicjs.com/docs/api/ai.md): Generate content with a write key: POST /v3/buckets/{slug}/ai/text, /ai/image, /ai/video, /ai/video/extend, and /ai/audio.
- [Semantic search](https://www.cosmicjs.com/docs/api/content-rag.md): Content RAG semantic (vector) search: `POST /v3/buckets/{slug}/ai/search` embeds a natural-language `query` and returns the most semantically relevant objects in the bucket (ranked by score, with optional `type`/`locale`/`status`/`limit`/`min_score` filters and a text `snippet`). Requires a bucket write key; enabled per account. Embedding content on write is free; query-time search is metered as AI tokens. Complements keyword/structured Queries and powers the agent `search_content` tool. Distinct from ⌘K dashboard search.
- [Queries](https://www.cosmicjs.com/docs/api/queries.md): Structured filters for Objects and media via the `query` parameter on GET /v3/buckets/{slug}/objects and /media.
- [Webhooks](https://www.cosmicjs.com/docs/api/webhooks.md): Webhook POST payload (`resource`, `event`, `triggered_at`, `data`) sent when dashboard or API events fire. Create them in Bucket Settings > Webhooks.
- [Localization](https://www.cosmicjs.com/docs/api/localization.md): Localized Objects share a slug and count as one Object. Fetch them with `locale` on GET /v3/buckets/{slug}/objects.

## OpenAPI
- [OpenAPI spec](https://www.cosmicjs.com/openapi.json): Machine-readable REST API for api.cosmicjs.com/v3.