Sophia HTTP API
Base URL and versioning
- Dev:
http://localhost:3000 - Production:
https://api.sophia.cleverhire.ai
Versioned routes use /v1/. GET /health is unversioned (load balancer liveness). Version is in the path only—no version header.
Authentication
| Mechanism | How |
|---|---|
| Workspace users | Authorization: Bearer <Firebase ID token> |
| Candidate join flow | x-candidate-session: <token> after password verify |
| Interview bot | x-internal-token: <BOT_INTERNAL_TOKEN> |
| Stripe webhook | stripe-signature on raw body |
Authenticated workspace routes require an active user in a non-suspended organization. Some routes require admin role. Optional: x-request-id for correlation.
Errors
Failed requests return JSON with error, code, requestId, and optional details (validation paths/messages).
Common codes: VALIDATION_FAILED / MALFORMED_ID (400), UNAUTHENTICATED (401), FORBIDDEN (403), NOT_FOUND (404), CONFLICT / ALREADY_EXISTS (409), INSUFFICIENT_CREDITS (402), RATE_LIMITED (429), INTERNAL (500), DEPENDENCY_UNAVAILABLE (503).
Success bodies are returned directly (no { data: ... } wrapper). Lists that paginate use docs, page, limit, total, hasMore (limit max 100).
API groups
| Group | Endpoints | What it does |
|---|---|---|
| Health | 2 | Liveness probe and smoke test |
| Auth | 6 | Signup, verification, session, logout |
| Team | 10 | Invites, membership, roles |
| Positions | 5 | Job definitions for AI interviews |
| Candidates | 8 | Applicant CRM and resumes |
| Files | 2 | Resume upload URL and parse-only |
| Interviews (workspace) | 10 | Schedule, edit, cancel, list |
| Interviews (candidate) | 6 | Join, lobby, consent, bot connect |
| Interviews (bot) | 10 | Bot lifecycle and runtime updates |
| Notes | 4 | Notes on candidates or interviews |
| Credits & billing | 4 | Balance, ledger, lots, checkout |
| Stripe webhook | 1 | Grant credits after payment |
| Reports | 3 | Read report, status, admin retry |
Full endpoint details → OpenAPI spec
Module-oriented docs → Domain modules