# SURAD

> SURAD is an Arabic-first platform for voice agents. Two first-class modes: managed intelligence (the agent's brain runs in SURAD) and bring your own brain (your system keeps the brain; SURAD provides STT, TTS, streaming, voice identity, sessions, metering). Tenants build an agent in SURAD Studio (brain, instructions, knowledge, voice, pronunciation, reply format and length), publish it, and put it in front of users via a one-line website widget, their own server/app over HTTPS, or a voice-only API for their own LLM/agent. API base: https://app.surad-ai.com

Everything an integrator needs is in /llms-full.txt (single file, English). Human docs (Arabic) are at /developers.

## Integration paths

- [The agent: setup, voice, publish](https://surad-ai.com/developers/agents): managed brain vs your own brain per agent, instructions, voice and pronunciation, reply format/length, revisions, publish/rollback.
- [One-line widget](https://surad-ai.com/developers/widget): `<script src="https://app.surad-ai.com/widget/v1.js" data-embed="emb_…" async></script>` — text + push-to-talk voice, no backend, no secret in the browser.
- [SURAD agent from your server](https://surad-ai.com/developers/server): API key (server only) → short-lived session token → session → text/voice turns, SSE events, cancel/close, conversation history.
- [Voice for your own brain](https://surad-ai.com/developers/voice-api): `capability: "tts_only"` + `ready_text` (optional `synthesis_transport: "grpc_stream"` for streamed PCM over SSE), and `/voice/utterance` for STT.
- [Reference](https://surad-ai.com/developers/reference): error codes, API key scopes, limits, audio formats, execution identity, idempotency.

## Machine-readable contract

- OpenAPI (live, matches production): https://app.surad-ai.com/api/v1/developer-kit/v1/openapi.json
- Developer kit (curl, Node, Python, Laravel, WordPress examples; Postman; SDKs): https://app.surad-ai.com/api/v1/developer-kit/v1

## Rules an integration must follow

- Never ship the API key (`sk_…`) to a browser, mobile app or plugin. Only the session token reaches clients.
- Every client request carries `Origin` equal to a domain registered in Studio → Integration → allowed origins; the token is bound to it.
- A session token opens exactly one session (`409 TOKEN_REPLAYED` on reuse) and stays valid for that session's turns until it expires.
- Send a unique `idempotency_key` per turn; retries with the same key never synthesize twice.
- The voice spoken is the one configured for the agent in Studio; check `identity.voice_profile_id` / `audio.voice`. If it cannot be loaded you get `AUDIO_PRODUCTION_FAILURE` (502, retryable) — never a different voice.