Docs/REST API

Developer

REST API

The Talknex API is a standard REST API with predictable resource-oriented URLs, Bearer token auth, and JSON request/response bodies.

Base URL & authentication

# Base URL

https://api.talknex.ai/v1

# All requests must include:

Authorization: Bearer <your-api-key>

Content-Type: application/json

API keys are created in Settings → API Keys. Each key is scoped to your organization. Keys have no expiry but can be revoked at any time.

Placing a call

# POST /v1/calls

curl -X POST https://api.talknex.ai/v1/calls \
  -H "Authorization: Bearer $TALKNEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_8f3c",
    "to": "+14155550192",
    "from": "+18005551234",
    "metadata": { "leadId": "lead_4421" }
  }'

# Response

{
  "id": "call_9xkz3",
  "status": "initiated",
  "agentId": "agent_8f3c",
  "to": "+14155550192",
  "createdAt": "2026-05-05T10:23:00Z"
}

Endpoints

Agents

GET/agents

List all agents in your organization.

POST/agents

Create a new agent.

GET/agents/:id

Retrieve a single agent by ID.

PATCH/agents/:id

Update agent configuration.

DELETE/agents/:id

Delete an agent.

Calls

POST/calls

Initiate an outbound call.

GET/calls

List call history with pagination and filters.

GET/calls/:id

Get call details, transcript, and sentiment.

DELETE/calls/:id

Delete call record and recording.

Phone Numbers

GET/phone-numbers

List all phone numbers in your account.

POST/phone-numbers

Purchase and provision a new number.

PATCH/phone-numbers/:id

Update routing config or assigned agent.

DELETE/phone-numbers/:id

Release a number back to Twilio.

Knowledge

GET/knowledge/collections

List all knowledge collections.

POST/knowledge/collections

Create a new collection.

POST/knowledge/collections/:id/documents

Upload a document or submit text chunks.

DELETE/knowledge/collections/:id/documents/:docId

Remove a document.

Contacts

GET/contacts

List contacts with search and filter.

POST/contacts

Create a contact.

PATCH/contacts/:id

Update contact details or CRM fields.

Rate limits & errors

Rate limits

100 requests per minute per API key. Exceeded requests receive a 429 Too Many Requests response with a Retry-After header.

Error format

{
  "error": {
    "code": "validation_error",
    "message": "agentId is required",
    "field": "agentId"
  }
}

HTTP status codes

200

Success

201

Resource created

400

Bad request — invalid parameters

401

Unauthorized — missing or invalid API key

403

Forbidden — resource belongs to another org

404

Not found

429

Rate limit exceeded

500

Internal server error — retry with exponential backoff

WebSocket transcript stream

Subscribe to a live call's transcript in real-time via WebSocket:

import { Talknex } from '@talknex/sdk';

const client = new Talknex({ apiKey: process.env.TALKNEX_API_KEY });

client.calls.on('call_9xkz3', 'transcript', (chunk) => {
  console.log(`[${chunk.role}] ${chunk.text}`);
  // [agent] Hi, this is Aria from Northridge Clinics...
  // [caller] I'd like to book an appointment
});

client.calls.on('call_9xkz3', 'tool_call', (event) => {
  console.log(`Tool called: ${event.tool} with `, event.args);
});

← Bookings & Calendar Webhooks