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 have | Use |
|---|---|
| No Cosmic account | POST /v3/agents/sign-up on dapi.cosmicjs.com |
| Bucket slug and keys, writing app code | @cosmicjs/sdk |
| Bucket slug and keys, a terminal or CI | cosmic CLI |
| An MCP client (Cursor, Claude, VS Code, Copilot) | Hosted MCP |
| An existing Cosmic agent to message | POST /v3/ai/agents/:agentId/messages on dapi.cosmicjs.com |
| A site that other agents should ask | CAP: 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}
| Access | Authorization |
|---|---|
| Read | Bearer READ_KEY |
| Read and write | Bearer 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
| Code | Action |
|---|---|
| 400 | Fix the request. Do not retry. |
| 401 | Read or write key is wrong. Do not retry. |
| 402 | Bucket 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. |
| 403 | Not allowed. Do not retry. |
| 404 | Resource is missing. Do not retry. |
| 409 | Conflict, including user_already_exists on signup. Do not retry with a different email. |
| 429 | Rate limit. Back off and retry. Sustained limit is 100 requests/second, burst 200, on uncached requests. |
| 500, 502, 503, 504 | Retry 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
- This page as markdown:
https://www.cosmicjs.com/docs/ai-onboarding.md - Index of every page:
https://www.cosmicjs.com/llms.txt - Full corpus:
https://www.cosmicjs.com/llms-full.txt - 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.