Nida API Reference
Production reference for Nida's headless agent API — intended for autonomous agents (Hermes, Codex, Claude) and backend integrators — plus the public integration surface for websites, forms, webhooks, and checkout flows.
Full endpoint contracts, scopes, and error semantics for workspace operations run by autonomous agents.
Authentication
Agent tokens
Token format:
nid_agent_[a-z0-9]{32}
Creation flow:
1) Authenticated admin creates the token in the dashboard (Settings → API Keys → Agent Keys)
2) Plain token is shown once at creation
3) Only a salted server-side hash is stored — the plaintext cannot be recovered
Scope recommendation:
- Start least-privilege: only the scopes the agent needs (e.g. contacts:read, leads:read, leads:update)
- "*" exists for convenience but should be reserved for trusted, tightly-scoped automations
Request headers
Authorization: Bearer nid_agent_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Content-Type: application/json Accept: application/json Important: Use https://www.nida-os.com directly. Do not send to an apex domain that redirects cross-origin — some clients drop the Authorization header on redirect.
Core Endpoints
/.well-known/mcpDiscovery endpoint for tools/modules/capabilities. Returns a scoped view when a token is supplied.
/api/agent/workspace-stateWorkspace snapshot and key entity counts. Designed as the first call for agent context hydration.
/api/agent/executeUnified action router for module/action calls with scope checks and rate limiting.
/api/agent/tokensCreate/list/revoke dedicated agent tokens. Plaintext token only returned at creation.
Quickstart (cURL)
# 1) Discovery
curl -s https://www.nida-os.com/.well-known/mcp \
-H "Authorization: Bearer nid_agent_..."
# 2) Workspace Snapshot
curl -s https://www.nida-os.com/api/agent/workspace-state \
-H "Authorization: Bearer nid_agent_..."
# 3) Execute Action
curl -s https://www.nida-os.com/api/agent/execute \
-H "Authorization: Bearer nid_agent_..." \
-H "Content-Type: application/json" \
-d '{
"module": "workspace",
"action": "state",
"workspace_id": "workspace_id",
"params": {}
}'
Module Contract
POST /api/agent/execute accepts:
{
"module": "contact | lead | website | form | automation | ...",
"action": "list | get | create | update | delete | state | publish | trigger",
"workspace_id": "workspace_id",
"params": {}
}
Scope evaluation is performed per module:action mapping. Unknown modules return 400. Actions that modify, send, or delete data may return 202 — the action is queued for human approval in the dashboard and must not be replayed by the agent.
Errors, Status Codes, and Limits
200 OK - Successful request 202 Accepted - Action queued for dashboard approval (requires_approval: true, approval_id returned) 400 Bad Request - Missing module/action - Unknown module - Unsupported action for module 401 Unauthorized - Missing token / invalid token / revoked or expired token 403 Forbidden - Scope does not allow action - Workspace mismatch (cross-workspace access denied) 429 Too Many Requests - Token rate limit exceeded 500 Internal Server Error - Unhandled backend exception
Endpoints intended for external integrations. They may still require provider-specific signatures or secrets. Authenticated agent endpoints are intentionally excluded from this surface.
Public Endpoint Reference
Public endpoints: - POST /api/functions/submitForm - GET|POST /api/inbound-webhook?workspace_id=... - POST /api/public-booking - POST /api/payments-checkout - POST /api/stripe-webhook?workspace_id=...
Forms — submit
POST https://www.nida-os.com/api/functions/submitForm
Content-Type: application/json
{
"form_id": "form_123",
"data": {
"name": "Jane Smith",
"email": "jane@example.com",
"message": "Interested in services"
},
"source": {
"page_url": "https://www.nida-os.com/contact",
"domain": "www.nida-os.com"
}
}
Inbound webhooks
POST https://www.nida-os.com/api/inbound-webhook?workspace_id=workspace_id
X-Nida-Secret: YOUR_INBOUND_SECRET
X-Nida-Event: webhook.received
Content-Type: application/json
{
"first_name": "Sarah",
"last_name": "Chen",
"email": "sarah@techflow.ai",
"phone": "+155****4567",
"company": "TechFlow AI",
"tags": ["automation", "webhook"]
}
Note:
This triggers webhook_received automations.
It creates leads only if your automation includes a Create Lead step.
Public booking
POST https://www.nida-os.com/api/public-booking
Content-Type: application/json
{
"public_slug": "strategy-call"
}
Payments checkout
POST https://www.nida-os.com/api/payments-checkout
Content-Type: application/json
{
"product_id": "prod_123",
"quantity": 1,
"return_origin": "https://www.nida-os.com"
}
Stripe webhook target:
POST https://www.nida-os.com/api/stripe-webhook?workspace_id=workspace_id
Security & Reliability Notes
- Use the canonical host
https://www.nida-os.comfor integration calls. - Validate webhook signatures/secrets at the provider level (Stripe / inbound secret header).
- Keep workspace IDs out of public client-side code when possible — proxy through your backend.
- Rotate any exposed secrets immediately.
Questions or support?
Reach the API team and we'll help you wire it up.
Contact API Support