Public REST API

Nexvio exposes a team-scoped REST API at /api/public/v1 on app.nexvio.ai. Authenticate every request with a nex_ API key issued in Dashboard → Settings → Developer API.

Authentication

All endpoints (except /health) require an Authorization header:

Authorization: Bearer nex_<your-api-key>

The active team is inferred from the key. Do not pass team identifiers in request headers or the URL — the API is already scoped to your team.

Base URL

https://app.nexvio.ai/api/public/v1

Response envelope

Every successful response wraps its payload in a data key:

{ "data": { ... } }

Paginated responses include a meta object:

{ "data": [...], "meta": { "total": 42, "limit": 20, "offset": 0 } }

Error format

Errors return a descriptive JSON object with a machine-readable code:

{
  "error": {
    "code": "not_found",
    "message": "Agent not found",
    "details": {}
  }
}

Code	HTTP status	Meaning
unauthorized	401	Missing or invalid API key
forbidden	403	Key does not have permission for this action
not_found	404	Requested resource does not exist
validation_error	400	Request body or params failed validation
conflict	409	The request conflicts with the current state (for example, publishing a version that is no longer publishable)
contact_duplicate	409	A contact with the same identifying details already exists
payload_too_large	413	Request body exceeds the size limit (for example, an oversized form submission)
rate_limit_exceeded	429	Too many requests
internal_error	500	Unexpected server error

Resource-specific not_found variants (agent_not_found, conversation_not_found, message_not_found, knowledge_not_found, webhook_not_found, form_not_found, submission_not_found, version_not_found) also return 404. Branch on the HTTP status when you only need the general category.

A 401 response also includes a WWW-Authenticate header describing what went wrong — error="invalid_request" when the Authorization header is missing or malformed, or error="invalid_token" when the key itself is invalid, expired, or revoked.

Scopes

Nexvio API keys are team-scoped, not surface-scoped — the same key authenticates both this REST API (/api/public/v1) and the Operator MCP endpoint (/api/mcp/sse). Every key is issued with one or more of the following scopes:

Scope	Surface	Description
team:read	REST	Read access — GET endpoints for agents, versions, conversations, contacts, forms, submissions, webhooks, integrations, knowledge, and assets.
team:write	REST	Write access — all mutating operations (POST, PATCH, PUT, DELETE) including creating agents, publishing versions, creating forms, submitting submissions, managing webhooks, and rotating signing secrets.
mcp:read	Operator MCP	Read access for MCP tools (e.g. listing agents, searching help articles, reading ticket stats).
mcp:write	Operator MCP	Write access for MCP tools (e.g. updating agent settings, drafting help articles, updating ticket status).

Operations that mutate state (those documented as "Requires the team:write scope") will return 403 forbidden if the API key only has team:read. New keys are issued with all four scopes.

Rate limits

Requests are rate-limited per team (all API keys for a team share one counter). The default limit is 60 requests per 60-second sliding window. Plans with higher tier limits may have a higher ceiling — the X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers are included on every response so you can monitor usage.

When the limit is exceeded you will receive a 429 response with the rate_limit_exceeded error code and a Retry-After header (seconds to wait). Back off until the timestamp in X-RateLimit-Reset has passed.

Generating API keys

1. Go to Dashboard → Settings → Developer API (team owners and admins can manage keys).
2. Click Create key, give it a descriptive name, and choose an expiry (30 days, 90 days, 1 year, or never — 90 days is the default and recommended).
3. Copy the key — it is shown only once. Nexvio stores only a SHA-256 hash of the key, so it cannot be recovered later — if you lose it, revoke it and create a new one.

API keys can be rotated or revoked from the same settings page at any time, and work for both the REST API and the Operator MCP endpoint.