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.

Start with the quickstart Inspect the EU AI Act trace

Endpoint: POST /v1/retrieve
Delivery: REST · JSON
Access: Manually approved
Status: Private beta

Private beta

The contract below matches the prepared customer boundary. Public signup, self-service keys, MCP delivery, and a general-availability SLA are not available.

Request access

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.

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

Authentication

Keys are scoped to one client and environment.

AuthorizationBearer cm_test_••••••••

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

Callers choose the question, not the serving boundary.

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

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.

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.

Caller sendsquery · filters · top_k

Server pinsentitlement · verified version · profile · authorization

Service returnsbounded passages · citations · decision

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

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.

200 OKapplication/json

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

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.

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.

HTTP	Code	Meaning	Retry
400	`INVALID_REQUEST`	Malformed JSON or a request outside the schema.	No
401	`INVALID_API_KEY`	Missing, invalid, revoked, expired, or wrong-environment key.	No
403	`FILTER_FORBIDDEN`	A filter or profile would widen the entitlement.	No
403	`SCOPE_FORBIDDEN`	The key lacks the retrieval:read scope.	No
403	`ENTITLEMENT_INACTIVE`	The knowledge base is not active for this client.	No
409	`REQUEST_ALREADY_PROCESSED`	The idempotency key already reached the service.	Inspect request_id
429	`RATE_LIMITED`	A rate, concurrency, or extraction throttle is active.	Yes
429	`QUOTA_EXHAUSTED`	The daily or monthly request allowance is exhausted.	No
413	`INVALID_REQUEST`	The request body exceeds 16,384 bytes.	No
503	`INTERNAL_UNAVAILABLE`	A required service dependency is unavailable.	Yes
503	`RETRIEVAL_UNAVAILABLE`	Retrieval 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.

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

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

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