API Documentation - talentoBot AI

Introduction

The talentoBot API allows you to programmatically create interviews, manage candidates, and retrieve interview results. Our REST API uses JSON for request and response payloads.

Base URL

          HTTPS
https://api.talentobot.com/v1
        

API Version

Current version: v1

All endpoints are prefixed with the version number. We'll maintain backward compatibility and announce breaking changes at least 3 months in advance.

Need Help?

Contact our API support team at [email protected] or visit the Help Center.

Authentication

The talentoBot API uses API keys for authentication. Include your API key in the Authorization header of all requests.

Getting Your API Key

Log in to your talentoBot dashboard
Navigate to Settings → API Keys
Click "Generate New API Key"
Copy and store your key securely (it won't be shown again)

Authentication Example

          CURL
curl 'https://api.talentobot.com/v1/projects' \
  -H 'Authorization: Bearer YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json'
        

Keep Your API Key Secret:

Never share your API key publicly or commit it to version control. Rotate keys regularly and revoke compromised keys immediately.

Rate Limits

To ensure service quality, API requests are rate limited based on your plan:

Plan	Requests per Minute	Requests per Hour
Free Trial	10	100
Pro	60	1,000
Enterprise	300	10,000

Rate Limit Headers

Every API response includes rate limit information:

          HTTP
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1609459200
        

Handling Rate Limits

If you exceed the rate limit, you'll receive a 429 Too Many Requests response. Implement exponential backoff and retry logic in your applications.

Error Handling

The API uses standard HTTP status codes and returns error details in JSON format.

HTTP Status Codes

Code	Status	Description
200	OK	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Invalid request parameters
401	Unauthorized	Invalid or missing API key
404	Not Found	Resource not found
429	Too Many Requests	Rate limit exceeded
500	Server Error	Internal server error

Error Response Format

          JSON
{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: project_name",
    "param": "project_name"
  }
}
        

Projects

Projects represent interview configurations. Each project contains instructions for Tami and generates unique interview links.

POST /projects

Create a new interview project.

Request Parameters

Parameter	Type	Required	Description
`project_name`	string	Required	Name of the position or project
`instructions`	string	Required	Instructions for Tami AI
`template_id`	string	Optional	ID of template to use
`company_name`	string	Optional	Company name shown to candidates

Example Request

            CURL
curl -X POST 'https://api.talentobot.com/v1/projects' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "project_name": "Senior React Developer",
    "instructions": "Ask about React, TypeScript, and state management",
    "company_name": "Acme Corp"
  }'
          

Example Response

            JSON
{
  "id": "proj_abc123",
  "project_name": "Senior React Developer",
  "interview_url": "https://talentobot.com/i/abc123xyz",
  "token": "abc123xyz",
  "created_at": "2025-01-15T10:30:00Z",
  "status": "active"
}
          

GET /projects

List all your interview projects.

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of results (default: 20, max: 100)
`offset`	integer	Pagination offset (default: 0)
`status`	string	Filter by status: active, completed, expired

Example Response

            JSON
{
  "data": [
    {
      "id": "proj_abc123",
      "project_name": "Senior React Developer",
      "status": "active",
      "sessions_count": 5,
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}
          

GET /projects/{project_id}

Retrieve details of a specific project.

DELETE /projects/{project_id}

Delete a project. This action is irreversible.

Sessions

Sessions represent completed interviews. Retrieve session data to access transcripts, scores, and AI analysis.

GET /projects/{project_id}/sessions

List all interview sessions for a project.

Example Response

JSON { "data": [ { "id": "sess_xyz789", "candidate_email": "[email protected]", "status": "completed", "overall_score": 85, "recommendation": "strong_hire", "started_at": "2025-01-16T14:00:00Z", "completed_at": "2025-01-16T14:22:00Z" } ] }

GET /sessions/{session_id}

Get full details including transcript and analysis.

Example Response

JSON { "id": "sess_xyz789", "candidate_email": "[email protected]", "status": "completed", "scores": { "overall": 85, "technical": 92, "communication": 81, "culture_fit": 82 }, "recommendation": "strong_hire", "messages": [ { "role": "assistant", "content": "Hi! Tell me about your React experience.", "created_at": "2025-01-16T14:00:00Z" }, { "role": "user", "content": "I have 5 years of React experience...", "created_at": "2025-01-16T14:01:15Z" } ], "ai_summary": "Strong technical skills with deep React knowledge..." }

Webhooks

Webhooks allow you to receive real-time notifications when events occur (e.g., interview completed).

Supported Events

interview.completed - Candidate completes interview
interview.started - Candidate starts interview
project.created - New project created

Webhook Payload Example

JSON { "event": "interview.completed", "timestamp": "2025-01-16T14:22:00Z", "data": { "session_id": "sess_xyz789", "project_id": "proj_abc123", "candidate_email": "[email protected]", "overall_score": 85 } }

Webhook Configuration:

Configure webhooks in Dashboard → Settings → Webhooks. You'll need to verify endpoint ownership via a challenge-response.

SDKs & Libraries

Official SDKs are coming soon. For now, use any HTTP client library in your language of choice.

Example: JavaScript/Node.js

          JavaScript
const axios = require('axios');

const client = axios.create({
  baseURL: 'https://api.talentobot.com/v1',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

// Create a project
const project = await client.post('/projects', {
  project_name: 'Senior React Developer',
  instructions: 'Ask about React and TypeScript'
});

console.log('Interview URL:', project.data.interview_url);
        

Example: Python

          Python
import requests

API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://api.talentobot.com/v1'

headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
}

# Create a project
response = requests.post(
    f'{BASE_URL}/projects',
    headers=headers,
    json={
        'project_name': 'Senior React Developer',
        'instructions': 'Ask about React and TypeScript'
    }
)

project = response.json()
print(f'Interview URL: {project["interview_url"]}')
        

Changelog

Version 1.0 (January 2025)

Initial API release
Projects, Sessions, and Templates endpoints
Webhook support for interview events
OAuth 2.0 authentication

Stay Updated:

Subscribe to our API changelog to receive notifications about new features, deprecations, and breaking changes.