Immersive Commons

npx add-mcp 'https://www.immersivecommons.com/api/mcp'

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.

Start a device-code grant

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.

Poll until status = completed

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.

Call an endpoint with your token

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.

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. 01 Device-code flow (agent-driven). The recommended path in the quickstart above — no human credentials touch the agent.
2. 02 Browser 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.

Immersive Commons API Reference (OpenAPI 3.1)

154 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.

Method	Path	Auth · scope	Summary
GET	/api/events/upcoming	public / bearer events:read_upcoming	List upcoming Immersive Commons events
GET	/api/events/get	public	Look up a single event by its Luma URL
GET	/api/events/next	browser session	Cursor-tail the caller's agentic event log
POST	/api/events/rsvp	bearer events:rsvp idempotent	Queue an RSVP to a Luma event
POST	/api/events/request	bearer events:request idempotent	Propose a member event (operator-approved)
GET	/api/events	public	Read upcoming and recent floor events

Method	Path	Auth · scope	Summary
POST	/api/batch	public	Run up to 20 public GET reads in one request

Method	Path	Auth · scope	Summary
GET	/api/directory/search	bearer directory:search	Search the member directory

Method	Path	Auth · scope	Summary
GET	/api/resources/list	bearer resources:read	List bookable resources
POST	/api/resources/book	bearer resources:book idempotent	Queue a resource booking

Method	Path	Auth · scope	Summary
GET	/api/activity/me	bearer membership:read	Read the caller's own activity log

Method	Path	Auth · scope	Summary
GET	/api/leaderboard/me	bearer leaderboard:manage	Read the caller's commit-leaderboard state
POST	/api/leaderboard/optin	bearer leaderboard:manage	Toggle commit-leaderboard opt-in
POST	/api/leaderboard/connect-github	bearer github:link	Link a GitHub identity with a personal access token
POST	/api/user-settings	browser session	Toggle the caller's own leaderboard opt-in

Method	Path	Auth · scope	Summary
POST	/api/research/ask	bearer research:query	Query the research RAG corpus
POST	/api/presentations/ask	public	Retrieval over the public talk archive
GET	/api/research/submissions/pending	browser session	Read the pending research-submission queue
POST	/api/research/submissions/{id}/approve	browser session	Approve a pending research submission
POST	/api/research/submissions/{id}/deny	browser session	Deny a pending research submission

Method	Path	Auth · scope	Summary
POST	/api/ingest/highlights/pending	bearer events:submit_recap idempotent	Submit a highlight to the moderation queue
POST	/api/ingest/highlights/image	bearer events:submit_recap	Host an image for a highlight submission

Method	Path	Auth · scope	Summary
POST	/api/agent/feedback	public / bearer feedback:submit	File feedback, a feature request, or a breakage report
GET	/api/agent/feedback/mine	bearer feedback:read	List the caller's own feedback tickets
GET	/api/agent/feedback/{ticket_id}	bearer admin:feedback_review	Read one feedback ticket
GET	/api/agent/feedback/pending	browser session	Operator browse of the feedback queue
POST	/api/agent/feedback/{ticket_id}/resolve	browser session	Mark a feedback ticket resolved

Method	Path	Auth · scope	Summary
POST	/api/agent/token/revoke	bearer	Self-revoke the presenting token
GET	/api/agent/setup-check	public / bearer	Deterministic 'am I set up?' probe
POST	/api/agent/signup/start	public	Begin the RFC 8628 device-code token mint
POST	/api/agent/sandbox/mint	public	Mint an anonymous sandbox token with no human in the loop
GET	/api/agent/signup/poll	public	Poll a device-code grant for completion
GET	/api/tokens/me	browser session	List the caller's active agent tokens
POST	/api/agent/signup/complete	browser session	Approve (or cancel) a pending device-code signup
GET	/api/sandbox	public	Machine-readable description of the sandbox surface
POST	/api/agent/keys/register	browser session	Bind an Ed25519 public key to one of your agent tokens
POST	/api/agent/keys/revoke	browser session	Unbind the public key from one of your agent tokens
POST	/api/agent/keys/enforce-toggle	browser session	Turn signature enforcement on or off for a bound token

Method	Path	Auth · scope	Summary
GET	/api/floor10/donations	public	Read the public donor wall
POST	/api/x402/donate	public	Donate USDC over x402
POST	/api/x402/research/ask	public	Pay-per-query twin of the research RAG read

Method	Path	Auth · scope	Summary
GET	/api/tier/me	browser session	Read the caller's membership tier
POST	/api/tier/request	browser session	Request a higher membership tier
DELETE	/api/tier/request	browser session	Cancel the pending tier request
GET	/api/membership/profile	browser session	Read the caller's own member profile
POST	/api/membership/profile	browser session	Update the caller's own member profile
GET	/api/tier/pending	browser session	Read the pending-membership queue
POST	/api/tier/approve	browser session	Approve a member into a tier
POST	/api/tier/deny	browser session	Deny a pending tier request
POST	/api/membership/profile/photo	browser session	Set the caller's profile photo
DELETE	/api/membership/profile/photo	browser session	Remove the caller's profile photo

