API reference

The Nedzo API is organized around REST. It uses standard HTTP methods, returns JSON responses, and uses standard HTTP status codes.

Base URL

https://api.nedzo.ai/v1

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

See Authentication for more details.

If you’re using an account-scoped API key, most endpoints require a workspaceId in the request body or query string. Workspace-scoped keys infer it automatically. See Workspace ID and Request Scope for details on which to use and how to find your workspace ID.

Plan access

Every paid plan can use these endpoints:

Contacts (/v1/contacts)
Make a call (POST /v1/call, deprecated: use POST /v1/conversations/call)
Conversation logs (GET /v1/conversations and GET /v1/conversations/{id})

The send endpoints follow the channels on your plan, not the tier:

Calls, SMS and email (POST /v1/conversations/call, /sms and /email) on every plan
WhatsApp, Instagram and Messenger (POST /v1/conversations/whatsapp, /instagram and /messenger) on Pro and up

A send on a channel your plan does not include returns a 403 that names the channel, for example "detail": "Your plan does not include WhatsApp.". Everything else is for VIP only. That covers agents and their knowledge, actions and settings, custom actions, MCP servers, calendars, phone numbers, the knowledge library, workflows, campaigns, templates, workspaces and workspace billing. Stopping a contact in a campaign is VIP only too, under both its new path and the old /v1/outbound-campaigns path. Each of those pages carries a “VIP plan only” note. A new endpoint is VIP only unless its page says every plan can use it. On other plans these endpoints return a 403:

{
  "type": "https://api.nedzo.ai/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "This API is available on the VIP plan. Your plan can use the Contacts, Call and conversation log APIs.",
  "instance": "/v1/agents",
  "requiredPlan": "vip",
  "feature": "fullApiAccess"
}

To use them, move to VIP. See Plans. Every endpoint returns a 402 when the account has no plan, or its subscription is not active.

Request Format

For POST, PUT, and PATCH requests, send JSON in the request body:

curl -X POST https://api.nedzo.ai/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Agent", "workspaceId": "789e4567-e89b-12d3-a456-426614174000"}'

Response Format

All responses are JSON. Successful responses return the requested data:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "My Agent",
  "createdAt": "2024-01-15T10:30:00Z"
}

Errors

Errors follow the RFC 7807 Problem Details format:

{
  "type": "https://api.nedzo.ai/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Agent not found"
}

HTTP Status Codes

Code	Description
`200`	Success
`201`	Created
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Not allowed for this key or account, for example an endpoint your plan does not include. See Plan access
`404`	Not Found - Resource doesn’t exist
`409`	Conflict - Resource already exists or conflicts with existing state
`422`	Validation Error - Request failed validation
`429`	Too Many Requests - Rate limited
`500`	Internal Server Error
`502`	Bad Gateway - Upstream service error

Pagination

List endpoints support pagination via query parameters:

Parameter	Description	Default
`limit`	Number of items per page	Varies by endpoint, see each list page. Contacts: 100, up to 1,000
`offset`	Number of items to skip	0

Contacts and wallet transactions return { items, total, limit, offset, hasMore }: keep adding limit to offset while hasMore is true. Other list endpoints return an array.

GET /v1/contacts?limit=50&offset=100

Rate Limiting

Write requests on the public API (creating contacts, sending messages, starting calls) run at 1 per second per account. Every key on the account shares that one rate, account keys and workspace keys together.

VIP: writes can queue. If you send 10 in the same second, 1 starts now and the other 9 wait their turn, starting 1 per second. Each waiting request stays open and gets its normal response when it runs. A write that would have to wait more than 9 seconds to start gets a 429.
Other plans: no queue. A second write in the same second gets a 429.

A 429 comes with a Retry-After header (in seconds) saying when to retry. Read endpoints (GET) are not part of this limit. Starting a call also checks your plan’s concurrent call limit. At the limit, the call is not placed and you get a 429 such as concurrent call limit reached: 5 of 5 in use, with Retry-After. Calls are never queued. If the limit can’t be checked, you get a 503 with Retry-After, and no call is placed.

API Reference

Workspaces

Agents

Phone Numbers

Contacts

Knowledge

Templates

Campaigns

Calls

Workflows

Conversations

API reference

Base URL

Authentication

Plan access

Request Format

Response Format

Errors

HTTP Status Codes

Rate Limiting

​Base URL

​Authentication

​Plan access

​Request Format

​Response Format

​Errors

​HTTP Status Codes

​Pagination

​Rate Limiting

Base URL

Authentication

Plan access

Request Format

Response Format

Errors

HTTP Status Codes

Pagination

Rate Limiting