Private-beta API reference

Retrieve evidence. Keep control of the answer.

Send a raw query and permitted filters. CorpusMesh returns bounded passages, official citations, the corpus version, and the retrieval decision. Your application decides what happens next.

Endpoint
POST /v1/retrieve
Delivery
REST · JSON
Access
Manually approved
Status
Private beta
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"
}'

Developer docsOverview

Request example

One request returns source-linked context.#

Use a private-beta key issued for your environment and entitlement. Keep it on the server. If this is your first integration, the focused quickstart explains how to read answers, abstentions, and errors before you copy an example.

POST /v1/retrieveRequest bodyExample
{
  "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"
}

Authentication

Keys are scoped to one client and environment.#

  • Server-side only

    Never expose a CorpusMesh key in browser code, a mobile bundle, analytics, logs, or a public repository.

  • Test and live are separate

    A test key cannot authenticate against a live runtime. Rotation and revocation preserve the access audit trail.

  • Idempotency is explicit

    Send a 16 to 128 character Idempotency-Key when a request may be retried. Reuse it only for the same request.

Request headersExample
Authorization: Bearer cm_test_••••••••
Content-Type: application/json
Idempotency-Key: request-article-6-001

Request

Callers choose the question, not the serving boundary.#

Unknown fields are rejected. Filters can narrow an entitlement but cannot expand it.

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.
Request and server-enforced retrieval boundaryfails closed
  1. Caller sendsquery · filters · top_k
  2. Server pinsentitlement · verified version · profile · authorization
  3. Service returnsbounded passages · citations · decision

Enforced boundary

The server resolves what the key is allowed to retrieve.#

Before embedding the query, CorpusMesh verifies the organization, API client, entitlement, plan, immutable corpus version, retrieval profile, projection, and mandatory filters.

A forbidden language, jurisdiction, profile, or inactive entitlement fails closed before retrieval. The service never silently broadens the request.

Example

Excerpt: a filter or profile would widen the entitlement. Other error fields omitted.

HTTP 403

{
  "error": {
    "code": "FILTER_FORBIDDEN"
  }
}

Response

Every passage carries enough context to inspect its origin.#

This example uses content from the reviewed EU AI Act Source Trace. Placeholder identifiers are shortened; the private-beta response returns full UUIDs.

Identity
version, retrieval_profile, and trace_id identify the serving state.
Source
Document authority, canonical URL, dates, citation label, anchor, and source snapshot travel with the passage.
Usage
Result count, response bytes, and provider-reported query tokens support metering without storing the raw query.
200 OKapplication/jsonExample
{
  "request_id": "req_<request-id>",
  "knowledge_base": "eu-ai-act-reference",
  "version": "2026-08-21.1",
  "retrieval_profile": "gemini-embedding-2-768-search-v2",
  "results": [
    {
      "chunk_id": "chk_34924b790ce0a55d5f8bf88a25536329cc1c41c6",
      "text": "2. In addition to the high-risk AI systems referred to in paragraph 1, AI systems referred to in Annex III shall be considered to be high-risk.",
      "score": 0.8504182949786874,
      "document": {
        "id": "<document-uuid>",
        "revision_id": "<revision-uuid>",
        "title": "Regulation (EU) 2024/1689 laying down harmonised rules on artificial intelligence",
        "authority": "European Parliament, Council of the European Union",
        "canonical_url": "https://eur-lex.europa.eu/eli/reg/2024/1689/oj/eng",
        "published_at": "2024-07-12T00:00:00.000Z",
        "effective_at": "2024-08-01T00:00:00.000Z"
      },
      "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"
      }
    }
  ],
  "trace_id": "ret_<trace-id>",
  "abstention": {
    "decision": "answer",
    "signal": "top_bm25_score_divided_by_unique_query_term_count",
    "threshold": 0.9716698313638811,
    "observed_value": 1.3979861158367013,
    "unsupported_explicit_references": []
  },
  "usage": {
    "query_embedding_tokens": "<provider-reported-or-null>",
    "result_count": 1,
    "response_bytes": "<measured-response-bytes>"
  }
}

Abstention and errors

No evidence is different from a failed request.#

200 · abstain

The service cannot support the query.

The response is valid, results is empty, and abstention.decision is abstain. Do not treat it as evidence or retry it unchanged.

4xx or 5xx · error

The request did not complete.

The body contains an error code, request ID, trace ID, and retryable. An API or provider failure is never converted into an abstention.

Example

Excerpt. Other response fields, including the abstention signal, are omitted.

{
  "results": [],
  "abstention": {
    "decision": "abstain"
  }
}

Stable error codes
HTTPCodeMeaningRetry
400INVALID_REQUESTMalformed JSON or a request outside the schema.No
401INVALID_API_KEYMissing, invalid, revoked, expired, or wrong-environment key.No
403FILTER_FORBIDDENA filter or profile would widen the entitlement.No
403SCOPE_FORBIDDENThe key lacks the retrieval:read scope.No
403ENTITLEMENT_INACTIVEThe knowledge base is not active for this client.No
409REQUEST_ALREADY_PROCESSEDThe idempotency key already reached the service.Inspect request_id
429RATE_LIMITEDA rate, concurrency, or extraction throttle is active.Yes
429QUOTA_EXHAUSTEDThe daily or monthly request allowance is exhausted.No
413INVALID_REQUESTThe request body exceeds 16,384 bytes.No
503INTERNAL_UNAVAILABLEA required service dependency is unavailable.Yes
503RETRIEVAL_UNAVAILABLERetrieval or the bounded response could not complete.Yes

Initial beta limits

Limits are enforced before paid retrieval work.#

These are the prepared EU AI Act beta-plan limits. The immutable plan attached to an issued entitlement is authoritative.

The beta has no automatic overage. Exposure controls can throttle or block systematic corpus extraction even when request quotas remain.

Beta plan limitsprepared 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
Request body
16,384 bytes

Private beta

Bring the knowledge problem. Keep your application.

Tell us which sources, jurisdictions, update obligations, and request volume your product needs.

Request developer access

Manual review. Keys are issued only after approval.