Immersive Commons Membership API

openapi: 3.2.0
info:
  title: Immersive Commons — Agent REST Membership 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: Membership
  description: Membership tier (browser-session).
paths:
  /api/tier/me:
    get:
      operationId: getMyTier
      tags:
      - Membership
      summary: Read the caller's membership tier
      description: Clerk-session only (NOT reachable with an agt_ bearer). Returns the caller's current tier, any pending request, and history. Agents read their tier via the MCP tool `ic_get_my_membership`.
      security:
      - clerkSession: []
      responses:
        '200':
          description: Tier + pending request + history.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TierMeResponse'
        '401':
          description: Not signed in.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Clerk lookup failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ic-route:
        file: app/api/tier/me/route.ts
        method: GET
  /api/tier/request:
    post:
      operationId: requestTier
      tags:
      - Membership
      summary: Request a higher membership tier
      description: 'Clerk-session only (NOT reachable with an agt_ bearer). Records a pending request for a higher, self-requestable ring; an operator approves it. Idempotent: re-posting overwrites the prior pending request. Agents use the MCP tool `ic_request_tier`.'
      security:
      - clerkSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TierRequestRequest'
      responses:
        '200':
          description: Request recorded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TierRequestResponse'
        '400':
          description: Invalid tier (not self-requestable / not higher than current).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Not signed in.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Clerk update failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ic-route:
        file: app/api/tier/request/route.ts
        method: POST
    delete:
      operationId: cancelTierRequest
      tags:
      - Membership
      summary: Cancel the pending tier request
      description: Clerk-session only. Clears the caller's pending tier request. No-op if none is pending.
      security:
      - clerkSession: []
      responses:
        '200':
          description: Cancelled (or nothing was pending).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TierRequestCancelResponse'
        '401':
          description: Not signed in.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Clerk update failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ic-route:
        file: app/api/tier/request/route.ts
        method: DELETE
  /api/membership/profile:
    get:
      operationId: getMyMemberProfile
      tags:
      - Membership
      summary: Read the caller's own member profile
      description: Clerk session, or agt_ token with `membership:write` — note the READ shares the write scope, because the route resolves both verbs through one auth path. A member who has never saved a profile gets a default stub rather than a 404.
      security:
      - clerkSession: []
      - agentBearer:
        - membership:write
      responses:
        '200':
          description: The caller's profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberProfileResponse'
        '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/membership/profile/route.ts
        method: GET
    post:
      operationId: updateMyMemberProfile
      x-sandbox: simulated
      tags:
      - Membership
      summary: Update the caller's own member profile
      description: 'Clerk session, or agt_ token with `membership:write` (live tier re-checked). Read-modify-write: omitted fields keep their current value, and an explicit null clears one. Idempotent. The saved record snapshots the caller''s live ring, and the profile photo lives on the sister route /api/membership/profile/photo.'
      security:
      - clerkSession: []
      - agentBearer:
        - membership:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MemberProfileUpdateRequest'
      responses:
        '200':
          description: The saved profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberProfileResponse'
        '400':
          description: Invalid JSON, or company_website is not a valid URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '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/membership/profile/route.ts
        method: POST
  /api/tier/pending:
    get:
      operationId: listPendingTierRequests
      tags:
      - Membership
      summary: Read the pending-membership queue
      description: Clerk operator session OR an agt_ token carrying `admin:tier_review`. Returns every pending tier request plus the recent audit tail. A KV read failure degrades to an EMPTY list rather than a 500, so read an empty `pending` as 'nothing visible', not as proof the queue is empty.
      security:
      - clerkSession: []
      - agentBearer:
        - admin:tier_review
      responses:
        '200':
          description: The queue plus the recent audit tail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TierPendingResponse'
        '401':
          description: No auth.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Not an operator / scope not authorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ic-route:
        file: app/api/tier/pending/route.ts
        method: GET
  /api/tier/approve:
    post:
      operationId: approveTierRequest
      x-sandbox: simulated
      tags:
      - Membership
      summary: Approve a member into a tier
      description: 'Clerk operator session OR an agt_ token carrying `admin:tier_review`, live tier re-checked. With no `tier` the member''s own pending request is approved as-is; passing `tier` approves them into that ring instead (an operator override — this is the only path that can hand out `operator`). Sister of the /floor10/admin/members server action: both call one applyTier, so behaviour is identical.'
      security:
      - clerkSession: []
      - agentBearer:
        - admin:tier_review
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TierApproveRequest'
      responses:
        '200':
          description: The applied tier move.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TierApplyResponse'
        '400':
          description: Invalid JSON, missing user_id, an unknown tier override, or no pending request to approve.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No auth.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Not an operator / scope not authorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Clerk lookup or write failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ic-route:
        file: app/api/tier/approve/route.ts
        method: POST
  /api/tier/deny:
    post:
      operationId: denyTierRequest
      x-sandbox: simulated
      tags:
      - Membership
      summary: Deny a pending tier request
      description: 'Clerk operator session OR an agt_ token carrying `admin:tier_review`, live tier re-checked. Clears the pending request and its KV snapshot; the member''s current tier is unchanged. `was_pending: false` means there was nothing to deny — a success, not an error.'
      security:
      - clerkSession: []
      - agentBearer:
        - admin:tier_review
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TierDenyRequest'
      responses:
        '200':
          description: The request was cleared.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TierDenyResponse'
        '400':
          description: Invalid JSON or missing user_id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No auth.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Not an operator / scope not authorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Clerk write failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ic-route:
        file: app/api/tier/deny/route.ts
        method: POST
  /api/membership/profile/photo:
    post:
      operationId: setMyMemberPhoto
      x-sandbox: simulated
      tags:
      - Membership
      summary: Set the caller's profile photo
      description: Clerk session, or agt_ token with `membership:write` (live tier re-checked) — the sister route of /api/membership/profile, which cannot set the photo itself. The server crops the supplied image to a 256px square WebP and stores it INSIDE the profile record as a data URL, so the response's `profile.photo_data_url` is the photo, not a link to it.
      security:
      - clerkSession: []
      - agentBearer:
        - membership:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MemberPhotoRequest'
      responses:
        '200':
          description: The saved profile, photo included.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberPhotoResponse'
        '400':
          description: Invalid JSON, no image supplied, or an image the cropper rejected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '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/membership/profile/photo/route.ts
        method: POST
    delete:
      operationId: deleteMyMemberPhoto
      x-sandbox: simulated
      tags:
      - Membership
      summary: Remove the caller's profile photo
      description: 'Clerk session, or agt_ token with `membership:write` (live tier re-checked). Clears the photo and leaves the rest of the profile untouched. Idempotent: a caller with no photo gets `had_photo: false` and a 200, and no `profile` is echoed because nothing was written.'
      security:
      - clerkSession: []
      - agentBearer:
        - membership:write
      responses:
        '200':
          description: Photo removed, or there was none.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberPhotoDeleteResponse'
        '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/membership/profile/photo/route.ts
        method: DELETE
