API Reference¶

SpeakNode provides a RESTful API for programmatic access to all platform features. Use the API to create agents, dispatch calls, manage phone numbers, and retrieve conversation data.

Base URL¶

All API requests should be made to:

https://api.speaknode.com

Authentication¶

The API uses Bearer token authentication. Tokens are issued by the platform's Keycloak identity provider.

Include your token in the Authorization header of every request:

curl -X GET https://api.speaknode.com/api/v1/agents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Warning

Keep your access token secret. Do not expose it in client-side code or public repositories. For browser-based integrations, use the widget with its scoped agent token instead.

Tip

Access tokens have a limited lifetime. Use the refresh token flow to obtain new access tokens without re-authenticating.

Interactive Documentation¶

The full API specification is available below as an interactive Swagger UI. You can browse endpoints, view request/response schemas, and try out requests directly.

Common Endpoints¶

Endpoint	Method	Description
`/api/v1/agents`	`GET`	List all agents in the current space
`/api/v1/agents/{id}`	`GET`	Get agent details
`/api/v1/conversations`	`GET`	List conversations with filters
`/api/v1/conversations/{id}`	`GET`	Get conversation details and transcript
`/api/v1/conversations/dispatch`	`POST`	Start an outbound call
`/api/v1/tools`	`GET`	List all tools
`/api/v1/phone-numbers`	`GET`	List imported phone numbers

Note

This table shows a subset of available endpoints. Refer to the Swagger UI above for the complete API specification.

Error Responses¶

The API returns standard HTTP status codes:

Status Code	Meaning
`200`	Success
`201`	Created
`400`	Bad Request -- check your request body or parameters
`401`	Unauthorized -- invalid or expired token
`403`	Forbidden -- insufficient permissions
`404`	Not Found -- resource does not exist
`422`	Validation Error -- request body failed validation
`429`	Rate Limited -- too many requests
`500`	Internal Server Error

Error responses include a JSON body with details:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "The AgentId field is required.",
  "traceId": "00-abc123-def456-00"
}

Rate Limits¶

API requests are subject to rate limiting. If you exceed the limit, you will receive a 429 Too Many Requests response. Wait and retry after the duration indicated in the Retry-After header.