API reference

Manage a NuTalk workspace from your own code: agents, calls, conversations, contacts, campaigns, scheduling, testing and knowledge. Every endpoint takes and answers JSON over HTTPS.

Base URLhttps://www.nutalk.ai/v1OpenAPI /openapi.json For AI agents /v1/llms.txt

Make your first request

Create a key
In the dashboard, open Settings → API keys and choose what the key may do. Each endpoint names the scope it needs, so give the key only those. The secret is shown once.
Keep it out of your code
Put it in an environment variable on your server. Never ship a key to a browser or a mobile app.
export NUTALK_API_KEY=sk_51e4f2a9_…

Check the key

Any valid key may call GET /v1/auth/verify. It answers with the key's name, prefix and scopes, and the workspace it belongs to. A wrong or revoked key answers 401 invalid_api_key.

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

200Response

{
  "success": true,
  "data": {
    "authenticated": true,
    "api_key": {
      "id": "7b7a0ce4-0000-4000-8000-000000000001",
      "name": "Production backend",
      "prefix": "51e4f2a9",
      "scopes": [
        "agents:read",
        "calls:read",
        "calls:write"
      ]
    },
    "workspace": {
      "id": "d3b85d84-ef8f-4c4a-8d18-3fa23e7fd48a",
      "name": "Acme",
      "slug": "acme",
      "status": "active"
    },
    "verified_at": "2026-10-02T02:19:49.549Z"
  }
}

How every request works

Authentication

Send the workspace key as Authorization: Bearer sk_… on every request. A key reaches only its own workspace; a reseller key (rk_…) names the client in NuTalk-Client-Id. Authentication →

Scopes

Each endpoint names the scope it needs, such as contacts:read. A key without it gets 403 forbidden with the missing scope in details. All scopes →

Pagination

Lists take limit (1–100, default 20) and offset, and answer pagination.has_more.

Idempotency

Calls, messages, bookings, enrollments, imports and other creates take an Idempotency-Key: a retry with the same key and body within 24 hours answers the first result instead of acting twice. Sending a message requires one.

The 25 endpoints that take one

POST /v1/calls
POST /v1/conversations/:id/messages
POST /v1/exclusions
POST /v1/contacts/:id/touches
POST /v1/contact-imports
POST /v1/campaigns
POST /v1/campaigns/:id/enrollments
POST /v1/campaigns/:id/contacts/import
POST /v1/conversions
POST /v1/clinic/locations
POST /v1/clinic/locations/:id/hours
POST /v1/clinic/rooms
POST /v1/clinic/rooms/:id/spots
POST /v1/clinic/doctors
POST /v1/clinic/doctors/:id/days-off
POST /v1/clinic/services
POST /v1/clinic/record-fields
POST /v1/business/appointments
POST /v1/clinic/appointments
POST /v1/clinic/appointments/:id/reschedule
POST /v1/clinic/appointments/:id/cancel
POST /v1/clinic/appointments/:id/status
POST /v1/test-scenarios/:id/runs
POST /v1/agents/:id/test-run-alls
POST /v1/test-run-alls/:id/try-fix

Approvals

When a key asks for it, a delete or change answers 202 with a change request and runs only after an owner or admin approves it. Approvals →

Errors

Every error has success: false, a stable code, a message and, when useful, details. Each response carries X-Request-Id for support. Error codes →

Rate limits

Responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. A 429 says how long to wait in Retry-After. Rate limits →

Resources

318 endpoints in 22 groups. Each page lists every field and error the server checks, generated from the same description as /openapi.json.

