Referensi API

Retrieval yang bisa Anda panggil

Retrieval yang sama dengan yang dipakai chat, di balik bearer token. Referensi ini publik; layar pengelolaan key yang live ada di workspace Anda.

Satu key melayani keduanya: endpoint HTTP dan tool MCP Contexta menerima kredensial yang sama.

Kelola API key

URL dasar

https://api.contexta.my.id

Autentikasi

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

Endpoint

POST/v1/retrieve— Pencarian semantik

Mengembalikan chunk dokumen yang paling dekat dengan pertanyaan. Tanpa panggilan LLM — hanya retrieval.

GET/v1/documents— Daftar dokumen

Daftar dokumen yang boleh dibaca key ini.

GET/v1/documents/{id}/export— Ekspor dokumen

Teks terindeks lengkap satu dokumen, dalam format Markdown atau JSONL.

GET/v1/keys/me— Inspeksi key

Info key pemanggil: nama, scope, batas, dan sisa kuota.

POST /v1/retrieve

Mengembalikan chunk dokumen yang paling dekat dengan pertanyaan. Tanpa panggilan LLM — hanya retrieval.

Request body

Field	Tipe	Default	Catatan
query	string	wajib	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"
  }
}

Batas rate

60 permintaan/menit · 5.000 permintaan/hari. Sisa kuota ada di header setiap respons.

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.

Kode error

Kode	HTTP	Arti
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

Server MCP

Key yang sama berlaku sebagai server MCP untuk Claude Desktop, Cursor, atau client MCP lainnya.

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

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

Tool	Mengembalikan
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

Scope key

Key bisa dibatasi ke subset dokumen. Permintaan di luar scope mengembalikan kosong.

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.