> ## Documentation Index > Fetch the complete documentation index at: https://immersivecommons.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Query the research RAG corpus > Clerk session or agt_ token with `research:query`. Forwards a top-k retrieval (optionally LLM-synthesized) query to the supercommons2 RAG funnel and returns the results. The query text is never logged. 60 requests/hour/member. ## OpenAPI ````yaml /openapi.json post /api/research/ask openapi: 3.1.1 info: title: Immersive Commons — Agent REST API version: '2026-07-16' 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. No operation is deprecated today; when one is scheduled for removal it will be marked `deprecated: true` here and carry RFC 8594 `Deprecation` + `Sunset` response headers, announced at least 90 days ahead via /developers and llms.txt. 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: events description: Discover and RSVP to events; propose member events. - name: batch description: Fan out several public GET reads in one request. - name: directory description: Search the member directory. - name: resources description: List and book rooms / printers. - name: account description: The caller's own activity log. - name: leaderboard description: The public commit leaderboard. - name: research description: Query the research RAG corpus. - name: highlights description: Submit event highlights for moderation. - name: feedback description: File feedback / breakage reports. - name: auth description: Token mint (device code), self-revoke, setup checks. - name: payments description: x402 machine payments (donor wall). - name: membership description: Membership tier (browser-session). - name: browser-session description: Clerk-cookie only — NOT reachable with an agt_ bearer. paths: /api/research/ask: post: tags: - research summary: Query the research RAG corpus description: >- Clerk session or agt_ token with `research:query`. Forwards a top-k retrieval (optionally LLM-synthesized) query to the supercommons2 RAG funnel and returns the results. The query text is never logged. 60 requests/hour/member. operationId: askResearch requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ResearchAskRequest' responses: '200': description: Retrieval results (or a synthesized answer). content: application/json: schema: $ref: '#/components/schemas/ResearchAskResponse' '400': description: >- Bad JSON / missing or oversized q / invalid k / invalid sources / invalid model. 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' '429': description: Per-member hourly rate budget exceeded. content: application/json: schema: $ref: '#/components/schemas/Error' '502': description: Upstream RAG funnel error. content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: RAG funnel not configured / rate limiter unavailable. content: application/json: schema: $ref: '#/components/schemas/Error' '504': description: Upstream RAG funnel timeout. content: application/json: schema: $ref: '#/components/schemas/Error' security: - agentBearer: - research:query components: schemas: ResearchAskRequest: type: object required: - q properties: q: type: string maxLength: 500 description: The query. k: type: integer minimum: 1 maximum: 50 default: 10 sources: type: array items: type: string enum: - paper - book default: - paper synthesize: type: boolean default: false description: When true, returns an LLM-synthesized grounded answer. model: type: string enum: - claude-haiku-4-5 - claude-sonnet-4-6 - claude-opus-4-7 description: Only valid when synthesize=true. ResearchAskResponse: type: object description: >- Passthrough from the RAG funnel. `/search` returns { results, via }; `/synthesize` returns { q, k, model, answer, citations, retrieval_results, usage, via }. additionalProperties: true properties: results: type: array items: type: object additionalProperties: true answer: type: string citations: type: array items: type: object additionalProperties: true via: type: string 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_ 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. ````