API Reference

Retrieval you can call

The same retrieval the chat uses, behind a bearer token. This reference is public; the live key management screen is in your workspace.

One key serves both: the HTTP endpoints and the Contexta MCP tools accept the same credential.

Manage API keys

Base URL

https://api.contexta.my.id

Authentication

Every /v1 request carries the key in the Authorization header. A browser login token is not accepted here.

curl -X POST "https://api.contexta.my.id/v1/retrieve" \
  -H "Authorization: Bearer ctx_live_xxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"query": "refund policy", "top_k": 5}'

Endpoints

POST/v1/retrieve— Semantic search

Returns the document chunks closest to a question. No LLM call — retrieval only.

GET/v1/documents— List documents

Lists the documents this key may read.

GET/v1/documents/{id}/export— Export document

Full indexed text of one document, as Markdown or JSONL.

GET/v1/keys/me— Inspect key

What the calling key is: name, scopes, limits, and remaining quota.

POST /v1/retrieve

Returns the document chunks closest to a question. No LLM call — retrieval only.

Request body

Field	Type	Default	Notes
query	string	required	1–500 characters
top_k	int	5	1–20
document_ids	string[]	all	max 50; narrowed to key scope
doc_types	string[]	all	unclassified, sop, policy, contract, report, thesis, reference, other

Response

{
  "data": [
    {
      "document_id": "0f0d…",
      "document_name": "policy-2026.pdf",
      "doc_type": "policy",
      "chunk_index": 3,
      "page_number": 7,
      "section_path": "3. Refunds",
      "text": "…",
      "score": 0.68
    }
  ],
  "meta": {
    "query": "refund policy",
    "top_k": 5,
    "retrieved": 5,
    "document_scope": "all"
  }
}

Rate limits

60 requests/minute · 5,000 requests/day. Remaining quota on every response header.

X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 59
X-RateLimit-Limit-Day: 5000
X-RateLimit-Remaining-Day: 4999

Over quota returns 429 with a Retry-After header. Every request is logged for 90 days, including rejected ones.

Error codes

Code	HTTP	Meaning
invalid_api_key	401	Missing, malformed, or unknown key
api_key_revoked	403	Key was revoked
api_key_expired	403	Key passed its expiry date
insufficient_scope	403	Key lacks the retrieve scope
quota_minute_exceeded	429	60/minute window used up
quota_day_exceeded	429	Daily allowance used up
too_many_failed_keys	429	Same rejected key retried too many times
invalid_request	422	Body or query failed validation
document_not_found	404	No such document, or key may not read it
document_not_exportable	409	Indexing not finished or no chunks
api_key_store_unavailable	503	Authorization storage down

MCP server

The same key works as an MCP server for Claude Desktop, Cursor, or any MCP client.

https://api.contexta.my.id/mcp

{
  "mcpServers": {
    "contexta": {
      "url": "https://api.contexta.my.id/mcp",
      "headers": { "Authorization": "Bearer ctx_live_xxxxxxxxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

Tool	Returns
contexta_retrieve	Top chunks for a query with document_name, page_number, section_path, and fusion score
contexta_list_documents	Every document this key can read, with chunk_count and status
contexta_export_document	One whole document as markdown or JSONL

Key scoping

A key can be limited to a subset of documents. Out-of-scope requests return empty.

Requests that ask for a document outside the key's subset return empty results. Exports of out-of-scope documents answer 404 — the same as a non-existent document.