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/v1

Authentication

Bearer token via API key

Format

JSON request/response

Quickstart

5 minutes

Make 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:

cURLCopy and run in terminal

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:

200 OK

{
  "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:

HTTP Header

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx

Learn more about authentication

Response Format

All responses are returned in JSON format with a consistent structure:

Success Response

{
  "success": true,
  "data": {
    "id": "agent_abc123",
    "name": "Sales Agent",
    ...
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid parameters",
    "details": { ... }
  }
}

Pagination

List endpoints support pagination using limit and offset query parameters:

Example Request

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:

Idempotent Request

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

GETPOSTPATCHDELETE

Calls

Access call logs, transcripts, and recordings

GET

Contacts

Manage your contact database

GETPOSTPATCHDELETE

Campaigns

Create and control outbound campaigns

GETPOSTPATCHDELETE

Channels

View voice and messaging channels

GET

Webhooks

Receive real-time event notifications

Events

Additional Resources

Error Codes

Troubleshoot API errors

Rate Limits

Understand API limits

API Keys

Manage authentication

Need help?

If you have questions about the API, reach out to our support team at support@nutalk.ai.

PreviousAccount Setup NextAuthentication

{ "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 } }

Response Format

All responses are returned in JSON format with a consistent structure:

Success Response

{
  "success": true,
  "data": {
    "id": "agent_abc123",
    "name": "Sales Agent",
    ...
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid parameters",
    "details": { ... }
  }
}

Pagination

List endpoints support pagination using limit and offset query parameters:

Example Request

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:

Idempotent Request

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.