API Reference
Nutalk REST API
Integrate AI voice and messaging agents into your applications with our comprehensive REST API.
Base URL
https://dev.nutalk.ai/v1Authentication
Bearer token via API key
Format
JSON request/response
Quickstart
5 minutesMake your first API call in under 5 minutes. All you need is an API key.
Get your API key
Go to Settings → API Keys and create a new key. Keep it secure.
Make your first request
Copy this command and replace YOUR_API_KEY with your key:
curl https://dev.nutalk.ai/v1/agents \
-H "Authorization: Bearer YOUR_API_KEY"Get your response
You'll receive a JSON response with your agents:
{
"success": true,
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Sales Agent",
"description": "Handles inbound sales calls",
"deployed_version": { "id": "v-abc123", "version_label": "v1.2" }
}
],
"pagination": { "total": 1, "limit": 20, "offset": 0, "has_more": false }
}That's it! You've made your first API call. Now explore the endpoints below to manage agents, calls, contacts, and campaigns.
Installation
Use the Nutalk API with your favorite language. No SDK required—just HTTP requests.
Node.js / TypeScript
Using native fetch
// No installation needed!
// Use native fetch (Node 18+)
const response = await fetch(
"https://dev.nutalk.ai/v1/agents",
{
headers: {
Authorization: `Bearer ${API_KEY}`
}
}
);Python
pip install requests
import requests
response = requests.get(
"https://dev.nutalk.ai/v1/agents",
headers={
"Authorization": f"Bearer {API_KEY}"
}
)cURL
Command line
curl https://dev.nutalk.ai/v1/agents \
-H "Authorization: Bearer $API_KEY"Any Language
REST API compatible
Works with any HTTP client:
- • PHP:
Guzzle,curl - • Ruby:
HTTParty,Faraday - • Go:
net/http - • Java:
HttpClient
Authentication
All API requests require authentication using a Bearer token. Include your API key in the Authorization header:
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxResponse Format
All responses are returned in JSON format with a consistent structure:
{
"success": true,
"data": {
"id": "agent_abc123",
"name": "Sales Agent",
...
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid parameters",
"details": { ... }
}
}Pagination
List endpoints support pagination using limit and offset query parameters:
GET /v1/agents?limit=20&offset=40| Parameter | Type | Default | Description |
|---|---|---|---|
| limit | integer | 20 | Number of items to return (max 100) |
| offset | integer | 0 | Number of items to skip |
Response Pagination Object
List responses include a pagination object:
{
"success": true,
"data": [...],
"pagination": {
"total": 142, // Total items available
"limit": 20, // Items per page
"offset": 40, // Current offset
"has_more": true // More items available
}
}💡 Pagination Best Practice
Use has_more to check if more pages exist, rather than comparing offset + limit to total. This is more reliable as totals may change between requests.
Idempotent Requests
For POST requests, you can include an Idempotency-Key header to safely retry requests without duplicating resources:
curl -X POST https://dev.nutalk.ai/v1/agents \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: unique-request-id-12345" \
-H "Content-Type: application/json" \
-d '{"name": "My Agent", "instructions": "..."}'How it works
If you retry a request with the same idempotency key within 24 hours, the API returns the original response instead of creating a duplicate.
Best practice
Use a UUID or combine a user ID with a timestamp. Keys should be unique per distinct operation.
API Endpoints
Agents
Create, manage, and configure AI agents
Calls
Access call logs, transcripts, and recordings
Contacts
Manage your contact database
Campaigns
Create and control outbound campaigns
Channels
View voice and messaging channels
Webhooks
Receive real-time event notifications
Additional Resources
Need help?
If you have questions about the API, reach out to our support team at support@nutalk.ai.