API Reference
REST API overview for Teammates.ai. Authentication methods, key endpoints for Raya, Adam, and Sara, rate limits, error handling, and code examples.
API Overview
The Teammates.ai REST API gives you programmatic access to manage organizations, AI teammates, jobs, candidates, interviews, campaigns, conversations, and billing. All endpoints return JSON responses and use standard HTTP methods (GET, POST, PUT, DELETE). The base URL for all API requests is https://api.teammates.ai/v1.
Authentication
Teammates.ai supports two authentication methods. Use API keys for server-to-server integrations and JWT tokens for user-context requests.
| Method | Header Format | Best For | How to Get |
|---|---|---|---|
| API Key | Authorization: Bearer sk_live_... | Server-to-server integrations, webhooks, automation. | Dashboard > Organization Settings > API Keys. Generate a new key and store it securely. |
| JWT Token | Authorization: Bearer eyJ... | User-context requests, Dashboard integrations. | POST /v1/auth/login with email and password. Token expires after 24 hours; refresh with /v1/auth/refresh. |
Note:Never expose API keys in client-side code or public repositories. Use environment variables on your server.
Key Endpoints
The API is organized around resources. Here are the most commonly used endpoints grouped by domain.
| Domain | Endpoint | Methods | Description |
|---|---|---|---|
| Organizations | /v1/organizations | GET, PUT | Retrieve and update organization settings. |
| Employees | /v1/employees | GET, POST, PUT, DELETE | Manage AI teammates (Raya, Adam, Sara instances). |
| Agents | /v1/employees/:id/agents | GET, POST, PUT | Configure channel agents (chat, email, phone) for each AI teammate. |
| Data Sources | /v1/data-sources | GET, POST, PUT, DELETE | Manage knowledge base content (files, URLs, FAQs). |
| Jobs (Sara) | /v1/jobs | GET, POST, PUT, DELETE | Create and manage job listings for Sara interviews. |
| Candidates (Sara) | /v1/candidates | GET, POST, PUT | Add candidates and retrieve their interview status. |
| Interviews (Sara) | /v1/interviews | GET, POST | Create interviews and retrieve results, scores, and reports. |
| Campaigns (Adam) | /v1/campaigns | GET, POST, PUT | Create and manage outbound sales campaigns. |
| Conversations (Raya) | /v1/conversations | GET, POST | Retrieve support conversations, messages, and resolution status. |
| Usage & Billing | /v1/usage | GET | Check credit balance, usage history, and billing status. |
Rate Limits
API rate limits prevent abuse and ensure consistent performance for all users.
| Limit Type | Limit | Response When Exceeded |
|---|---|---|
| Per-minute | 60 requests/minute per API key | HTTP 429 Too Many Requests |
| Per-day | 10,000 requests/day per API key | HTTP 429 Too Many Requests |
| Batch endpoints | 100 items per batch request | HTTP 400 Bad Request |
Note:If you need higher rate limits, contact support. Use webhooks instead of polling for real-time data. Batch requests wherever possible to reduce call volume.
Code Example: Create an Interview
Here is how to create a new interview for Sara using curl:
```bash curl -X POST https://api.teammates.ai/v1/interviews \ -H "Authorization: Bearer sk_live_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "job_id": "job_abc123", "candidate": { "name": "Jane Smith", "email": "jane@example.com" }, "deadline": "2026-03-01T23:59:59Z", "language": "en" }' ```
Sara creates the interview, generates questions from the job description, and sends the candidate an invitation email with a unique interview link.
Error Handling
The API returns standard HTTP status codes. Error responses include a JSON body with an error code, message, and details field for debugging.
| Status Code | Meaning | Common Cause |
|---|---|---|
| 200 OK | Request succeeded. | Normal response. |
| 201 Created | Resource created. | Successful POST request. |
| 400 Bad Request | Invalid request body or parameters. | Missing required field, invalid JSON, or incorrect data type. |
| 401 Unauthorized | Authentication failed. | Missing, expired, or invalid API key or JWT token. |
| 403 Forbidden | Insufficient permissions. | API key does not have access to the requested resource. |
| 404 Not Found | Resource not found. | Invalid ID or deleted resource. |
| 429 Too Many Requests | Rate limit exceeded. | Wait and retry. Check Retry-After header for delay. |
| 500 Internal Server Error | Server-side error. | Contact support with the request ID from the response headers. |
API Versioning
All endpoints are versioned under /v1. When breaking changes are introduced, a new version (e.g., /v2) is released. The previous version remains available for at least 12 months after a new version launches. Teammates.ai announces version deprecations via email and in-Dashboard notifications at least 90 days before end-of-life.
Frequently Asked Questions
Is the API available on the Free plan?▾
Can I use the API to create interviews for Sara programmatically?▾
How do I handle API errors in my integration?▾
Related Articles
Still need help?
Contact our team