Agents29Create agents, version and deploy their instructions, and set their automations, human handoff, memory and Cal.com booking.Calls11Place outbound calls; read transcripts, summaries and recordings.Conversations16Read the inbox, reply, send templates, assign and resolve.Contacts15People and their numbers, custom fields and opt-outs.Contact lists7Group contacts; a list can feed a campaign.Contact imports6Large CSV files, uploaded in parts, read in the background.Campaigns32Outbound calling campaigns: create, enroll, start, pause.Conversions3Bookings, visits, won deals and payments as events, and where people came from.Goals7Yes/no outcomes each evaluated conversation is scored on.Competencies5Behaviors the evaluator rates, with performance levels.Channels41Phone, WhatsApp and web channels: phone lines, their agent and AI mode.Phone numbers6Search numbers for sale and buy one; every purchase waits for approval.Billing4The plan, credits, usage and credit history, read only.Knowledge7Text, files and websites an agent answers from.Automated testing23Scenarios, test runs and test chats before going live.Clinic setup41Locations, rooms, doctors, hours, days off and services.Business scheduling26Hosts, meeting types, availability and calendars.Agenda17Book, reschedule and cancel clinic and business appointments.Webhooks6Signed call, conversation and conversion events sent to your server.Approvals2Follow the deletes and changes that wait for an owner.Resellers13One reseller key across every client workspace.

What you can do, and where

The API covers the work an integration repeats: contacts, campaigns, calls and conversations, and setting up agents, phone lines, scheduling and testing. Connecting numbers and accounts, an agent's own voice and billing stay in the dashboard. The MCP server runs the same endpoints, and changes only what each key allows.