components:
  schemas:
    MemberProfileResponse:
      type: object
      required:
      - ok
      - profile
      properties:
        ok:
          type: boolean
        profile:
          $ref: '#/components/schemas/MemberProfile'
    MemberProfileUpdateRequest:
      type: object
      description: 'Read-modify-write: an omitted field keeps its current value, and an explicit null clears it. Clearing company_website also clears the derived logo.'
      properties:
        first_name:
          type:
          - string
          - 'null'
        company_website:
          type:
          - string
          - 'null'
          description: Must parse as a URL, or the call is a 400.
        public_visible:
          type: boolean
    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).
    TierDenyRequest:
      type: object
      required:
      - user_id
      properties:
        user_id:
          type: string
          description: Clerk user id of the member whose request is being denied.
        reason:
          type: string
          description: Free text for the audit trail; trimmed to 400 characters.
    MemberPhotoResponse:
      type: object
      required:
      - ok
      - profile
      properties:
        ok:
          type: boolean
        profile:
          $ref: '#/components/schemas/MemberProfile'
        base64_len:
          type: integer
          description: Length of the stored WebP data URL. The photo lives inside the record, so this is what it costs.
    TierPendingResponse:
      type: object
      required:
      - ok
      - pending
      - audit
      properties:
        ok:
          type: boolean
        pending:
          type: array
          items:
            $ref: '#/components/schemas/PendingTierRequestRecord'
          description: Newest first.
        audit:
          type: array
          items:
            $ref: '#/components/schemas/TierAuditRecord'
          description: The recent tail, not the whole history.
    MemberPhotoDeleteResponse:
      type: object
      required:
      - ok
      - had_photo
      properties:
        ok:
          type: boolean
        had_photo:
          type: boolean
          description: False when there was nothing to remove.
        profile:
          $ref: '#/components/schemas/MemberProfile'
    TierApproveRequest:
      type: object
      required:
      - user_id
      properties:
        user_id:
          type: string
          description: Clerk user id of the member being approved.
        tier:
          type: string
          description: Optional override ring. Omit to approve the member's own pending request as filed.
        reason:
          type: string
          description: Free text for the audit trail; trimmed to 400 characters.
    TierRequestCancelResponse:
      type: object
      required:
      - ok
      - was_pending
      properties:
        ok:
          type: boolean
        was_pending:
          type: boolean
    RateInfo:
      type: object
      description: Per-token rate-limit snapshot returned by write endpoints.
      properties:
        current:
          type: integer
        remaining:
          type: integer
        limit:
          type: integer
    TierMeResponse:
      type: object
      required:
      - ok
      - tier
      properties:
        ok:
          type: boolean
        tier:
          type: string
          description: public | ft-member | ai-floor | ic-member | operator
        pending:
          type:
          - object
          - 'null'
          additionalProperties: true
          description: The pending tier request, or null.
        history:
          type: array
          items:
            type: object
            additionalProperties: true
        email:
          type: string
        display_name:
          type: string
    MemberProfile:
      type: object
      required:
      - clerk_user_id
      - public_visible
      - ring
      - updated_at
      additionalProperties: true
      properties:
        clerk_user_id:
          type: string
        first_name:
          type: string
        photo_data_url:
          type: string
          description: Set through /api/membership/profile/photo, not this route.
        company_website:
          type: string
          description: Normalized to an absolute URL on save.
        company_logo_url:
          type: string
          description: Derived from company_website; not settable directly.
        public_visible:
          type: boolean
          description: Whether the member appears on the public members wall.
        ring:
          type: string
          description: Snapshot of the member's tier at the last save — public | ft-member | ai-floor | ic-member | operator.
        updated_at:
          type: string
          format: date-time
    TierDenyResponse:
      type: object
      required:
      - ok
      - user_id
      - tier
      - was_pending
      properties:
        ok:
          type: boolean
        user_id:
          type: string
        tier:
          type: string
          description: The member's tier, unchanged by a deny.
        was_pending:
          type: boolean
          description: False when there was nothing to deny.
    PendingTierRequestRecord:
      type: object
      description: One member waiting on an operator decision. The display fields are snapshots taken at request time; the admin page re-reads Clerk for live values.
      required:
      - user_id
      - current_tier
      - requested_tier
      - submitted_at
      additionalProperties: true
      properties:
        user_id:
          type: string
          description: Clerk user id of the requester.
        email:
          type: string
        display_name:
          type: string
        current_tier:
          type: string
          description: What the member is now.
        requested_tier:
          type: string
          description: What they asked to become.
        note:
          type: string
          description: Free text, capped at 600 characters when the request was filed.
        submitted_at:
          type: string
          format: date-time
    MemberPhotoRequest:
      type: object
      description: Supply the image exactly one way.
      properties:
        data_url:
          type: string
          description: 'A data: URL, e.g. data:image/png;base64,...'
        base64:
          type: string
          description: 'Bare base64 with no data: prefix.'
    TierRequestResponse:
      type: object
      required:
      - ok
      - current_tier
      - requested_tier
      properties:
        ok:
          type: boolean
        current_tier:
          type: string
        requested_tier:
          type: string
        submitted_at:
          type: string
          format: date-time
        kv_warning:
          type: string
          description: Present if the KV pending-queue write soft-failed (the request is still recorded).
    TierApplyResponse:
      type: object
      required:
      - ok
      - user_id
      - from
      - to
      - action
      properties:
        ok:
          type: boolean
        user_id:
          type: string
        from:
          type: string
          description: The ring the member held before this call.
        to:
          type: string
          description: The ring they hold now.
        action:
          type: string
          description: The audit verb recorded for the move.
    TierRequestRequest:
      type: object
      required:
      - tier
      properties:
        tier:
          type: string
          description: A self-requestable tier ABOVE the caller's current tier.
        note:
          type: string
          maxLength: 600
    TierAuditRecord:
      type: object
      description: One entry in the membership audit trail.
      required:
      - user_id
      - action
      - at
      additionalProperties: true
      properties:
        user_id:
          type: string
        email:
          type: string
        display_name:
          type: string
        action:
          type: string
          description: request | approve | deny | auto-promote | demote.
        from:
          type: string
          description: Prior tier — omitted on a first grant.
        to:
          type: string
          description: New tier — omitted on a deny.
        requested:
          type: string
          description: What the member had asked for, where that applies.
        reason:
          type: string
        by_clerk_user_id:
          type: string
          description: The operator. Absent on a self-request or an auto-promote.
        at:
          type: string
          format: date-time
  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