API Overview

Nexvio provides three complementary integration surfaces. Choose based on what you are building and who is making the requests.

---

Public REST API (bearer API key)

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

The Public REST API is a team-scoped JSON REST API. It is the right choice when you need programmatic control over agents, conversations, contacts, knowledge, or integrations from your own backend or automation scripts.

Auth: Authorization: Bearer nex_<key> — generate keys in Dashboard → Settings → Developer API.

Response shape: Successful responses use { "data": ... }. Errors use { "error": { "code": "...", "message": "..." } }.

Endpoints include:

• GET /health — verify the API is reachable (no auth required)
• GET /team — resolve the team bound to the current API key
• GET|POST /agents, GET|PATCH|DELETE /agents/{agentId} — agent CRUD
• GET /agents/{agentId}/conversations — list and inspect conversations and messages
• GET|POST|PATCH|DELETE /agents/{agentId}/contacts — contact management
• GET /integrations, DELETE /integrations/{integrationId} — connected integrations
• POST /agents/{agentId}/chat — playground-style AI chat
• GET|POST|DELETE /knowledge — knowledge base items
• POST|DELETE /agents/{agentId}/assets/icon|profile-picture — branding assets
• GET|POST /agents/{agentId}/versions, GET|PATCH /agents/{agentId}/versions/{versionId} — agent version management
• POST /agents/{agentId}/versions/{versionId}/publish — publish a draft version
• POST /agents/{agentId}/versions/{versionId}/discard — archive a draft version
• GET|POST /forms, GET|PUT /forms/{formId} — form definitions
• GET /forms/templates — team-owned form templates
• GET|POST /forms/{formId}/submissions, GET|PUT /forms/{formId}/submissions/{submissionId} — form submissions
• GET|POST /webhooks, GET|PATCH|DELETE /webhooks/{webhookId} — webhook subscriptions
• POST /webhooks/{webhookId}/rotate-secret — rotate a webhook signing secret
• GET /webhooks/{webhookId}/deliveries — delivery attempt logs
• POST /webhooks/{webhookId}/test — send a synthetic test event

See the full endpoint reference in the API Reference section.

---

MCP (Model Context Protocol)

Nexvio also exposes two MCP endpoints for AI clients and custom agent builders.

Operator MCP (SSE)

Endpoint: GET /api/mcp/sse on app.nexvio.ai

Use this when you want to connect an AI client — Claude Desktop, Cursor, or ChatGPT — so it can manage your Nexvio workspace using natural language. It exposes tools for agents, contacts, helpdocs, tickets, and analytics, scoped to your team.

Auth: Bearer token using a nex_ API key from Dashboard → Settings → Developer API, or an OAuth access token. This is the same key type used by the Public REST API above — a single key carries scopes for both surfaces (team:read/team:write for REST, mcp:read/mcp:write for MCP), so you don't need separate keys per surface.

Transport: Server-Sent Events (SSE). See Agent MCP Server for client setup instructions.

External Agent MCP (Streamable HTTP)

Endpoint: POST /external-agent/mcp on app.nexvio.ai

Use this when you are building an agent that needs to read and act on Nexvio data — reply to conversations, manage tickets, create tasks, or handle approvals — on behalf of your team. It uses the newer Streamable HTTP transport and is designed for server-to-server use.

Auth: Bearer token using an external agent API key from Dashboard → Agents → [Your Agent] → API Keys.

Transport: Streamable HTTP (MCP 2025-03-26). See External Agents to get started.

---

Comparison

	Public REST API	Operator MCP	External Agent MCP
Endpoint	/api/public/v1/*	/api/mcp/sse	/external-agent/mcp
Auth	nex_ team API key	nex_ team API key or OAuth	External agent API key
Transport	HTTPS JSON	SSE	Streamable HTTP
Best for	Backend automation, scripts, integrations	AI assistants (Claude, Cursor, ChatGPT)	Custom server-side agent you build
Docs	API Reference	Agent MCP Server	External Agents

---

Widget integration

The embeddable agent widget (@nexvio-ai/widget-js) is a separate, client-side integration that does not use MCP or the REST API. It loads the widget frame in the browser and optionally verifies logged-in users with JWT or HMAC. See the Widget SDK reference.

Outbound events

Nexvio can push events to your server when contacts, tickets, or actions change. This uses standard HTTPS webhooks with HMAC-SHA256 signatures. See Outbound Webhooks.