# TilQazyna Platform

> Sovereign AI platform for Kazakhstani universities: OpenAI-compatible API
> (chat, embeddings, files, vector stores, responses with file_search RAG,
> audio) plus assistants. Kazakh-first models. Replace base_url, keep your SDK.

## Connect

- Base URL: `https://router.tilqazyna.kz/v1`
- Auth: `Authorization: Bearer sk-tq-...` (create keys in the portal, /portal → API keys)
- Models: `til-chat` (chat), `til-embed` (embeddings), `til-speech` (audio)
- Errors: OpenAI format `{"error":{"message","type","code"}}`; 429 = rate limit or monthly quota.

## Endpoints

- POST /v1/chat/completions — messages[], stream:true for SSE
- POST /v1/embeddings — input: string | string[]
- POST /v1/files (multipart file=) · GET /v1/files · DELETE /v1/files/{id}
- POST /v1/vector_stores {name} · POST /v1/vector_stores/{id}/files {file_id} · POST /v1/vector_stores/{id}/search {query}
- POST /v1/responses {input, tools:[{type:"file_search", vector_store_ids:[...]}]} — managed RAG, citations in annotations; or {input, assistant_id}
- POST /v1/assistants {name, instructions, vector_store_ids} · GET /v1/assistants · GET /v1/assistants/{id} — objects include status: draft|published|paused
- POST /v1/audio/transcriptions|translations (multipart file=) · POST /v1/audio/speech {input} → audio/wav

## Portal (self-service, session cookie — not for API clients)

- Manage keys/KBs/assistants/channels at `https://router.tilqazyna.kz/portal` (`/portal/api/*`, `tq_session` cookie, not `sk-tq-...`).
- GET conversations?filter=&limit= (neg|refused|widget|telegram) · GET conversations/{id} — transcript
- GET requests?filter=&limit= (filter=errors) — per-call log (latency, model, status)
- POST channels/{id}/origins {allowed_origins} — widget embed allowlist
- GET templates · POST templates/{id}/use — starter bot: creates a KB + draft assistant
- POST assistants/{id}/status {status: draft|published|paused}

## Recipe: RAG bot in 4 calls

1. POST /v1/files (upload PDF) → file_id
2. POST /v1/vector_stores {"name":"Docs"} → vs_id
3. POST /v1/vector_stores/{vs_id}/files {"file_id":file_id}
4. POST /v1/responses {"input":"question","tools":[{"type":"file_search","vector_store_ids":[vs_id]}]}

## MCP

Run the MCP server for IDE agents (Cursor/Claude Code):
`platform-server mcp --base-url https://router.tilqazyna.kz --api-key sk-tq-...`
Tools: list_assistants, create_assistant, query_assistant, search_vector_store, get_usage.