Immersive Commons Headsets API

openapi: 3.2.0
info:
  title: Immersive Commons — Agent REST Headsets API
  version: '2026-09-15'
  summary: The REST surface an AI agent uses to act at Immersive Commons.
  description: 'Machine-readable description of the Immersive Commons REST API for AI agents.


    **Authentication.** Most operations take a Bearer agent token (`Authorization: Bearer agt_...`). Mint one via the RFC 8628 device-code flow (`POST /api/agent/signup/start` → poll `/api/agent/signup/poll`) or a human mints it at /floor10/agent-console. Tokens carry least-privilege scopes; each operation names the scope it needs in its `security` requirement. Public reads allow anonymous access (empty security requirement). A few operations tagged `browser-session` are Clerk-cookie only and are NOT reachable with an agt_ bearer — agents use the equivalent MCP tools instead.


    **Error model.** Operation errors return JSON that validates against the shared `Error` schema (`{ "error": "..." }`, optionally `ok:false`/`error_kind`/`rate`/`retry_after_seconds`). Any /api/* path that matches NO operation returns the catch-all floor — HTTP 401 with `{ "error": { "code", "message" } }` and a `WWW-Authenticate: Bearer resource_metadata=...` header pointing at /.well-known/oauth-protected-resource.


    **Idempotency.** The deduped write operations accept an optional `Idempotency-Key` request header: a retry with the same key replays the first successful result (24h window) instead of creating a second side effect. This layers on top of each endpoint''s own semantic dedupe (e.g. RSVP''s 7-day window).


    **Versioning & deprecation policy.** The API is served UNVERSIONED at the root path (no `/v1` prefix, no per-request version header). The dated `info.version` (CalVer) is the change marker to pin against. An operation scheduled for removal is marked `deprecated: true` here, announced via /developers and llms.txt, and kept at least one release. Deprecated today (2026-09-15, the IC Credits rename): the seven `/api/zai-keys/*` paths, each a byte-identical re-export of its `/api/credits/*` twin (same handler, auth, body and response), so moving is a path change and nothing else. Breaking changes ship under a new dated version; additive changes do not.


    **Rate limits.** Agent tokens are limited per-token per endpoint family (e.g. 3 highlight submissions/day, 60 research queries/hour). 429 responses carry a `Retry-After` header. Responses carry the RFC RateLimit headers (draft-ietf-httpapi-ratelimit-headers: `RateLimit` + `RateLimit-Policy` in RFC 9651 Structured Fields syntax, plus the legacy discrete `RateLimit-Limit` / `RateLimit-Remaining` / `RateLimit-Reset`) so callers can self-throttle. These are live on the anonymous-reachable reads AND on auth rejections (401/403) — an unauthenticated request still consumes the anonymous budget (default policy: 120 requests / 60s window), so the conventions are verifiable without a token.'
  contact:
    name: Immersive Commons
    email: admin@immersivecommons.com
    url: https://www.immersivecommons.com/developers
  license:
    name: Proprietary
    url: https://www.immersivecommons.com/privacy
servers:
- url: https://www.immersivecommons.com
  description: Production
- url: https://www.immersivecommons.com
  description: Sandbox (test mode) — same base URL; mint a sandbox token via `sandbox:true` on /api/agent/signup/start. Writes return simulated receipts, reads serve real data.
  x-sandbox: token-flag
security:
- {}
tags:
- name: headsets
  description: 'Headset lending: waivers, attestation, checkout, incidents.'
paths:
  /api/headsets/checkout:
    post:
      operationId: checkoutHeadset
      tags:
      - headsets
      summary: Borrow a headset unit
      description: Clerk-session only (NOT reachable with an agt_ bearer), ic-member+. Opens a lend record against `unit_id` and returns its due-back time. A signed waiver is a precondition — without one this answers 412.
      security:
      - clerkSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HeadsetCheckoutRequest'
      responses:
        '200':
          description: Lend opened.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeadsetCheckoutResponse'
        '400':
          description: Invalid JSON or missing unit_id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Not signed in.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: ic-member tier required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such unit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: The caller already has an open lend, or the unit is not available.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '412':
          description: No signed waiver on file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Lending store unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ic-route:
        file: app/api/headsets/checkout/route.ts
        method: POST
  /api/headsets/return:
    post:
      operationId: returnHeadset
      tags:
      - headsets
      summary: Return a borrowed headset
      description: 'Clerk-session only (NOT reachable with an agt_ bearer), ic-member+. Closes the lend and reports the unit''s resulting status. Only the borrower or an operator may close a lend. Setting `damaged: true` returns the unit out-of-service rather than available.'
      security:
      - clerkSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HeadsetReturnRequest'
      responses:
        '200':
          description: Lend closed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeadsetReturnResponse'
        '400':
          description: Invalid JSON or missing lend_id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Not signed in.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Neither the borrower nor an operator.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such lend.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: That lend is already closed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Lending store unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ic-route:
        file: app/api/headsets/return/route.ts
        method: POST
  /api/headsets/report-damage:
    post:
      operationId: reportHeadsetDamage
      tags:
      - headsets
      summary: File a damage / loss / near-miss incident
      description: Clerk-session only (NOT reachable with an agt_ bearer), ic-member+. Writes the incident record; the Telegram fan-out to ops is done out-of-band by a node-side timer, so a 200 here means RECORDED, not 'someone has seen it'.
      security:
      - clerkSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HeadsetDamageRequest'
      responses:
        '200':
          description: Incident recorded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeadsetDamageResponse'
        '400':
          description: Invalid JSON, unknown `type`, or unknown `reporter_role`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Not signed in.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: ic-member tier required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: Attached photo too large.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Incident store unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ic-route:
        file: app/api/headsets/report-damage/route.ts
        method: POST
  /api/headsets/sign-waiver:
    post:
      operationId: signHeadsetWaiver
      tags:
      - headsets
      summary: Sign the headset-lending waiver
      description: Clerk-session only (NOT reachable with an agt_ bearer), ic-member+. One-time, version-gated, and a precondition for checkout. The signer's ring is derived SERVER-SIDE from their live tier — a `ring` field in the body is never trusted. `photo_consent` is tri-state and anything other than "yes"/"no" is recorded as "unset".
      security:
      - clerkSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HeadsetWaiverRequest'
      responses:
        '200':
          description: Waiver recorded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeadsetWaiverResponse'
        '400':
          description: Invalid JSON or a rejected field (name / email / typed signature).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Not signed in.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: ic-member tier required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Waiver store unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ic-route:
        file: app/api/headsets/sign-waiver/route.ts
        method: POST
  /api/headsets/sop-complete:
    post:
      operationId: markHeadsetSopComplete
      x-sandbox: simulated
      tags:
      - headsets
      summary: Record that you walked another member through the SOP
      description: Clerk session, or agt_ token with `headsets:lend` (live tier re-checked). The CALLER must already be attested. Records the runthrough for `subject_user_id`; it is deliberately a separate event from the sign-off (POST /api/headsets/attest) so the audit trail keeps both timestamps. You cannot name yourself as the subject.
      security:
      - clerkSession: []
      - agentBearer:
        - headsets:lend
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HeadsetSopCompleteRequest'
      responses:
        '200':
          description: SOP runthrough recorded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeadsetAttestationResponse'
        '400':
          description: Invalid JSON, missing subject_user_id, or the subject is the caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No auth.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The caller is not attested.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ic-route:
        file: app/api/headsets/sop-complete/route.ts
        method: POST
  /api/headsets/attest:
    get:
      operationId: getHeadsetAttestation
      tags:
      - headsets
      summary: Read an attestation status
      description: Clerk session, or agt_ token with `headsets:lend`. Defaults to the caller; pass `user_id` to read someone else's. `is_attested` folds in the operator-default rule, so it can be true with a null `record`.
      security:
      - clerkSession: []
      - agentBearer:
        - headsets:lend
      parameters:
      - name: user_id
        in: query
        required: false
        schema:
          type: string
        description: Clerk user id to read. Defaults to the caller.
      responses:
        '200':
          description: Attestation status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeadsetAttestationStatusResponse'
        '401':
          description: No auth.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Scope/tier not authorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ic-route:
        file: app/api/headsets/attest/route.ts
        method: GET
    post:
      operationId: attestHeadsetMember
      x-sandbox: simulated
      tags:
      - headsets
      summary: Sign off another member as headset-trained
      description: Clerk session, or agt_ token with `headsets:lend` (live tier re-checked). The CALLER must already be attested — operators are attested by default. Self-attestation is refused. The subject's display name is snapshotted from Clerk onto the record.
      security:
      - clerkSession: []
      - agentBearer:
        - headsets:lend
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HeadsetAttestRequest'
      responses:
        '200':
          description: Attestation recorded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeadsetAttestationResponse'
        '400':
          description: Invalid JSON, missing subject_user_id, or an attempt to attest yourself.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No auth.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The caller is not attested.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ic-route:
        file: app/api/headsets/attest/route.ts
        method: POST
    delete:
      operationId: revokeHeadsetAttestation
      x-sandbox: simulated
      tags:
      - headsets
      summary: Revoke a member's headset sign-off
      description: 'Clerk session, or agt_ token with `headsets:lend` (live tier re-checked). The CALLER must already be attested. Idempotent: revoking someone who had no record still returns 200, with `was_present: false` and no `record`.'
      security:
      - clerkSession: []
      - agentBearer:
        - headsets:lend
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HeadsetRevokeAttestRequest'
      responses:
        '200':
          description: Revoked (or there was nothing to revoke).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeadsetRevokeAttestResponse'
        '400':
          description: Invalid JSON or missing subject_user_id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No auth.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The caller is not attested.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ic-route:
        file: app/api/headsets/attest/route.ts
        method: DELETE
components:
  schemas:
    HeadsetWaiverRequest:
      type: object
      required:
      - name
      - signature_typed
      description: The signer's ring is derived server-side from their live tier; a `ring` field here is ignored.
      properties:
        name:
          type: string
        email:
          type: string
        phone:
          type: string
        telegram:
          type: string
        signature_typed:
          type: string
          description: The typed signature.
        photo_consent:
          type: string
          enum:
          - 'yes'
          - 'no'
          - unset
          description: Anything other than yes/no is recorded as unset.
    HeadsetAttestationStatusResponse:
      type: object
      required:
      - ok
      - user_id
      - is_attested
      properties:
        ok:
          type: boolean
        user_id:
          type: string
          description: The member this answer is about.
        is_attested:
          type: boolean
          description: Folds in the operator-default rule, so it can be true while `record` is null.
        record:
          oneOf:
          - $ref: '#/components/schemas/HeadsetAttestationRecord'
          - type: 'null'
          description: The stored record, or null when there has never been one.
    HeadsetReturnResponse:
      type: object
      required:
      - ok
      properties:
        ok:
          type: boolean
        unit_status:
          type: string
          description: The unit's status after the return.
    HeadsetReturnRequest:
      type: object
      required:
      - lend_id
      properties:
        lend_id:
          type: string
        damaged:
          type: boolean
          description: True returns the unit out-of-service instead of available. Defaults to false.
    HeadsetCheckoutResponse:
      type: object
      required:
      - ok
      - lend_id
      properties:
        ok:
          type: boolean
        lend_id:
          type: string
          description: Pass this to /api/headsets/return.
        due_back_at:
          type: string
          format: date-time
    HeadsetCheckoutRequest:
      type: object
      required:
      - unit_id
      properties:
        unit_id:
          type: string
          description: The headset unit to borrow (e.g. IC3).
    HeadsetRevokeAttestRequest:
      type: object
      required:
      - subject_user_id
      properties:
        subject_user_id:
          type: string
        reason:
          type: string
    HeadsetAttestRequest:
      type: object
      required:
      - subject_user_id
      properties:
        subject_user_id:
          type: string
          description: Clerk user id to sign off. May not be yourself.
        notes:
          type: string
    HeadsetAttestationRecord:
      type: object
      description: The stored attestation for one member — who signed them off, when, and any notes.
      additionalProperties: true
      properties:
        subject_user_id:
          type: string
        subject_name:
          type: string
        by_user_id:
          type: string
        by_name:
          type: string
        notes:
          type: string
        attested:
          type: boolean
        attested_at:
          type: string
          format: date-time
        sop_completed_at:
          type: string
          format: date-time
    HeadsetWaiverResponse:
      type: object
      required:
      - ok
      properties:
        ok:
          type: boolean
        record_id:
          type: string
        expires_at:
          type: string
          format: date-time
          description: When the waiver must be re-signed.
    HeadsetAttestationResponse:
      type: object
      required:
      - ok
      - record
      properties:
        ok:
          type: boolean
        record:
          $ref: '#/components/schemas/HeadsetAttestationRecord'
    HeadsetRevokeAttestResponse:
      type: object
      required:
      - ok
      - was_present
      properties:
        ok:
          type: boolean
        was_present:
          type: boolean
          description: False when there was no attestation to revoke — still a 200.
        record:
          $ref: '#/components/schemas/HeadsetAttestationRecord'
    HeadsetDamageResponse:
      type: object
      required:
      - ok
      properties:
        ok:
          type: boolean
        incident_id:
          type: string
          description: Quote this to ops when following up.
    HeadsetDamageRequest:
      type: object
      required:
      - type
      - reporter_role
      properties:
        type:
          type: string
          enum:
          - lens
          - shell
          - controller
          - battery
          - hygiene
          - loss
          - near-miss
          - other
        reporter_role:
          type: string
          enum:
          - ops-staff
          - borrower
          - member
        unit:
          type: string
          description: The unit involved, if known.
        lend_id:
          type: string
          description: The lend it happened under, if known.
        borrower:
          type: string
        description:
          type: string
        photo:
          type: string
          description: Data URL or blob reference. Oversized attachments are a 413.
        reporter_name:
          type: string
        reporter_contact:
          type: string
    HeadsetSopCompleteRequest:
      type: object
      required:
      - subject_user_id
      properties:
        subject_user_id:
          type: string
          description: Clerk user id of the member you walked through the SOP. May not be yourself.
    Error:
      type: object
      required:
      - error
      additionalProperties: true
      description: Structured JSON error. `error` (string) is always present — an error code or a human-readable message. `ok:false` is present on bearer auth-gate rejections. Endpoints may attach additional context keys to aid recovery (tier, current_tier, limit, window_seconds, valid_kinds, recovery_hint, detail, example, ...); the reusable ones are named below.
      properties:
        error:
          type: string
          description: Error code or human-readable message (always present).
        ok:
          type: boolean
          enum:
          - false
          description: Present (false) on auth-gate rejections.
        error_kind:
          type: string
          description: Machine-readable failure class (rate_limit, validation, not_found, ...).
        message:
          type: string
          description: Longer human-readable detail (feedback + some rate-limit errors).
        rate:
          $ref: '#/components/schemas/RateInfo'
        retry_after_seconds:
          type: integer
          description: Seconds to wait before retrying (on 429).
        tier:
          type: string
          description: The caller's current tier — present on a tier/scope authorization (403) rejection.
        current_tier:
          type: string
          description: The caller's current tier — present on a tier/request validation (400) rejection.
        detail:
          type: string
          description: Extra failure detail — present on some 500 responses (e.g. the agent event-log read).
    RateInfo:
      type: object
      description: Per-token rate-limit snapshot returned by write endpoints.
      properties:
        current:
          type: integer
        remaining:
          type: integer
        limit:
          type: integer
  securitySchemes:
    agentBearer:
      type: http
      scheme: bearer
      bearerFormat: agt_<base64url>
      description: 'Per-member, individually-revocable agent token minted via the device-code flow. Send as `Authorization: Bearer agt_...`. The scope array in each operation''s security requirement names the IC scope the handler enforces.'
    clerkSession:
      type: apiKey
      in: cookie
      name: __session
      description: Browser Clerk session cookie. Operations under this scheme are reachable ONLY from a signed-in browser session, NOT with an agt_ bearer token. Agents use the equivalent MCP tools (e.g. ic_get_my_membership, ic_request_tier).
    workshopCode:
      type: http
      scheme: bearer
      bearerFormat: 6-char enrollment code
      description: 'The workshop''s own enrollment code, minted by POST /api/workshop/enroll and presented as a bearer. It is NOT an agt_ token: it carries no scopes, is not revocable per-token, and reaches only the /api/workshop/* routes.'
    sliceServiceSecret:
      type: http
      scheme: bearer
      bearerFormat: shared secret
      description: SLICE_SERVICE_SECRET — the machine-to-machine bearer the print-slicing service presents. A distinct trust boundary (an external machine on the tailnet), which is why it has its own secret rather than reusing the cron one. No member holds it and no member-facing flow can reach these routes.
    floorcastOnboarding:
      type: http
      scheme: bearer
      bearerFormat: fco_<...>
      description: 'A single-use Floorcast onboarding token. It exists because tenant provisioning has a chicken-and-egg problem: no operator exists yet for a floor that does not exist yet, so neither a Clerk session nor an agt_ token can authorize the call. Minting one is a concierge step with no live route, and the token is consumed by the provision it authorizes.'
x-payment-info:
  protocol: x402
  discovery: https://www.immersivecommons.com/discovery/resources
  donor_wall: https://www.immersivecommons.com/api/floor10/donations
  note: Payable resources are advertised at /discovery/resources; a bare request to a payable resource returns HTTP 402 with the PAYMENT-REQUIRED challenge.
x-api-lifecycle:
  versioning: unversioned-root (info.version is a dated CalVer change marker)
  deprecation: 'deprecated operations are flagged `deprecated: true` here and kept at least one release; the /api/zai-keys/* aliases (2026-09-15) are the current set'
x-sandbox:
  summary: 'A sandbox token (mint by adding "sandbox": true to POST /api/agent/signup/start) is a real token with real scopes whose WRITE operations return a simulated receipt instead of mutating; reads serve real data. Same base URL + bearer auth. Immutable after mint.'
  obtain:
    endpoint: POST /api/agent/signup/start
    body:
      sandbox: true
  write_response_shape:
    ok: true
    sandbox: true
    simulated: true
    would_have:
      action: string
      scope: string
      args: object
    note: string — scope was checked; deeper business rules (tier/role/ownership/signature) are NOT evaluated in sandbox, and no production state changed. A green receipt means well-formed + scoped, NOT guaranteed to pass in production.
  real_exceptions:
  - POST /api/agent/feedback (bug-report channel must be heard)
  - POST /api/agent/token/revoke (token lifecycle; genuinely revokes)
  not_sandbox_eligible:
  - ic_donate (x402 payment rail — never faked; not a REST operation in this spec)
  - floor-admin toggles + tools with no concrete scope to check — denied fail-closed, never silently simulated