Developer quickstart

Make one bounded retrieval request.

This guide covers the prepared REST contract. It requires a manually issued private-beta key and does not expose a public signup or public retrieval API.

Endpoint
POST /v1/retrieve
Examples
cURL · TypeScript · Python
Credential
Server-side beta key
Status
Prepared private beta
Developer docsQuickstart

Before the request

Keep the credential in your server environment.#

Set CORPUSMESH_API_KEY to the key issued for your API client. Do not place it in browser code, a mobile bundle, analytics, logs, or a public repository.

  • 1. Match the environment

    A test key works only with a test runtime. Live access uses a separately issued live key.

  • 2. Keep the raw query yours

    Your application sends the query. CorpusMesh stores keyed usage fingerprints, not the raw query, in the usage ledger.

  • 3. Reuse retry identity

    Use the same 16 to 128 character Idempotency-Key only when retrying the same request.

Environment variableserver onlyExample
CORPUSMESH_API_KEY=cm_test_••••••••

Send the request

Choose a language and run the same contract.#

Each example sends a raw question, entitled filters, top_k, and an idempotency key to POST /v1/retrieve. The current example targets the limited EU AI Act beta fixture.

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

Handle the result

Branch on HTTP status, then on the retrieval decision.#

A supported answer and an abstention both use HTTP 200. Errors use 4xx or 5xx with a stable code and a retryable value.

200 · answer or abstain

Read the decision before using results.

Use passages only when abstention.decision is answer. An abstain response is valid but contains no supported evidence.

4xx or 5xx · error

Retry only when the response permits it.

Inspect error.code, error.retryable, and Retry-After. A provider failure is never returned as an empty successful result.

Example

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

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

Inspect before integrating

Review a real Source Trace without an API key.#

The published EU AI Act trace shows the query, enforced version and filters, ranked passages, official citations, lineage, retrieval profile, and abstention evidence from a reviewed internal run.

Private-beta integration pathno key needed to inspect
  1. Inspectpublic Source Trace
  2. Evaluaterequest · boundary · citations · decision
  3. Continuerequest a scoped beta entitlement

Need the complete contract?

Continue with fields, limits, errors, and boundaries.

The retrieval reference documents the prepared beta behavior without implying public availability.