llms.txt

# Open AI Hay API

> FastAPI backend providing chat, research, and translation via pydantic-ai agents with SSE streaming, web search/crawl tools (Brave + crawl4ai), and persistent conversation history with ownership checks.

Important notes:

- Primary routes:
  - /api/chat (list, stream chat, history)
  - /api/research (lead agent orchestrating parallel subagents, citations)
  - /api/translate/url, /api/translate/file (streamed translation)
  - /api/featured (daily curated items)
  - /api/metrics/* (aggregations over conversation runs)
  - /api/auth/* (token/guest/refresh/logout)
  - /api/contact/* (support, waitlist)
  - /healthz, /health, /health/detailed
- Authentication:
  - Bearer JWT required for: /api/chat, /api/research, /api/translate, /api/metrics/*
  - Get tokens:
    - POST /api/auth/token { identifier }
    - POST /api/auth/token/guest
    - POST /api/auth/refresh (refresh cookie rotates)
  - Ownership: conversations scoped via feature_params.user_id; enforced in protected routes
- Rate limits (per IP):
  - /api/chat: 20/min; /api/research: 10/min; /api/translate: 30/min; default: 50/min
  - Provider RPM guard via internal invoker with provider-aware retries
- Streaming:
  - Server-Sent Events (SSE), media_type: text/event-stream; charset=utf-8
  - Common events: ai_message, conversation_created, error
  - Chat extras: search_results, fetch_url_results
  - Research extras: lead_thinking, lead_answer, web_search_query, web_search_results, subagent_completed, final_report
- Minimal request shapes:
  - ChatRequest: { message: string; conversation_id?: UUID; media?: BinaryContentIn[] }
  - ResearchRequest: { query: string; conversation_id?: UUID; media?: BinaryContentIn[] }
  - TranslateURLRequest: { url: string; message: string; target_lang: string; source_lang?: string; conversation_id?: UUID }
  - TranslateFileRequest: { message: string; target_lang: string; source_lang?: string; media: BinaryContentIn[]; conversation_id?: UUID }
  - BinaryContentIn: { data: base64; media_type: string; identifier?: string }
- Agents and tools:
  - chat_agent tools: search_web(query,n), fetch_url_content(urls)
  - research subagent tools: web_search(query,max_results), web_fetch(urls)
  - research lead tool (deferred): run_parallel_subagents(prompts)
- Web discovery:
  - Search: Brave API (requires BRAVE_API_KEY), shared 1.1s throttle
  - Crawl: crawl4ai markdown extraction with pruning; optional deep crawl
- Persistence:
  - ConversationMessageRun.messages stored as JSONB (ModelMessage adapter; bytes base64)
  - History is appended chronologically and passed back to agents
- Security & cache:
  - Security headers added; /api/chat, /api/research, /api/translate responses are no-store/no-cache
- Examples (SSE):

```
# Chat stream
curl -N -X POST https://<host>/api/chat \
  -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json' \
  -d '{"message":"Xin chào"}'

# Research stream
curl -N -X POST https://<host>/api/research \
  -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json' \
  -d '{"query":"Tóm tắt tình hình AI gần đây"}'

# Translate URL stream
curl -N -X POST https://<host>/api/translate/url \
  -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com","message":"Dịch sang tiếng Việt","target_lang":"vi"}'
```

Optional:

- LLM providers (defaults): google: gemini-3-flash-preview; research models also Gemini with thinking enabled
- Environment:
  - Required: DATABASE_URL
  - Important: JWT_SECRET_KEY (prod), BRAVE_API_KEY, LOGFIRE_TOKEN
  - Keys: GOOGLE_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY
  - CORS: RAILWAY_PUBLIC_DOMAIN, HOST_URL, ALLOWED_ORIGINS
  - Email: SMTP_* or RESEND_*; SUPPORT_* addresses
  - Privacy: COLLECT_CLIENT_IP, ANALYTICS_IP_SALT
- Answering guidelines:
  - Use chat vs research vs translate appropriately
  - Include auth in protected examples
  - Prefer original sources over aggregators; provide citations when using web content