Method	Path	Auth · scope	Summary
GET	/api/funko/m/{handle}	public	Get a member's published Funko Me figure by handle
POST	/api/funko/share	browser session	Publish or unpublish your own Funko Me figure
GET	/api/funko/catalog	public	List the browsable Funko unlock catalog
GET	/api/funko/figures	public	Resolve many public figures in one request
GET	/api/funko/me	browser session	Read the caller's own figure, quota and in-flight run
DELETE	/api/funko/me	browser session	Delete the caller's own figure
GET	/api/funko/progress	browser session	Read the caller's own unlock snapshot
GET	/api/funko/task	browser session	Poll one generation task
POST	/api/funko/run/start	browser session	Claim a run - THE spend gate
POST	/api/funko/run/end	browser session	Mark an in-flight run terminal
POST	/api/funko/view	browser session	Render one orthographic head view (PAID)
POST	/api/funko/inspect	browser session	Second-opinion defect check on a rendered view (never fatal)
POST	/api/funko/mesh	browser session	Reconstruct the head from the rendered views (PAID, the expensive one)
POST	/api/funko/publish	browser session	Park the finished head and write the member's profile
GET	/api/funko/admin	browser session	Read the figure moderation log and the public index
POST	/api/funko/admin	browser session	Take down, restore, or grant generations

Method	Path	Auth · scope	Summary
GET	/api/files/list	bearer files:read	List every vault file the caller may see
POST	/api/files/upload	bearer files:write	Upload a file into the vault
POST	/api/files/grant	bearer files:write	Mint an expiring share-link for one file
PATCH	/api/files/{id}	bearer files:write	Update a file's visibility / grantees / label / description / tags
DELETE	/api/files/{id}	bearer files:write	Delete a file
GET	/api/folders	bearer files:read	Read the vault root — top-level folders plus loose files
POST	/api/folders	bearer files:write	Create a folder
GET	/api/folders/{id}	public / bearer files:read	Traverse one folder
PATCH	/api/folders/{id}	bearer files:write	Update a folder's visibility / grantees / name / description / tags
DELETE	/api/folders/{id}	bearer files:write	Delete an empty folder
POST	/api/folders/grant	bearer files:write	Mint an expiring share-link for a whole folder subtree
GET	/api/folders/shared	public	Resolve a folder share-link to its listing

Method	Path	Auth · scope	Summary
GET	/api/prints/list	bearer prints:read	List the caller's print requests
POST	/api/prints/request	bearer prints:submit	File a 3D-print request with the Floor 10 farm
GET	/api/prints/{id}	bearer prints:read	Read one print request and its full history
PATCH	/api/prints/{id}	bearer prints:manage	Advance a print request through the farm lifecycle
POST	/api/prints/{id}/cancel	bearer prints:submit	Cancel your own print request

Method	Path	Auth · scope	Summary
POST	/api/headsets/checkout	browser session	Borrow a headset unit
POST	/api/headsets/return	browser session	Return a borrowed headset
POST	/api/headsets/report-damage	browser session	File a damage / loss / near-miss incident
POST	/api/headsets/sign-waiver	browser session	Sign the headset-lending waiver
POST	/api/headsets/sop-complete	browser session	Record that you walked another member through the SOP
GET	/api/headsets/attest	browser session	Read an attestation status
POST	/api/headsets/attest	browser session	Sign off another member as headset-trained
DELETE	/api/headsets/attest	browser session	Revoke a member's headset sign-off

Method	Path	Auth · scope	Summary
POST	/api/credits/request	browser session	Get an IC Key with IC Credits (instant at the ring default, queued above it)
GET	/api/credits/status	browser session	Your IC Credits console state, or poll a queued request
POST	/api/credits/pickup	browser session	Claim the once-only plaintext key for a QUEUED request an operator approved
POST	/api/credits/regenerate	browser session	Replace your live IC Key (same budget, spend carried over, old key revoked)
GET	/api/credits/usage	browser session	Your own IC Credits spend
POST	/api/zai-keys/request	browser session	DEPRECATED alias of POST /api/credits/request
GET	/api/zai-keys/status	browser session	DEPRECATED alias of GET /api/credits/status
POST	/api/zai-keys/reveal	browser session	DEPRECATED alias of POST /api/credits/pickup
GET	/api/credits/admin/pending	browser session	Read the pending IC Credits request queue
GET	/api/credits/admin/usage	browser session	Month-to-date IC Credits usage: per provider, per model, per key, last events
POST	/api/credits/admin/approve	browser session	Approve a queued IC Credits request and mint the key
POST	/api/credits/admin/deny	browser session	Deny a queued IC Credits request
POST	/api/credits/admin/set-budget	browser session	Change a live IC Key's monthly IC Credits budget in place
POST	/api/credits/admin/revoke	browser session	Revoke a live IC Key
GET	/api/zai-keys/admin/pending	browser session	DEPRECATED alias of GET /api/credits/admin/pending
GET	/api/zai-keys/admin/usage	browser session	DEPRECATED alias of GET /api/credits/admin/usage
POST	/api/zai-keys/admin/approve	browser session	DEPRECATED alias of POST /api/credits/admin/approve
POST	/api/zai-keys/admin/deny	browser session	DEPRECATED alias of POST /api/credits/admin/deny

