Retrieval API

A request contract with a visible evidence boundary.

Send the question and permitted filters. CorpusMesh resolves the entitled corpus version, retrieval profile, and mandatory scope before any retrieval work begins.

Inspect the request Open a real Source Trace

Method: POST /v1/retrieve
Format: application/json
Decision: answer · abstain
Status: Private beta

Contract status

This reference documents the verified private-beta runtime. It does not provide public credentials or general availability.

Request access

Request

The caller controls the question and requested narrowing.

Unknown fields are rejected. Filters can narrow an entitlement, never expand it. The service plan applies the final top_k cap.

Field	Type	Presence	Behavior
`query`	string	Required	Raw query text, up to 4,000 characters.
`knowledge_base`	string	Required	The entitled knowledge-base slug.
`filters.language`	string[]	Optional	Requested languages within the entitlement.
`filters.jurisdiction`	string[]	Optional	Requested jurisdictions within the entitlement.
`filters.subject`	string[]	Optional	Knowledge-base-specific subject slugs.
`top_k`	integer	Optional	1 to 100 in the schema, capped by the service plan.
`profile`	active \| UUID	Optional	Use active or an explicitly entitled retrieval-profile ID.

: "${CORPUSMESH_API_KEY:?Set CORPUSMESH_API_KEY first}"

curl --silent --show-error --fail-with-body https://corpusmesh.com/v1/retrieve \
  --request POST \
  --header "Authorization: Bearer $CORPUSMESH_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: request-article-6-001" \
  --data '{
  "knowledge_base": "eu-ai-act-reference",
  "query": "How do Article 6 and Annex III work together to identify high-risk AI systems?",
  "filters": {
    "language": [
      "en"
    ],
    "jurisdiction": [
      "eu"
    ]
  },
  "top_k": 5,
  "profile": "active"
}'

Enforced boundary

The serving state is resolved before embedding the query.

The API verifies the organization, client, entitlement, immutable version, active retrieval profile, projection, and mandatory filters. A forbidden widening fails closed.

Caller sendsquery · filters · top_k

CorpusMesh pinsentitlement · version · profile · authorization

API returnspassages · citations · decision

Language, jurisdiction, subject, and profile requests are intersected with the entitlement. The API does not silently substitute broader access.

Response identity

Every result says what served it and where it came from.

The response identifies the corpus version, retrieval profile, trace, source document, revision, source snapshot, canonical URL, citation anchor, and measured usage.

Serving state

version, retrieval_profile, and trace_id make the retrieval state inspectable.

Source lineage

Authority, canonical URL, effective dates, source snapshot, and anchor travel with each passage.

Bounded usage

Result count, response bytes, and provider-reported query tokens support metering without storing raw query text.

Retrieval decision

An abstention is a valid response, not a hidden failure.

200 · answer

Evidence met the configured threshold.

Use the returned passages and citations as context for your own application. CorpusMesh does not generate the final answer.

200 · abstain

The query is not supported by the retrieved evidence.

results is empty and the response explains the abstention signal. Do not retry unchanged or treat it as evidence.

Private beta

Evaluate the contract against your knowledge workflow.

Describe the sources, jurisdictions, update obligations, and request volume your application needs.

Request developer access