cosmicjs.com

# Cosmic Documentation

## For Agents
If you are an AI agent: start at <https://www.cosmicjs.com/docs/agent-skills.md>. It includes a one-curl signup flow (`POST /v3/agents/sign-up`) that provisions a free-tier Cosmic project + bucket tied to a human's email, without any prior account.

## Introduction
You can access all of our documentation as plain text markdown files by adding `.md` to the end of any url.
For example, you can find the plain text version of the docs homepage at <https://www.cosmicjs.com/docs/index.md>.
For a single concatenated dump of every docs page, see <https://www.cosmicjs.com/docs/llms-full.txt>.

## 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.
- [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`.
- [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): Understand how to use the introduction section of the Cosmic dashboard.
- [Projects](https://www.cosmicjs.com/docs/dashboard/projects.md): Understand how to use the projects section of the Cosmic dashboard.
- [Buckets](https://www.cosmicjs.com/docs/dashboard/buckets.md): Understand how to use the buckets section of the Cosmic dashboard.
- [Workspaces](https://www.cosmicjs.com/docs/dashboard/workspaces.md): Understand how to use the workspaces section of the Cosmic dashboard.
- [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): Understand how to use the search section of the Cosmic dashboard.
- [Account](https://www.cosmicjs.com/docs/dashboard/account.md): Understand how to use the account section of the Cosmic dashboard.
- [Cosmic Pages](https://www.cosmicjs.com/docs/dashboard/cosmic-pages.md): Understand how to use the cosmic pages section of the Cosmic dashboard.
- [AI](https://www.cosmicjs.com/docs/dashboard/ai.md): Understand how to use the ai section of the Cosmic dashboard.
- [Agents](https://www.cosmicjs.com/docs/dashboard/ai/agents.md): Understand how to use the agents section of the Cosmic dashboard.
- [Workflows](https://www.cosmicjs.com/docs/dashboard/ai/workflows.md): Understand how to use the workflows section of the Cosmic dashboard.
- [Application Workflows](https://www.cosmicjs.com/docs/dashboard/application-workflows.md): Understand how to use the application workflows section of the Cosmic dashboard.
- [Chrome Extension](https://www.cosmicjs.com/docs/chrome-extension.md): Explore chrome extension in Cosmic.

## API reference
- [Introduction](https://www.cosmicjs.com/docs/api/index.md): Explore introduction in Cosmic.
- [Authentication](https://www.cosmicjs.com/docs/api/authentication.md): Reference for the authentication API endpoint and functionality.
- [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): Reference for the request limits API endpoint and functionality.
- [Errors](https://www.cosmicjs.com/docs/api/errors.md): Reference for the errors API endpoint and functionality.
- [Object types](https://www.cosmicjs.com/docs/api/object-types.md): Reference for the object types API endpoint and functionality.
- [Objects](https://www.cosmicjs.com/docs/api/objects.md): Reference for the objects API endpoint and functionality.
- [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): Reference for the revisions API endpoint and functionality.
- [Metafields](https://www.cosmicjs.com/docs/api/metafields.md): Reference for the metafields API endpoint and functionality.
- [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): Reference for the media API endpoint and functionality.
- [AI](https://www.cosmicjs.com/docs/api/ai.md): Reference for the ai API endpoint and functionality.
- [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): Reference for the queries API endpoint and functionality.
- [Webhooks](https://www.cosmicjs.com/docs/api/webhooks.md): Reference for the webhooks API endpoint and functionality.
- [Localization](https://www.cosmicjs.com/docs/api/localization.md): Reference for the localization API endpoint and functionality.