API Reference

Nutalk REST API

Integrate AI voice and messaging agents into your applications with our comprehensive REST API.

Base URL

https://www.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

Verify the key first. Replace YOUR_API_KEY with your key:

cURLCopy and run in terminal

curl https://www.nutalk.ai/v1/auth/verify \
  -H "Authorization: Bearer YOUR_API_KEY"

Get your response

You'll receive a JSON response confirming the key and workspace:

200 OK

{
  "success": true,
  "data": {
    "authenticated": true,
    "api_key": { "name": "Production backend", "prefix": "51e4f2a9" },
    "workspace": { "name": "Acme", "slug": "acme", "status": "active" },
    "verified_at": "2026-05-08T18:45:00.000Z"
  }
}

That's it! You've made your first API call. Now explore the endpoints below to manage agents, calls, contacts, contact lists, campaigns, goals, and competencies.

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://www.nutalk.ai/v1/agents",
  {
    headers: {
      Authorization: `Bearer ${API_KEY}`
    }
  }
);

Python

pip install requests

import requests

response = requests.get(
    "https://www.nutalk.ai/v1/agents",
    headers={
        "Authorization": f"Bearer {API_KEY}"
    }
)

cURL

Command line

curl https://www.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 YOUR_NUTALK_API_KEY

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://www.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

Authentication

Verify API keys before deploying integrations

GET

Agents

Create, manage, and configure AI agents

GETPOSTPATCHDELETE

Calls

Initiate calls and access transcripts and recordings

GETPOST

Contacts

Manage your contact database

GETPOSTPATCHDELETE

Contact Lists

Create and manage reusable contact lists

GETPOSTPATCHDELETE

Campaigns

Create and control outbound campaigns

GETPOSTPATCHDELETE

Goals

Manage agent evaluation goals and targets

GETPOSTPATCHDELETE

Competencies

Manage agent scoring rubrics and competencies

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.

AnteriorAccount Setup SiguienteAuthentication

{ "success": true, "data": { "authenticated": true, "api_key": { "name": "Production backend", "prefix": "51e4f2a9" }, "workspace": { "name": "Acme", "slug": "acme", "status": "active" }, "verified_at": "2026-05-08T18:45:00.000Z" } }

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://www.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.