Area	REST API	MCP server	In the dashboard only
Agents	Partly. Create an agent with its instructions, language, identity and call opening, edit them (each change is a new version), read any version, deploy one, archive and restore it, and set its automations (WhatsApp follow-ups, appointment reminders, closing inactive conversations), follow-up emails, transfers to a person or a PBX extension, knowledge and memory, how it books (its booking method, clinic booking, business meeting types, Cal.com) and the REST actions it calls on your API.	14 read tools, 11 that set it up (when the key lets MCP set up the workspace), 4 that act on conversations or reach customers (when the key allows it; setup ones also need setup allowed)	The agent's voice; restaurant booking; its data connectors; the REST connector's token or password; and connecting the workspace's Cal.com account.
Channels and numbers	Partly. List channels with their number, status and health; create a phone channel on one of the workspace's numbers with an agent and a voice, change its number, turn its incoming calls on or off, and change its voice and language; delete a channel of any type but the Zoom channel; rename a channel; put an agent on it or take one off; switch a messaging channel's AI mode (off, testing, live, paused) and list, add or remove the numbers it answers while testing, or on Messenger and Instagram the people, added from their chat or with a code; set its default operator, WhatsApp's human-like timing and message grouping, and whether the team's first message opens a chat on hold; choose its scheduling; set its evaluation and caller screening, and how a phone channel's outbound calls get through phone menus. Create a website widget and change its agents, modes, allowed websites, greeting and look; create a Live Room and change its link, questions, on-screen sources, look and whether it takes calls. List the workspace's phone numbers, search the numbers for sale in the US, Canada and Mexico, check what a purchase needs and buy one (every purchase waits for an owner's or admin's approval), and remove a verified caller ID. For a WhatsApp API number, list, create (for Meta's review), delete and restore its message templates and choose what fills their fields; read and change the business profile customers see (about, description, category, address, email, websites); and try a held account's templates again once a payment method is added in Meta.	16 read tools, 15 that set it up (when the key lets MCP set up the workspace), 16 that act on conversations or reach customers (when the key allows it; setup ones also need setup allowed)	Bringing numbers from your phone provider or releasing them, adding a card, the Mexican compliance profile, connecting WhatsApp, Instagram, Messenger or Zoom, assigning AiBox lines, the widget's avatar and voice for calls, voicemail settings, and a WhatsApp number's other settings (its display name, photo, registration, blue check and two-step PIN).
Scheduling (clinic, business, restaurant)	Partly. Clinic: locations, rooms, doctors, services, weekly hours, days off, clinic settings and the patient record's questions. Business meetings: hosts (the NuTalk login each one is and the HubSpot owners they stand for), their weekly availability and days off, company closures, meeting types and which calendars each host's connection uses. The agenda: list clinic and business appointments with the dashboard's filters (who booked them, the line, the patient's confirmation, what awaits an outcome, the meetings search), read each one's history, book, reschedule and cancel them, record outcomes and find free times.	32 read tools, 51 that set it up (when the key lets MCP set up the workspace), 5 that act on conversations or reach customers (when the key allows it; setup ones also need setup allowed)	Connecting calendar accounts (Google, Microsoft), iCal links, and restaurant scheduling.
Contacts, lists and imports	Yes. Create, find, update and delete contacts; define custom fields (create, rename, archive) and set their values; create lists and add or remove members, and see which lists a contact is on; tag or untag many contacts at once; import CSV files of up to 4 GiB into a list or a campaign; opt contacts out and add numbers to the exclusion list; read and set the rules every campaign follows (don't call a number again for a while); with Conversions on, record where a contact came from (click ids, ad, UTMs).	10 read tools, 16 that set it up (when the key lets MCP set up the workspace), 3 that act on conversations or reach customers (when the key allows it; setup ones also need setup allowed)	A contact's preferred language, and pausing their automations.
Campaigns	Partly. Create a campaign with the steps the dashboard builds for its purpose and calling agent, or any steps of your own; set its channel, the number whose callers join it, calling hours, caps, retries, duplicates rule, callbacks and longest call; load contacts before the start or link contact lists; start, pause and archive it, enroll or import contacts; run an A/B test of agents and voices, promote a variant or move one to its agent's live version; add, change, reorder and delete its stages; read its analytics; read each contact's status, step, next call and result, set its lead response or stage, call it again or take it out; list and cancel the calls to come.	10 read tools, 12 that set it up (when the key lets MCP set up the workspace), 11 that act on conversations or reach customers (when the key allows it; setup ones also need setup allowed)	Test runs, advanced retries (time windows, stopping rules) and the campaign's own outbound webhooks.
Conversions	Partly. Read the workspace's conversions (bookings, visits, calls, goals, won deals, payments), each with its key, who recorded it, its proof and where the person came from; record a qualified lead, a won deal, a payment or an outcome of your own under your own id. During the beta, only for workspaces NuTalk switched Conversions on for.	2 read tools, 1 that act on conversations or reach customers (when the key allows it; setup ones also need setup allowed)	Switching Conversions on for the workspace: a NuTalk super admin does it during the beta.
Calls	Yes. Place a call (or a free test call to one of your verified test numbers), follow a queued call, end a live call, list calls, read a call's transcript, summary, outcome and recording, and read, add, change and delete the notes your team adds to it.	4 read tools, 3 that set it up (when the key lets MCP set up the workspace), 2 that act on conversations or reach customers (when the key allows it; setup ones also need setup allowed)	A call's evaluation scores.
Conversations	Yes. Read conversations and their messages; assign, resolve, reopen, archive and unarchive, and list the teammates a conversation can be assigned to; pause and resume the AI, on one conversation or up to 50 at once; ask the AI to reply now, or to run its failed reply again; send a text or an approved WhatsApp template, and list the templates a chat can send.	5 read tools, 12 that act on conversations or reach customers (when the key allows it; setup ones also need setup allowed)	Sending files or voice notes. A conversation with someone who has not written yet starts from a campaign.
Testing and evaluation	Partly. Create, update and delete the goals and competencies conversations are scored against, and read an agent's goal progress and analytics (or compare two of its versions); write test scenarios for an agent, run them against its versions, run all of them at once and read What to fix, try a fix on the draft, hide a fix, mark a verdict the judge got wrong, re-score runs and read each simulated conversation's scores; read a version's release summary; chat with an agent to try it; place a free test call, and add, verify and remove the numbers test calls go to.	14 read tools, 20 that set it up (when the key lets MCP set up the workspace), 1 that act on conversations or reach customers (when the key allows it; setup ones also need setup allowed)	Drafting simulated customers with AI, a campaign's test runs and the evaluation results of each call.
Webhooks	Yes. Register, update and delete signed endpoints for call, conversation and conversion events, and read each endpoint's delivery log.	3 read tools, 1 that set it up (when the key lets MCP set up the workspace), 2 that act on conversations or reach customers (when the key allows it; setup ones also need setup allowed)	Nothing
Knowledge	Partly. List an agent's knowledge; add text, a web page (or a whole site) or, over REST, a file; read a source again and delete it.	3 read tools, 5 that set it up (when the key lets MCP set up the workspace)	Viewing a source's text, and replacing a file in place (add the new one and delete the old one instead).
Approvals	Read only. Deletes and changes made with a key can wait for an owner's or admin's approval (set per key); the key follows each request and what it became.	2 read tools	Approving or rejecting a request, and choosing which keys need approval.
Team and permissions	No endpoint	No tools	Inviting people, roles, which conversations each person sees, and the API keys themselves: a key is created, edited and revoked in Settings only.
Plan, credits and billing	Read only. Read the plan, the currency, the credit period and the credits (balance, used, allowance, bought), the usage report by day, agent, channel and campaign, the credit history and the billing alerts, with a key an owner or admin gave billing access.	4 read tools	Invoices, cards and payment methods, buying credits, changing the plan, and the alerts' settings (a reseller key reads its clients' usage and invoices).

