---
title: "Query the research RAG corpus"
method: POST
path: "/api/research/ask"
tags: ["research"]
---

# Query the research RAG corpus

`POST /api/research/ask`

## Request

- Base URL: `https://www.immersivecommons.com`
- URL: `https://www.immersivecommons.com/api/research/ask`
- Auth: HTTP bearer

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.

## Request body

- ResearchAskRequest
  - `q` string, required: The query.
  - `k` integer
  - `sources` string[]
  - `synthesize` boolean: When true, returns an LLM-synthesized grounded answer.
  - `model` 'claude-haiku-4-5' | 'claude-sonnet-4-6' | 'claude-opus-4-7': Only valid when synthesize=true.

## Response `200`

Retrieval results (or a synthesized answer).

- ResearchAskResponse: Passthrough from the RAG funnel. `/search` returns { results, via }; `/synthesize` returns { q, k, model, answer, citations, retrieval_results, usage, via }.
  - `results` object[]
  - `answer` string
  - `citations` object[]
  - `via` string

## Other responses

- `400`: Bad JSON / missing or oversized q / invalid k / invalid sources / invalid model.
- `401`: No auth.
- `403`: Scope/tier not authorized.
- `429`: Per-member hourly rate budget exceeded.
- `502`: Upstream RAG funnel error.
- `503`: RAG funnel not configured / rate limiter unavailable.
- `504`: Upstream RAG funnel timeout.

---

[API](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api.md) · [All operations](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api/revisions/be67c1f67c27?raw)