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.
Private-beta API reference
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.
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"
}'POST /v1/retrieve
const response = await fetch("https://corpusmesh.com/v1/retrieve", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CORPUSMESH_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": `request-${crypto.randomUUID()}`,
},
body: JSON.stringify({
"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"
}),
});
const retrieval = await response.json();
if (!response.ok) {
const retryAfter = response.headers.get("retry-after");
throw new Error(
retrieval.error.code + (retryAfter ? "; retry after " + retryAfter + "s" : ""),
);
}
if (retrieval.abstention.decision === "abstain") {
console.log("No supported evidence returned for this query.");
} else {
console.log(retrieval.results);
}POST /v1/retrieve
import os
import uuid
import requests
response = requests.post(
"https://corpusmesh.com/v1/retrieve",
headers={
"Authorization": f"Bearer {os.environ['CORPUSMESH_API_KEY']}",
"Idempotency-Key": f"request-{uuid.uuid4()}",
},
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"
},
timeout=35,
)
retrieval = response.json()
if not response.ok:
retry_after = response.headers.get("retry-after")
suffix = f"; retry after {retry_after}s" if retry_after else ""
raise RuntimeError(f"{retrieval['error']['code']}{suffix}")
if retrieval["abstention"]["decision"] == "abstain":
print("No supported evidence returned for this query.")
else:
print(retrieval["results"])Request example
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.
{
"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
Never expose a CorpusMesh key in browser code, a mobile bundle, analytics, logs, or a public repository.
A test key cannot authenticate against a live runtime. Rotation and revocation preserve the access audit trail.
Send a 16 to 128 character Idempotency-Key when a request may be retried. Reuse it only for the same request.
Authorization: Bearer cm_test_••••••••
Content-Type: application/json
Idempotency-Key: request-article-6-001Request
Unknown fields are rejected. Filters can narrow an entitlement but cannot expand it.
querystringRequiredknowledge_basestringRequiredfilters.languagestring[]Optionalfilters.jurisdictionstring[]Optionalfilters.subjectstring[]Optionaltop_kintegerOptionalprofileactive | UUIDOptionalEnforced boundary
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.
Excerpt: a filter or profile would widen the entitlement. Other error fields omitted.
HTTP 403
{
"error": {
"code": "FILTER_FORBIDDEN"
}
}Excerpt: the knowledge base is not active for this client. Other error fields omitted.
HTTP 403
{
"error": {
"code": "ENTITLEMENT_INACTIVE"
}
}Response
This example uses content from the reviewed EU AI Act Source Trace. Placeholder identifiers are shortened; the private-beta response returns full UUIDs.
version, retrieval_profile, and trace_id identify the serving state.{
"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
The response is valid, results is empty, and abstention.decision is abstain. Do not treat it as evidence or retry it unchanged.
The body contains an error code, request ID, trace ID, and retryable. An API or provider failure is never converted into an abstention.
Excerpt. Other response fields, including the abstention signal, are omitted.
{
"results": [],
"abstention": {
"decision": "abstain"
}
}Excerpt. The error body also carries a request ID, trace ID, and retryable flag, omitted here.
HTTP 429
Retry-After: <seconds>
{
"error": {
"code": "RATE_LIMITED"
}
}| 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
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.
Private beta
Tell us which sources, jurisdictions, update obligations, and request volume your product needs.
Manual review. Keys are issued only after approval.