---
title: "Pay-per-query twin of the research RAG read"
method: POST
path: "/api/x402/research/ask"
tags: ["payments", "research"]
---

# Pay-per-query twin of the research RAG read

`POST /api/x402/research/ask`

## Request

- Base URL: `https://www.immersivecommons.com`
- URL: `https://www.immersivecommons.com/api/x402/research/ask`
- Auth: none required

The metered door onto the SAME corpus members query free at POST /api/research/ask — for agents with no IC membership. No token: a bare POST answers 402, and a re-send carrying a signed `X-PAYMENT` header buys one query. The answer is withheld if settlement fails (502) rather than given away. Returns 404 while X402_ENABLED is off. Members should keep using the free route.

## Headers

- `X-PAYMENT` string

## Request body

- X402ResearchAskRequest
  - `q` string, required: The query. Never logged.
  - `k` integer: Top-k retrieval depth.
  - `sources` string[]: Which corpora to search.
  - `synthesize` boolean: Ask for an LLM-written answer over the hits instead of the hits alone.
  - `model` string: Only valid with synthesize=true. One of: claude-haiku-4-5.

## Response `200`

The retrieval results, marked with a `via` of x402.

- X402ResearchAskResponse: The same payload the free member route returns, plus `via`.
  - `via` string, required: Always x402.
  - `results` object[]: Retrieval hits, when the upstream returned a bare list.

## Other responses

- `400`: Bad JSON, a missing/oversized q, an invalid k, an unknown source, or a model without synthesize.
- `402`: Payment required — the body carries the price, payTo and asset.
- `404`: The paid door is disabled (X402_ENABLED is not true).
- `429`: Per-payer query budget exceeded.
- `502`: The answer was produced but settlement failed, so it is withheld.
- `503`: The RAG funnel, the payment rails, or the rate limiter is unavailable.

---

[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)