RAG API · Private beta

A RAG API that returns evidence, not generated answers.

Send a raw query and permitted filters. CorpusMesh returns ranked passages, source versions, citations, and an explicit answer or abstain decision. It does not generate the final answer or legal advice.

Method
POST /v1/retrieve
Output
Ranked passages · JSON
Decision
answer · abstain
Status
Private beta
Example

POST /v1/retrieve · application/json

{
  "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"
}

The request follows the prepared beta plan. The response excerpt illustrates its shape using the reviewed public trace; identifiers are placeholders and this is not a new live request.

Developer docsRetrieval API

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.

Body parameters

querystringRequired
Raw query text, up to 4,000 characters.
knowledge_basestringRequired
The entitled knowledge-base slug.
filters.languagestring[]Optional
Requested languages within the entitlement.
filters.jurisdictionstring[]Optional
Requested jurisdictions within the entitlement.
filters.subjectstring[]Optional
Knowledge-base-specific subject slugs.
top_kintegerOptional
1 to 100 in the schema, capped by the service plan.
profileactive | UUIDOptional
Use active or an explicitly entitled retrieval-profile ID.
Example

POST /v1/retrieve

: "${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.

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

Retrieval request boundaryfails closed
  1. Caller sendsquery · filters · top_k
  2. CorpusMesh pinsentitlement · version · profile · authorization
  3. API returnspassages · citations · decision

Response fields

Every passage carries its serving state and source identity.#

The response identifies the corpus version, retrieval profile, trace, source document, revision, source snapshot, canonical URL, citation anchor, language, jurisdiction, and verification status.

Serving state
version, retrieval_profile, and trace_id make the retrieval state inspectable.
Citation and scope
citation.label, source_anchor, language, and jurisdiction travel with each passage.
Source lineage
source_snapshot_id identifies the captured source. Its checksums and lineage are inspectable in the public Source Trace.
200 OKresponse excerptExample
{
  "version": "2026-08-21.1",
  "results": [
    {
      "text": "2. In addition to the high-risk AI systems referred to in paragraph 1, AI systems refe…",
      "citation": {
        "label": "Article 6 Classification rules for high-risk AI systems",
        "source_anchor": "https://eur-lex.europa.eu/eli/reg/2024/1689/oj/eng#art_6",
        "source_snapshot_id": "<source-snapshot-uuid>"
      },
      "metadata": {
        "language": "en",
        "jurisdiction": "eu",
        "verification_status": "verified"
      }
    }
  ],
  "abstention": {
    "decision": "answer"
  },
  "trace_id": "ret_<trace-id>"
}

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.

Example

Response excerpt from the reviewed public trace. Identifiers are placeholders.

{
  "version": "2026-08-21.1",
  "results": [
    {
      "text": "2. In addition to the high-risk AI systems referred to in paragraph 1, AI systems refe…",
      "citation": {
        "label": "Article 6 Classification rules for high-risk AI systems",
        "source_anchor": "https://eur-lex.europa.eu/eli/reg/2024/1689/oj/eng#art_6",
        "source_snapshot_id": "<source-snapshot-uuid>"
      },
      "metadata": {
        "language": "en",
        "jurisdiction": "eu",
        "verification_status": "verified"
      }
    }
  ],
  "abstention": {
    "decision": "answer"
  },
  "trace_id": "ret_<trace-id>"
}

Evidence before integration

Inspect the retrieval result and its measured behavior.#

The public artifacts show the citation path, source checksums, corpus version, evaluation fixture, and runtime-observed scores for the reviewed v1 reference. The benchmark retrieved ten passages and the public trace displays five; that evaluation is separate from the beta plan’s five-passage response cap.

  • Recall@10

    96.2%

    Share of required evidence found in the first ten passages.

    Dataset
    80 evaluation fixtures
    Scope
    eu-ai-act-reference · en · eu
    Version
    2026-08-21.1
    Reviewed
    2026-08-21
  • Source-anchor recall@10

    98.3%

    Required citation anchors present in the first ten passages.

    Dataset
    80 evaluation fixtures
    Scope
    eu-ai-act-reference · en · eu
    Version
    2026-08-21.1
    Reviewed
    2026-08-21
  • Abstention accuracy

    100%

    Unsupported fixtures that correctly returned abstain.

    Dataset
    80 evaluation fixtures
    Scope
    eu-ai-act-reference · en · eu
    Version
    2026-08-21.1
    Reviewed
    2026-08-21
  • Boundary violations

    0

    Results outside the enforced language and jurisdiction scope.

    Dataset
    80 evaluation fixtures
    Scope
    eu-ai-act-reference · en · eu
    Version
    2026-08-21.1
    Reviewed
    2026-08-21

Plan for integration

Match the request to the approved beta boundary.#

The prepared EU AI Act beta covers one English knowledge base for one named application. The service plan attached to your entitlement is authoritative.

Review the fixed-term beta offer and error and retry behavior. When a source changes, a candidate version must be reviewed and evaluated before activation. See how source maintenance is bounded.

EU AI Act beta planprepared plan
Maximum top_k
5
Passage length
4,000 characters
Response size
50,000 bytes
Request rate
10 per minute
Concurrency
2 requests
Daily allowance
250 requests
Monthly allowance
5,000 requests

Your acceptance test

Bring a workflow that can be checked.#

Use these questions to prepare a technical review and define success before access is issued.

  1. Which authorities, jurisdictions and source versions must your application cite?
  2. Which representative questions should return evidence, and which should abstain?
  3. What source-change cadence and review delay can your workflow accept?
  4. What request volume, concurrency and result depth does your integration need?
  5. Who will judge the retrieved passages and the answers your own model produces?

Use the benchmark acceptance worksheet to record these decisions. A published benchmark does not replace evaluation on your workflow.

Private beta

Evaluate the contract against your knowledge workflow.

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

Request developer access

Manual review. Keys are issued only after approval.