immersivecommons.com
Developer Portal

§ 01 · Quickstart

Immersive Commons API Quickstart

Token in three calls. Authentication is the RFC 8628 device-code flow: no human credentials ever reach your agent. Your agent starts the grant, a signed-in human approves it in a browser, then your agent polls for the minted token. The full walkthrough — scopes, deviations from stock RFC 8628, signed requests — is at /auth.md.

1. Start the grant. Request the narrowest scopes your workflow needs.

curl -sX POST https://www.immersivecommons.com/api/agent/signup/start \
  -H 'content-type: application/json' \
  -d '{"scopes":["read:public","events:read_upcoming"],"client_name":"My Agent"}'

2. Send the human to approve. The response carries verify_url_complete (or verify_url plus a short user_code). They approve at the agent console while signed in.

3. Poll for the token. Poll every interval seconds. On approval the response returns agent_token exactly once — store it immediately; later polls return 410.

curl -s 'https://www.immersivecommons.com/api/agent/signup/poll?device_code=<device_code>'

4. Call the API. Send the token as Authorization: Bearer agt_... to REST, MCP, or A2A.

curl -s https://www.immersivecommons.com/api/events/upcoming \
  -H 'authorization: Bearer agt_...'

On write endpoints, add an Idempotency-Key header so a network retry replays the first result instead of creating a second side effect (24-hour window, honored server-side). It layers on top of each endpoint's own semantic dedupe — see the endpoint reference below for which operations accept it.

§ 02 · Authentication & API keys

Immersive Commons API Authentication & Keys

Agent tokens are the API keys. There is no separate API-key system. The credential is a per-member, individually revocable bearer token of the form agt_<base64url>. The server stores only a SHA-256 of it; the plaintext is shown once at mint time. Two ways to get one:

1. 01Device-code flow (agent-driven). The recommended path in the quickstart above — no human credentials touch the agent.
2. 02Browser mint (human-driven). A human signs in at the agent console, picks scopes, clicks Mint, and pastes the token into the agent's environment. The same console is where any of your tokens can be revoked.

Tokens carry least-privilege scopes; each operation names the scope it enforces. Scopes cannot be added to an existing token — to widen access, re-register for a new one. The full scope catalog (id, description, tier) is machine-readable at /.well-known/ai-agent.json. Optionally upgrade a bearer to bearer-plus-Ed25519-signature (RFC 9421) so a leaked token alone is useless — details in /auth.md.

§ 03 · Endpoint reference

Immersive Commons API Reference (OpenAPI 3.1)

169 operations, one source of truth. This reference is generated at build time from /openapi.json — the OpenAPI 3.1.1 document your agent can consume directly (version 2026-09-15). It never drifts from what the server serves. Every operation binds to a real route handler; the scope column is the IC scope the handler enforces. Operations tagged browser session are Clerk-cookie only and are not reachable with an agt_ token — agents use the equivalent MCP tool.

§ 04 · Rate limits

Immersive Commons API Rate Limits

Free, not unlimited. Reads are unmetered within fair use. Write verbs carry per-token daily ceilings (UTC). These figures are sourced from the machine-readable /pricing.md; a 429 response carries a Retry-After header.

• Highlight submissions3 / token / day
• Image uploads30 / token / day (8 MB each)
• Event RSVPs10 / token / day
• Resource bookings10 / token / day
• Transcription jobs5 / token / day
• Research queries60 / member / hour
• Feedback reports (anonymous)10 / IP / hour

§ 05 · Protocols & skills

Immersive Commons MCP Server (A2A & REST)

Three transports, one API. The same capabilities are reachable however your agent is wired. Point your client at whichever transport it speaks:

1. 01MCP (Streamable HTTP). Add /api/mcp to your MCP client and paste agt_... in the Authorization header. A no-auth docs surface also lives at /api/mcp-docs.
2. 02A2A (JSON-RPC 2.0). Agent-to-agent calls at /api/a2a.
3. 03Skills. Portable, runtime-agnostic skill definitions are indexed at /.well-known/agent-skills/index.json and installable from the public ic-skills repo (npx skills add immersive-commons/ic-skills), listed on skills.sh, which also ships the official SDK + CLI packages: @immersivecommons/sdk + @immersivecommons/cli + @immersivecommons/mcp (npm), immersivecommons (PyPI), and ic-go (Go), and immersivecommons (RubyGems). Docs are also mirrored at immersivecommons.mintlify.app.

Prefer to orient first? The full machine manifest — scope catalog, endpoints, rate limits — is at /.well-known/ai-agent.json, and the prose registration guide is /auth.md. Agent-readable context for the whole site is at /llms.txt.

§ 06 · Sandbox

Immersive Commons API Sandbox

Try writes without side effects. Getting started is free and self-serve: the default public tier costs $0, you mint your own token in the quickstart above, and a sandbox lets you exercise write verbs safely before you point them at live data.

A sandbox token is a normal agent token minted through the same human-approved device-code flow, with one flag flipped. It carries real scopes and authenticates like any token — the only difference is that write verbs return a simulated receipt instead of mutating anything, while reads serve real production data. Sandbox is a property of the token, not the URL: same endpoints, same agt_ format, same auth header.

To mint one, add "sandbox": true to the device-code start body, then complete the flow exactly as normal. The poll completion echoes sandbox: true so you can confirm what you received. The flag is immutable after mint — a test token can never silently become a live one; production write access means minting a new token through the same approval.

curl -sX POST https://www.immersivecommons.com/api/agent/signup/start \
  -H 'content-type: application/json' \
  -d '{"scopes":["events:read_upcoming","events:rsvp"],"client_name":"my-agent (sandbox)","sandbox":true}'

A machine-readable descriptor of the sandbox — what it simulates, which endpoints honor it, and its fail-closed rules — is served unauthenticated at /api/sandbox. Fetch it to discover the test surface before you mint a token. Standalone sandbox docs page: /sandbox (markdown twin at /sandbox.md).

A simulated write returns { ok: true, sandbox: true, simulated: true, would_have: {…} }, where would_have echoes the action, the scope that was checked, and your validated arguments. Read the receipt honestly: sandbox verifies your token holds the required scope, but does not run the deeper business-rule gates (live tier, floor-admin role, resource ownership, request signature) that the real call would. A green sandbox receipt means “well-formed and scoped,” not “guaranteed to succeed in production.”

1. 01Reads (list / get / search / status) — real production data.
2. 02Scoped writes (RSVP, book, submit highlight, set profile, request tier, admin approve/deny) — simulated receipt, no mutation.
3. 03Feedback & self-revoke — real: a sandbox agent that finds a real bug must be heard, and revoking a token is lifecycle, not floor data.
4. 04x402 donations & floor-admin toggles — not sandbox-eligible: a real payment rail is never faked, and anything the sandbox cannot prove it may safely simulate fails closed rather than risk a real mutation.