Diction: Instructions file for Codex

Diction Gateway -- Agent Reference

Machine-legible reference for the Diction self-hosted gateway. Covers routes, wire formats, environment variables, capabilities, and what the gateway can and cannot do.

Overview

The gateway is a Go HTTP service that sits between the Diction iOS app and one or more OpenAI-compatible speech-to-text backends. It handles:

• WebSocket streaming for low-latency transcription
• HTTP transcription fallback
• Optional LLM post-processing (transcript cleanup, voice editing, suggestions)
• QR pairing with per-device keys, optionally required on every request

WARNING: TEXT_ROUTES_OPEN=false (default). /v1/text/* routes return 403 to callers without a pairing key until you set TEXT_ROUTES_OPEN=true. This is a deliberate speed bump, not a security control; the security control is DICTION_GATEWAY_AUTH=required.

Routes

GET /health

Health check. Returns 200 when the gateway is up.

Response: 200 OK
Body: "ok"

GET /v1/models

Lists configured speech backends (OpenAI-compatible + Diction legacy grouping). Also includes a top-level capabilities object describing what this gateway instance can do (additive -- never removes data[] or providers[]).

Response: 200 OK
Content-Type: application/json

{
  "object": "list",
  "data": [
    { "id": "nvidia/parakeet-tdt-0.6b-v3", "object": "model", "created": 0, "owned_by": "nvidia" }
  ],
  "providers": [
    {
      "id": "parakeet",
      "name": "NVIDIA Parakeet",
      "models": [{ "id": "parakeet-v3", "name": "Parakeet v3", "description": "...", "available": true }]
    }
  ],
  "capabilities": {
    "llm": true,
    "text_process": true,
    "text_suggest": true
  },
  "writing_tools": { "post_delivery_ms": 8000 }
}

capabilities object:

Field	Type	Meaning
llm	bool	LLM_BASE_URL + LLM_MODEL are set and LLM is active
text_process	bool	/v1/text/process is open (llm=true AND TEXT_ROUTES_OPEN=true, or auth=true)
text_suggest	bool	/v1/text/suggest is open (same condition as text_process)
text_summarize	bool	/v1/text/summarize is open (same condition as text_process)
formatting	bool	the formatting context key is honoured on cleanup (llm=true)