Nida

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.

Canonical Base URL
https://www.nida-os.com
Agent Token Type
nid_agent_…
Rate Limit
60 req/min (default)
Agent API · Authenticated

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

GET/.well-known/mcp

Discovery endpoint for tools/modules/capabilities. Returns a scoped view when a token is supplied.

Auth: Optional Bearer token
GET/api/agent/workspace-state

Workspace snapshot and key entity counts. Designed as the first call for agent context hydration.

Auth: Bearer nid_agent_*
POST/api/agent/execute

Unified action router for module/action calls with scope checks and rate limiting.

Auth: Bearer nid_agent_*
GET|POST|DELETE/api/agent/tokens

Create/list/revoke dedicated agent tokens. Plaintext token only returned at creation.

Auth: Authenticated workspace admin

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.

The token value is a credential — treat it like a password and rotate it immediately if exposed.

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
Default token limit is 60 requests/minute unless overridden during token creation.

Public API · No session required

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

Questions or support?

Reach the API team and we'll help you wire it up.

Contact API Support