API Reference
API Reference
Complete documentation for all REST endpoints.
The AI Interview System exposes a RESTful HTTP API with a global prefix of /api/v1. All endpoints return JSON and follow consistent error format. Interactive documentation is available via Swagger UI at https://mayaapi.teamcast.ai/api/docs.
Base URL
https://mayaapi.teamcast.ai/api/v1| Environment | Base URL |
|---|---|
| Development | https://mayaapi.teamcast.ai/api/v1 |
| Swagger UI | https://mayaapi.teamcast.ai/api/docs |
| OpenAPI JSON | https://mayaapi.teamcast.ai/api/docs-json |
| Agent Card | https://mayaapi.teamcast.ai/.well-known/agent.json |
Guides
Authentication
JWT, API Key, and OAuth 2.0 authentication methods.
Interviews
Create and manage interview lifecycle.
Candidate Access
OTP verification and session management.
Workflow
HITL state machine transitions and history.
Users & Tenants
User management and tenant configuration.
Admin Monitoring
System metrics, agent status, dashboard data.
Authentication
All endpoints (except health checks and agent card) require one of three authentication methods:
| Method | Header | Use Case |
|---|---|---|
| JWT Bearer | Authorization: Bearer <token> | Admin UI, recruiter operations |
| API Key | X-API-Key: <key> | External integrations, server-to-server calls |
| OAuth 2.0 | Authorization: Bearer <token> | Scoped client credentials |
Endpoint Summary
| Module | Endpoints | Auth |
|---|---|---|
| Authentication | POST /auth/login, POST /oauth/token | None |
| Interviews | GET/POST /interviews, GET/PUT/DELETE /interviews/:id, POST /:id/conduct, POST /:id/assess | JWT |
| Integration API | POST /integration/interviews, GET /integration/interviews/:runId, ... | API Key / OAuth2 |
| Candidate Access | GET /candidate-access/:token/info, POST .../request-otp, ... | Token-based |
| Workflow | POST /workflow/interviews/:id/transition, GET .../state, GET .../history, ... | JWT |
| Users | GET/POST /users, GET/PUT/DELETE /users/:id, POST /:id/change-password | JWT |
| Tenants | GET/POST /tenants, GET/PUT/DELETE /tenants/:id | JWT |
| API Keys | GET/POST /api-keys, GET/DELETE /api-keys/:id | JWT |
| OAuth Clients | GET/POST /oauth-clients, GET/DELETE /oauth-clients/:id | JWT |
| MCP Skills | POST /mcp/skills/validate, GET/POST /mcp/skills, DELETE /mcp/skills/:id | JWT |
| TTS | POST /tts/synthesize | None |
| Invitations | POST /invitations/tenants/:id, POST /invitations/platforms/:id, GET/POST /:token | JWT / Public |
| Recording | GET /recording/:sessionId/chunks, GET /recording/:sessionId/stream | JWT |
| Admin Monitoring | GET /admin/metrics/system|agents|workflows, GET /admin/dashboard/interviews | JWT |
| Health | GET /health/live, GET /health/ready | None |
Error Format
All errors follow a consistent JSON structure:
{
"statusCode": 400,
"message": "Validation failed",
"error": "Bad Request",
"details": [
{
"field": "candidateEmail",
"message": "Must be a valid email address"
}
]
}| Status Code | Meaning |
|---|---|
| 200 | Success |
| 201 | Created |
| 400 | Bad Request — validation error |
| 401 | Unauthorized — missing or invalid auth |
| 403 | Forbidden — insufficient permissions |
| 404 | Not Found |
| 429 | Too Many Requests — rate limit (100 req/min) |
| 500 | Internal Server Error |
/api/docs provides interactive documentation where you can test endpoints directly. Use the “Authorize” button to add your JWT token or API key.