# Developers — Immersive Commons

The agent-native API for Floor 10 of Frontier Tower SF. Three equivalent
surfaces share ONE per-user bearer token: REST, MCP, and A2A. Ten tools are
public (no token).

## Quickstart (device-code, RFC 8628)

1. POST https://www.immersivecommons.com/api/agent/signup/start with a non-empty `scopes` array.
2. Show the human the `user_code`; they approve at https://www.immersivecommons.com/signup-with-agent.
3. Poll https://www.immersivecommons.com/api/agent/signup/poll until you receive an `agt_` bearer.

Send it as `Authorization: Bearer agt_...`. Full walkthrough: https://www.immersivecommons.com/auth.md.

## Surfaces

- MCP (Streamable HTTP): https://www.immersivecommons.com/api/mcp — 138 tools, least glue.
- A2A (JSON-RPC 2.0): https://www.immersivecommons.com/api/a2a
- REST: one HTTP call per action. Spec: https://www.immersivecommons.com/openapi.json (OpenAPI 3.1).
- Docs-MCP surface: https://www.immersivecommons.com/api/mcp-docs (search_docs / get_doc, no auth).
- NLWeb natural-language endpoint: POST https://www.immersivecommons.com/ask ({ "query": "..." }).

## Authentication

Per-user `agt_` bearer tokens, 52 scopes across a 5-tier matrix. Optional
RFC 9421 Ed25519 signed-request upgrade. Machine metadata:
https://www.immersivecommons.com/.well-known/oauth-authorization-server (RFC 8414) +
https://www.immersivecommons.com/.well-known/oauth-protected-resource (RFC 9728). See https://www.immersivecommons.com/auth.md.

## Rate limits

Per-token daily write limits (UTC); reads unmetered within fair use. Full
table: https://www.immersivecommons.com/pricing.md. Everything on this domain is free ($0).

## Sandbox

Add `"sandbox": true` to the `/start` body to mint a TEST-MODE token: reads
serve real data, writes return simulated receipts (no production state),
immutable after mint. A machine-readable descriptor of the sandbox surface
(what it simulates, which endpoints honor it, fail-closed rules) is served
unauthenticated at https://www.immersivecommons.com/api/sandbox. Details: https://www.immersivecommons.com/pricing.md + the
sandbox section of this portal.

## SDKs, CLI, skills

Public repo: https://github.com/immersive-commons/ic-skills (13 skills, installable
via `npx skills add immersive-commons/ic-skills`). Official clients:
`@immersivecommons/sdk` + `@immersivecommons/cli` (npm), `immersivecommons`
(PyPI) — all generated from https://www.immersivecommons.com/openapi.json.

## If something breaks

POST a structured report to https://www.immersivecommons.com/api/agent/feedback. Out-of-band:
admin@immersivecommons.com.