Who can create a key, and what a key can reach, is in Authentication.

Make your first request

Create a key

In the dashboard, open Settings → API keys and choose what the key may do. Each endpoint names the scope it needs, so give the key only those. The secret is shown once.

Keep it out of your code

Put it in an environment variable on your server. Never ship a key to a browser or a mobile app.

export NUTALK_API_KEY=sk_51e4f2a9_…

Check the key

Any valid key may call GET /v1/auth/verify. It answers with the key's name, prefix and scopes, and the workspace it belongs to. A wrong or revoked key answers 401 invalid_api_key.

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

200Response

{
  "success": true,
  "data": {
    "authenticated": true,
    "api_key": {
      "id": "7b7a0ce4-0000-4000-8000-000000000001",
      "name": "Production backend",
      "prefix": "51e4f2a9",
      "scopes": [
        "agents:read",
        "calls:read",
        "calls:write"
      ]
    },
    "workspace": {
      "id": "d3b85d84-ef8f-4c4a-8d18-3fa23e7fd48a",
      "name": "Acme",
      "slug": "acme",
      "status": "active"
    },
    "verified_at": "2026-10-02T02:19:49.549Z"
  }
}

How every request works

Authentication

Send the workspace key as Authorization: Bearer sk_… on every request. A key reaches only its own workspace; a reseller key (rk_…) names the client in NuTalk-Client-Id. Authentication →

Scopes

Each endpoint names the scope it needs, such as contacts:read. A key without it gets 403 forbidden with the missing scope in details. All scopes →

Pagination

Lists take limit (1–100, default 20) and offset, and answer pagination.has_more.

Idempotency

The 25 endpoints that take one

POST /v1/calls
POST /v1/conversations/:id/messages
POST /v1/exclusions
POST /v1/contacts/:id/touches
POST /v1/contact-imports
POST /v1/campaigns
POST /v1/campaigns/:id/enrollments
POST /v1/campaigns/:id/contacts/import
POST /v1/conversions
POST /v1/clinic/locations
POST /v1/clinic/locations/:id/hours
POST /v1/clinic/rooms
POST /v1/clinic/rooms/:id/spots
POST /v1/clinic/doctors
POST /v1/clinic/doctors/:id/days-off
POST /v1/clinic/services
POST /v1/clinic/record-fields
POST /v1/business/appointments
POST /v1/clinic/appointments
POST /v1/clinic/appointments/:id/reschedule
POST /v1/clinic/appointments/:id/cancel
POST /v1/clinic/appointments/:id/status
POST /v1/test-scenarios/:id/runs
POST /v1/agents/:id/test-run-alls
POST /v1/test-run-alls/:id/try-fix

Approvals

When a key asks for it, a delete or change answers 202 with a change request and runs only after an owner or admin approves it. Approvals →

Errors

Every error has success: false, a stable code, a message and, when useful, details. Each response carries X-Request-Id for support. Error codes →

Rate limits

Responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. A 429 says how long to wait in Retry-After. Rate limits →

