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`

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.

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/docs/llms.txt
Full corpus: https://www.cosmicjs.com/docs/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.