API reference
Everything you need to connect your agent to Nod
Overview
Your agent communicates with Nod through a REST API, a persistent WebSocket connection, and webhooks. All endpoints use the same authentication: your agent ID and secret.
Your agent
CLI, server, workflow
→
Nod API
REST + WebSocket
→
Nod app
Mobile / Web / Desktop
Base URL
https://api.asknod.ai
For local development, set NOD_API_URL:
NOD_API_URL=http://localhost:8000
# WebSocket: wss://api.asknod.ai/ws/agent/{agent_id}Authentication
Every request includes two headers:
| Header | Description |
|---|---|
| X-Nod-Agent-Id | Your agent's unique identifier |
| X-Nod-Secret | Your agent's secret key |
You get both when you create an agent in the Nod app. See Authentication for code examples.
Error handling
{ "detail": "Human-readable error message" }| Status | Meaning |
|---|---|
| 400 | Bad request — missing or invalid fields |
| 401 | Invalid or missing credentials |
| 403 | Not authorized for this resource |
| 404 | Not found |
| 409 | Conflict — already exists or already resolved |
API resources
Authentication
Agent ID + secret, WebSocket auth handshake
Messages
Send and receive chat messages, reports, media
Requests
Approvals, choices, questions, and permissions
Tasks
Poll, start, and complete scheduled tasks
Activity
Log actions and show processing indicators
WebSocket
Real-time protocol and message types
Webhooks
Outbound delivery and inbound task triggers