What you can do, and where

Area	REST API	MCP server	In the dashboard only
Agents	Partly. Create an agent with its instructions, language, identity and call opening, edit them (each change is a new version), read any version, deploy one, archive and restore it, and set its automations (WhatsApp follow-ups, appointment reminders, closing inactive conversations), follow-up emails, transfers to a person or a PBX extension, knowledge and memory, how it books (its booking method, clinic booking, business meeting types, Cal.com) and the REST actions it calls on your API.	14 read tools, 11 that set it up (when the key lets MCP set up the workspace), 4 that act on conversations or reach customers (when the key allows it; setup ones also need setup allowed)	The agent's voice; restaurant booking; its data connectors; the REST connector's token or password; and connecting the workspace's Cal.com account.
Channels and numbers	Partly. List channels with their number, status and health; create a phone channel on one of the workspace's numbers with an agent and a voice, change its number, turn its incoming calls on or off, and change its voice and language; delete a channel of any type but the Zoom channel; rename a channel; put an agent on it or take one off; switch a messaging channel's AI mode (off, testing, live, paused) and list, add or remove the numbers it answers while testing, or on Messenger and Instagram the people, added from their chat or with a code; set its default operator, WhatsApp's human-like timing and message grouping, and whether the team's first message opens a chat on hold; choose its scheduling; set its evaluation and caller screening, and how a phone channel's outbound calls get through phone menus. Create a website widget and change its agents, modes, allowed websites, greeting and look; create a Live Room and change its link, questions, on-screen sources, look and whether it takes calls. List the workspace's phone numbers, search the numbers for sale in the US, Canada and Mexico, check what a purchase needs and buy one (every purchase waits for an owner's or admin's approval), and remove a verified caller ID. For a WhatsApp API number, list, create (for Meta's review), delete and restore its message templates and choose what fills their fields; read and change the business profile customers see (about, description, category, address, email, websites); and try a held account's templates again once a payment method is added in Meta.	16 read tools, 15 that set it up (when the key lets MCP set up the workspace), 16 that act on conversations or reach customers (when the key allows it; setup ones also need setup allowed)	Bringing numbers from your phone provider or releasing them, adding a card, the Mexican compliance profile, connecting WhatsApp, Instagram, Messenger or Zoom, assigning AiBox lines, the widget's avatar and voice for calls, voicemail settings, and a WhatsApp number's other settings (its display name, photo, registration, blue check and two-step PIN).
Scheduling (clinic, business, restaurant)	Partly. Clinic: locations, rooms, doctors, services, weekly hours, days off, clinic settings and the patient record's questions. Business meetings: hosts (the NuTalk login each one is and the HubSpot owners they stand for), their weekly availability and days off, company closures, meeting types and which calendars each host's connection uses. The agenda: list clinic and business appointments with the dashboard's filters (who booked them, the line, the patient's confirmation, what awaits an outcome, the meetings search), read each one's history, book, reschedule and cancel them, record outcomes and find free times.	32 read tools, 51 that set it up (when the key lets MCP set up the workspace), 5 that act on conversations or reach customers (when the key allows it; setup ones also need setup allowed)	Connecting calendar accounts (Google, Microsoft), iCal links, and restaurant scheduling.
Contacts, lists and imports	Yes. Create, find, update and delete contacts; define custom fields (create, rename, archive) and set their values; create lists and add or remove members, and see which lists a contact is on; tag or untag many contacts at once; import CSV files of up to 4 GiB into a list or a campaign; opt contacts out and add numbers to the exclusion list; read and set the rules every campaign follows (don't call a number again for a while); with Conversions on, record where a contact came from (click ids, ad, UTMs).	10 read tools, 16 that set it up (when the key lets MCP set up the workspace), 3 that act on conversations or reach customers (when the key allows it; setup ones also need setup allowed)	A contact's preferred language, and pausing their automations.
Campaigns	Partly. Create a campaign with the steps the dashboard builds for its purpose and calling agent, or any steps of your own; set its channel, the number whose callers join it, calling hours, caps, retries, duplicates rule, callbacks and longest call; load contacts before the start or link contact lists; start, pause and archive it, enroll or import contacts; run an A/B test of agents and voices, promote a variant or move one to its agent's live version; add, change, reorder and delete its stages; read its analytics; read each contact's status, step, next call and result, set its lead response or stage, call it again or take it out; list and cancel the calls to come.	10 read tools, 12 that set it up (when the key lets MCP set up the workspace), 11 that act on conversations or reach customers (when the key allows it; setup ones also need setup allowed)	Test runs, advanced retries (time windows, stopping rules) and the campaign's own outbound webhooks.
Conversions	Partly. Read the workspace's conversions (bookings, visits, calls, goals, won deals, payments), each with its key, who recorded it, its proof and where the person came from; record a qualified lead, a won deal, a payment or an outcome of your own under your own id. During the beta, only for workspaces NuTalk switched Conversions on for.	2 read tools, 1 that act on conversations or reach customers (when the key allows it; setup ones also need setup allowed)	Switching Conversions on for the workspace: a NuTalk super admin does it during the beta.
Calls	Yes. Place a call (or a free test call to one of your verified test numbers), follow a queued call, end a live call, list calls, read a call's transcript, summary, outcome and recording, and read, add, change and delete the notes your team adds to it.	4 read tools, 3 that set it up (when the key lets MCP set up the workspace), 2 that act on conversations or reach customers (when the key allows it; setup ones also need setup allowed)	A call's evaluation scores.
Conversations	Yes. Read conversations and their messages; assign, resolve, reopen, archive and unarchive, and list the teammates a conversation can be assigned to; pause and resume the AI, on one conversation or up to 50 at once; ask the AI to reply now, or to run its failed reply again; send a text or an approved WhatsApp template, and list the templates a chat can send.	5 read tools, 12 that act on conversations or reach customers (when the key allows it; setup ones also need setup allowed)	Sending files or voice notes. A conversation with someone who has not written yet starts from a campaign.
Testing and evaluation	Partly. Create, update and delete the goals and competencies conversations are scored against, and read an agent's goal progress and analytics (or compare two of its versions); write test scenarios for an agent, run them against its versions, run all of them at once and read What to fix, try a fix on the draft, hide a fix, mark a verdict the judge got wrong, re-score runs and read each simulated conversation's scores; read a version's release summary; chat with an agent to try it; place a free test call, and add, verify and remove the numbers test calls go to.	14 read tools, 20 that set it up (when the key lets MCP set up the workspace), 1 that act on conversations or reach customers (when the key allows it; setup ones also need setup allowed)	Drafting simulated customers with AI, a campaign's test runs and the evaluation results of each call.
Webhooks	Yes. Register, update and delete signed endpoints for call, conversation and conversion events, and read each endpoint's delivery log.	3 read tools, 1 that set it up (when the key lets MCP set up the workspace), 2 that act on conversations or reach customers (when the key allows it; setup ones also need setup allowed)	Nothing
Knowledge	Partly. List an agent's knowledge; add text, a web page (or a whole site) or, over REST, a file; read a source again and delete it.	3 read tools, 5 that set it up (when the key lets MCP set up the workspace)	Viewing a source's text, and replacing a file in place (add the new one and delete the old one instead).
Approvals	Read only. Deletes and changes made with a key can wait for an owner's or admin's approval (set per key); the key follows each request and what it became.	2 read tools	Approving or rejecting a request, and choosing which keys need approval.
Team and permissions	No endpoint	No tools	Inviting people, roles, which conversations each person sees, and the API keys themselves: a key is created, edited and revoked in Settings only.
Plan, credits and billing	Read only. Read the plan, the currency, the credit period and the credits (balance, used, allowance, bought), the usage report by day, agent, channel and campaign, the credit history and the billing alerts, with a key an owner or admin gave billing access.	4 read tools	Invoices, cards and payment methods, buying credits, changing the plan, and the alerts' settings (a reseller key reads its clients' usage and invoices).

Who can create a key, and what a key can reach, is in Authentication.