Skip to content

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 ​

MechanismHow
Workspace usersAuthorization: Bearer <Firebase ID token>
Candidate join flowx-candidate-session: <token> after password verify
Interview botx-internal-token: <BOT_INTERNAL_TOKEN>
Stripe webhookstripe-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 ​

GroupEndpointsWhat it does
Health2Liveness probe and smoke test
Auth6Signup, verification, session, logout
Team10Invites, membership, roles
Positions5Job definitions for AI interviews
Candidates8Applicant CRM and resumes
Files2Resume upload URL and parse-only
Interviews (workspace)10Schedule, edit, cancel, list
Interviews (candidate)6Join, lobby, consent, bot connect
Interviews (bot)10Bot lifecycle and runtime updates
Notes4Notes on candidates or interviews
Credits & billing4Balance, ledger, lots, checkout
Stripe webhook1Grant credits after payment
Reports3Read report, status, admin retry

Full endpoint details → OpenAPI spec

Module-oriented docs → Domain modules

Sophia AI Interview Platform — Internal Documentation