Method	Path	Auth · scope	Summary
GET	/api/hack/apply	browser session	Read the question catalog and the caller's own application
POST	/api/hack/apply	browser session	File or update a hackathon application
POST	/api/hack/nda	browser session	Record your own venue NDA signature
GET	/api/hack/photos	browser session	List an event's photo gallery
POST	/api/hack/photos	browser session	Hand in a photo you took at the event
POST	/api/hack/photos/grant	browser session	Mint a partner link to one event's gallery

Method	Path	Auth · scope	Summary
GET	/api/startups	browser session	Discover claimable startup slugs
GET	/api/startups/{slug}/profile	browser session	Read the full owner view of a startup profile
POST	/api/startups/{slug}/profile	browser session	Write a startup's public page
POST	/api/startups/{slug}/news	browser session	Append one news item to a startup profile
POST	/api/startups/{slug}/logo	browser session	Upload a startup logo
DELETE	/api/startups/{slug}/logo	browser session	Remove an uploaded startup logo
GET	/api/startups/{slug}/claim	browser session	Poll the caller's own ownership claim
POST	/api/startups/{slug}/claim	browser session	Ask to be bound as a startup's founder

Method	Path	Auth · scope	Summary
GET	/api/workshop/enroll	browser session	Check whether the caller is already enrolled
POST	/api/workshop/enroll	browser session	Enroll and mint a workshop bearer code
GET	/api/workshop/me	public	Read your enrollment, URLs, recipe and skills in one call
GET	/api/workshop/peers	public	List every other enrolled attendee as an A2A directory
GET	/api/workshop/status	public	Public workshop scoreboard
GET	/api/workshop/submit	public	Read the expected answer shape
POST	/api/workshop/submit	public	Submit the assembled answer
GET	/api/workshop/crosstalk/feed	public	Poll the Crosstalk room's visualization feed
GET	/api/workshop/crosstalk/a2a	public	Discovery hint for the Crosstalk A2A hub
POST	/api/workshop/crosstalk/a2a	public	JSON-RPC 2.0 endpoint for the Crosstalk room
POST	/api/workshop/crosstalk/register	public	One-line registration into the Crosstalk room

Method	Path	Auth · scope	Summary
POST	/api/newsletter/subscribe	public	Subscribe an address to THE SIGNAL

Method	Path	Auth · scope	Summary
GET	/api/floor10/members	public	Read the public floor roster
GET	/api/floor10/resources	public	Read what is on the floor and what is broken
GET	/api/floor10/claimable-events	bearer highlights:submit	List events the caller could write a highlight about
GET	/api/projects	public	Read the projects catalog
GET	/api/communities	public	Read the communities catalog
GET	/api/whats-new	browser session	Read the changelog, filtered to the caller's ring

Method	Path	Auth · scope	Summary
GET	/api/context	browser session	Read the floor's ambient context

Method	Path	Auth · scope	Summary
GET	/api/prints/slicing/queue	public	Poll for print requests that have never been sliced
POST	/api/prints/slicing/result	public	Report one slice outcome
POST	/api/prints/slicing/gcode-chunk	public	Upload one chunk of a sliced G-code
POST	/api/prints/slicing/gcode-commit	public	Reassemble the uploaded chunks into one vault file

Method	Path	Auth · scope	Summary
GET	/api/health	public	Liveness probe
GET	/api/health/kv	public	White-box KV round-trip probe
GET	/api/health/blob	public	White-box blob round-trip probe

Method	Path	Auth · scope	Summary
GET	/api/guests	browser session	Read the pending visitor queue
POST	/api/guests	browser session	File a visitor request as the host

Method	Path	Auth · scope	Summary
POST	/api/floorcast/provision	public	Stand up a new Floorcast tenant

Method	Path	Auth · scope	Summary
POST	/api/upload-media	browser session	Upload a media file to the site blob store

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

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. 01 MCP (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. 02 A2A (JSON-RPC 2.0). Agent-to-agent calls at /api/a2a.
3. 03 Skills. 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.

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.

Mint a sandbox (test-mode) token

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. 01 Reads (list / get / search / status) — real production data.
2. 02 Scoped writes (RSVP, book, submit highlight, set profile, request tier, admin approve/deny) — simulated receipt, no mutation.
3. 03 Feedback & self-revoke — real: a sandbox agent that finds a real bug must be heard, and revoking a token is lifecycle, not floor data.
4. 04 x402 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.