AI onboarding

Everything an AI agent needs to start using Cosmic. Humans can follow it too. The long form of signup, credentials, and claim states is Agent Skills.

Choose a path

You haveUse
No Cosmic accountPOST /v3/agents/sign-up on dapi.cosmicjs.com
Bucket slug and keys, writing app code@cosmicjs/sdk
Bucket slug and keys, a terminal or CIcosmic CLI
An MCP client (Cursor, Claude, VS Code, Copilot)Hosted MCP
An existing Cosmic agent to messagePOST /v3/ai/agents/:agentId/messages on dapi.cosmicjs.com
A site that other agents should askCAP: publish agent.txt, then they message your concierge

Prefer the SDK or CLI over raw HTTP when you are writing application code. Use the signup call only when the human does not already have a bucket.

Agent signup

A human email is required. The call provisions a free-tier project and bucket with no prior account. The project starts unclaimed: 50 objects, 5 MB of media, no AI credits, and it is deleted after 14 days unless the human verifies.

curl -X POST https://dapi.cosmicjs.com/v3/agents/sign-up \
  -H "Content-Type: application/json" \
  -d '{
    "human_email": "tony@example.com",
    "project_name": "Recipe Blog",
    "agent_id": "my-agent-platform"
  }'

The response includes agent_key (agk_...) for verify and status, an access_token for the dashboard API, and bucket.read_key / bucket.write_key for content. Ask the human for the 6-digit code from the claim email, then:

curl -X POST https://dapi.cosmicjs.com/v3/agents/verify \
  -H "Authorization: Bearer agk_..." \
  -H "Content-Type: application/json" \
  -d '{ "code": "123456" }'

If human_email is already a Cosmic user, signup returns 409 with user_already_exists. Stop and ask the human to log in and share a bucket key. Do not retry with a different email.

The same flow is cosmic agent-signup, cosmic agent-verify, and the MCP tools cosmic_agent_signup / cosmic_agent_verify / cosmic_agent_status. Full credential table: Agent Skills. Endpoint reference: Agent signup.

MCP server

Connect a client that already has a bucket:

https://mcp.cosmicjs.com/v1/buckets/{bucket-slug}
AccessAuthorization
ReadBearer READ_KEY
Read and writeBearer READ_KEY:WRITE_KEY

Signup, with no bucket yet:

https://mcp.cosmicjs.com/v1/agent

That server exposes cosmic_agent_signup, cosmic_agent_verify, and cosmic_agent_status. Self-host with npx @cosmicjs/mcp. Install the MCP server and the skills together with the Agent Plugin. Setup for each client is on the MCP server page.

CLI

npm i -g @cosmicjs/cli

cosmic agent-signup --email tony@example.com --project "Recipe Blog" --agent-id my-agent
cosmic agent-verify 123456
cosmic objects
cosmic types create

After agent-signup the CLI is logged into the new bucket. cosmic whoami labels an agent session. Command reference: CLI.

Skills

Skills teach the agent how to model content and call the SDK. Install them in the project:

npx skills add cosmicjs/skills

In Cursor, VS Code, GitHub Copilot, or Kiro, the Agent Plugin installs these skills and the MCP server in one step.

Errors and retries

CodeAction
400Fix the request. Do not retry.
401Read or write key is wrong. Do not retry.
402Bucket needs an upgrade, or an unclaimed agent hit agent_unclaimed_limit (50 objects, 5 MB media, no AI). Verify the human, or stay inside the limit. Do not retry the same call.
403Not allowed. Do not retry.
404Resource is missing. Do not retry.
409Conflict, including user_already_exists on signup. Do not retry with a different email.
429Rate limit. Back off and retry. Sustained limit is 100 requests/second, burst 200, on uncached requests.
500, 502, 503, 504Retry with backoff.

Retry only 429 and 5xx. Use exponential backoff (1s, 2s, 4s) and stop after 3 to 5 attempts. Details: Errors and Request limits.

Docs for agents

  1. This page as markdown: https://www.cosmicjs.com/docs/ai-onboarding.md
  2. Index of every page: https://www.cosmicjs.com/llms.txt
  3. Full corpus: https://www.cosmicjs.com/llms-full.txt
  4. OpenAPI spec: https://www.cosmicjs.com/openapi.json

Any docs URL accepts a .md suffix. Fetch the index before opening a second page.

FAQ

Which errors should an agent retry?

Retry 429 after backing off, and retry 5xx. Do not retry 400, 401, 403, 404, or 409. A 402 means a plan limit or an unclaimed agent limit.

Where does an agent with no bucket start?

POST /v3/agents/sign-up on https://dapi.cosmicjs.com, or the hosted MCP tools at https://mcp.cosmicjs.com/v1/agent (cosmic_agent_signup, cosmic_agent_verify, cosmic_agent_status).

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.