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.

Use an example Request beta access

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

Access required

The examples become callable only after CorpusMesh approves an entitlement and issues a key for the matching test or live environment.

Read the retrieval API reference

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.

Environment variableCORPUSMESH_API_KEY=cm_test_••••••••

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.

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.

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

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.

Inspectpublic Source Trace

Evaluaterequest · boundary · citations · decision

Continuerequest a scoped beta entitlement

Inspect the EU AI Act trace Request access

Need the complete contract?

Continue with fields, limits, errors, and boundaries.

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

Open the retrieval reference