API reference
Every ASAS v1 endpoint — methods, auth scopes, request and response schemas.
مرجع الواجهة البرمجية
مرجع كامل لنقاط النهاية في الإصدار الأول. المواصفة القابلة للقراءة آلياً بصيغة OpenAPI 3.1 متاحة للتنزيل واستيرادها في أدواتك.
This reference is generated from the same Zod contracts the gateway and SDK use. Download the machine-readable spec to import into Postman, Insomnia, or your codegen tool:
OpenAPI 3.1 spec
Import into any OpenAPI tool, or feed it to a code generator.
llms.txt
A flat, LLM-friendly index of these docs.
An interactive, try-it reference (rendered by fumadocs-openapi from this same
openapi.json) is a fast-follow. The wiring is scaffolded — see the docs app
README. Until then, this page is the hand-maintained mirror of the spec.
Base URL — https://api.asas.flitc.tech/v1 · Auth — Authorization: Bearer asas_live_…
· Errors — RFC 9457 application/problem+json (see Errors).
POST /v1/tts
Synthesize speech and return the full clip (blocking). Scope: tts:speak.
Request — application/json (TtsRequest)
{ "voice": "layan", "text": "أهلاً بك في أساس", "speed": 1.0, "quality": "standard" }Responses
| Status | Body |
|---|---|
200 | audio/mpeg or audio/wav (binary) |
422 | text over 500 chars / validation |
401 403 429 5xx | problem+json |
POST /v1/tts/stream
Same body as /v1/tts, but streams chunked audio for low-latency playback.
Scope: tts:speak. 200 → chunked audio/mpeg.
POST /v1/stt/transcriptions
Transcribe audio. Scope: stt:transcribe. Request is multipart/form-data.
| Field | Type | Notes |
|---|---|---|
file | file | Required. WAV/MP3/M4A |
language | string | Default auto |
diarize | boolean | Default false |
word_timestamps | boolean | Default false |
Responses — 200 synchronous transcription (short audio) · 202 async job
(long audio; result via the job.completed webhook) · errors as problem+json.
POST /v1/rag/search
Search your document tenant. Scope: rag:query. Request is application/json
(RagSearchRequest).
{ "query": "ما هي مدة الإجازة السنوية؟", "mode": "answer", "top_k": 8 }Responses — 200 complete JSON result · 409 tenant not provisioned /
resuming · errors as problem+json.
Schemas
TtsRequest
| Field | Type | Constraints |
|---|---|---|
text | string | required, 1–500 chars |
voice | string | required |
speed | number | 0.5–2.0, default 1.0 |
quality | enum | fast | standard | high, default standard |
RagSearchRequest
| Field | Type | Constraints |
|---|---|---|
query | string | required |
mode | enum | retrieve | answer | analyze, default retrieve |
top_k | integer | 1–100, default 10 |
min_score | number | 0–1, optional |
detail | enum | minimal | full, default full |
document_ids | string[] | optional |
language | string | auto / none / ISO-639-1 |
metadata_filters | object | optional |
enable_rewrite_search_query | boolean | default false (requires rewrite_search_query_instructions) |
Problem (error envelope)
| Field | Type | Notes |
|---|---|---|
status | integer | HTTP status |
title | string | short summary |
detail | string | occurrence specifics (optional) |
code | string | stable machine-readable code |
request_id | string | trace id |
See the full component schemas — including STT realtime and webhook payloads — in
the downloadable openapi.json.