For developers and agents

API reference

Every public endpoint, the webhooks and the schemas, read from the same OpenAPI file that machines use — nothing here is written separately.

NexiAgent public API · version 1.0.0 · OpenAPI 3.1 · openapi.json— openapi.json is the file for machines: the same content, as JSON.

Endpoints

GEThttps://nexiagent.com/api/chat/hellogetChatSiteHello

Check that a chat site may appear on this page, and fetch its appearance

The widget's first call. Answers whether the requesting origin is allowed, records the install (the panel shows 'seen on your website'), and returns the greeting, title, accent colour and the branding line. Called with the page's Origin; a server-side call without one is refused with origin_not_allowed.

Parameters

Name	In	Type	Description
X-API-Version	header	string ∈ "1"	Pin the API version the request is written against. Optional: without it the current version (1) answers. A version that does not exist is refused with 400 `unsupported_version` rather than answered by another version.
k*	query	string	The site's public key from the panel. Not a secret: it ships in the page's HTML.
Origin*	header	string (uri)	The page's origin, set by the browser. Must be on the site's allowed-domains list.

Responses

200The origin is allowed; the widget may draw itself.→ ChatHello (application/json)headers: X-API-Version, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Deprecation, Sunset
400The key is missing, or X-API-Version names a version that does not exist.→ Error (application/json)headers: X-API-Version, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Deprecation, Sunset
403The page's origin is not allowed for this site. The response echoes the origin so the exact string can be approved in the panel.→ Error (application/json)headers: X-API-Version, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Deprecation, Sunset
404No active site has this key (the same answer for a paused site, so keys cannot be enumerated).→ Error (application/json)headers: X-API-Version, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Deprecation, Sunset
429Rate limited.→ Error (application/json)headers: X-API-Version, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Deprecation, Sunset, Retry-After

POSThttps://nexiagent.com/api/chatsendChatMessage

Send one visitor message to the site's assistant and stream the reply

One conversational turn. The reply streams back as Server-Sent Events: start (with the conversationId), any number of delta (text fragments), then done — or error. A returning visitorId continues its conversation; a new one starts a conversation, which is the unit the plan is metered in. Requires the page's Origin to be on the site's allowed-domains list.

Parameters

Name	In	Type	Description
X-API-Version	header	string ∈ "1"	Pin the API version the request is written against. Optional: without it the current version (1) answers. A version that does not exist is refused with 400 `unsupported_version` rather than answered by another version.
Origin*	header	string (uri)	The page's origin, set by the browser.

Request body · application/json · ChatMessageRequest

sendChatMessage request body
Field	Type	Description
siteKey*	string	The site's public key.
visitorId*	string	A random string the client keeps per visitor; the same value continues the same conversation.
message*	string
locale	string	BCP-47 tag of the page, e.g. pt-PT. Optional.

Responses

200The assistant's reply, streamed.→ ChatStreamEvent (text/event-stream)headers: X-API-Version, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Deprecation, Sunset
400The body is not JSON, a required field is missing, or X-API-Version names a version that does not exist.→ Error (application/json)headers: X-API-Version, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Deprecation, Sunset
403The page's origin is not allowed for this site.→ Error (application/json)headers: X-API-Version, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Deprecation, Sunset
404No active site has this key.→ Error (application/json)headers: X-API-Version, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Deprecation, Sunset
413The message is longer than 2000 characters.→ Error (application/json)headers: X-API-Version, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Deprecation, Sunset
429Rate limited (per IP, per conversation, or new conversations per site).→ Error (application/json)headers: X-API-Version, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Deprecation, Sunset, Retry-After
503The site's monthly allowance is spent, or the assistant is temporarily unavailable.→ Error (application/json)headers: X-API-Version, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Deprecation, Sunset

GEThttps://status.nexiagent.com/api/status.jsongetPlatformStatus

Current status of every platform component

Public, unauthenticated. Answers 503 when the status backend itself cannot be reached, so a monitor can tell 'could not measure' from 'all fine'. Also reachable as https://nexiagent.com/api/status.json, which redirects here.

Parameters

Name	In	Type	Description
X-API-Version	header	string ∈ "1"	Pin the API version the request is written against. Optional: without it the current version (1) answers. A version that does not exist is refused with 400 `unsupported_version` rather than answered by another version.

Responses

200Status snapshot.→ PlatformStatus (application/json)headers: X-API-Version, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Deprecation, Sunset
400The X-API-Version header names a version that does not exist.→ Error (application/json)headers: X-API-Version, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Deprecation, Sunset
429Rate limited (120 reads per minute per IP).→ Error (application/json)headers: X-API-Version, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Deprecation, Sunset, Retry-After
503The status backend is unreachable.→ Error (application/json)headers: X-API-Version, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Deprecation, Sunset

Webhooks

Deliveries NexiAgent makes to an endpoint of yours. The path is the one you configure in the panel.

POSThttps://your-endpoint.examplereceiveAssistantEvent

An event captured by the customer's assistant, delivered to the customer's endpoint

Available from the Pro plan. Configured in the panel under 'Send to your tools'. Each delivery carries x-nexiagent-event, x-nexiagent-timestamp (seconds since 1970, included in the signature) and x-nexiagent-signature (hex HMAC-SHA256 of {timestamp}.{raw body} with the site's signing key). Reject deliveries older than five minutes. Answer 2xx within 10 seconds; otherwise NexiAgent retries six times over about half a day (1 min, 5 min, 25 min, ~2 h, ~10 h). Only https and only public addresses are accepted as endpoints.

Parameters

Name	In	Type	Description
x-nexiagent-event*	header	WebhookEventName
x-nexiagent-timestamp*	header	string	Unix seconds; part of the signed string.
x-nexiagent-signature*	header	string	HMAC-SHA256(`{timestamp}.{body}`), hex.

Request body · application/json · WebhookDelivery

receiveAssistantEvent request body
Field	Type	Description
event*	WebhookEventName
at*	string (date-time)
data*	object

Responses

2XXDelivered. Anything else is retried.

Schemas

Error object

Error fields
Field	Type	Description
error*	string ∈ "invalid", "invalid_json", "invalid_request", "message_too_long", "rate_limited", "unknown", "unknown_site", "origin_not_allowed", "limit_reached", "unavailable", "not_found", "method_not_allowed", "unsupported_version"	Stable machine-readable code.
message	string	One readable sentence.
docs	string (uri)	Where to read more.
origin	string \| null	On origin_not_allowed: the host that was refused, to approve in the panel.

ChatHello object

ChatHello fields
Field	Type	Description
ok*	boolean = true
appearance*	object	Set in the panel. Missing fields mean 'use the widget default'.
brand*	null \| object	Null on the Ultra plan (white label). The 'AI assistant' disclosure is not affected by this.

ChatMessageRequest object

ChatMessageRequest fields
Field	Type	Description
siteKey*	string	The site's public key.
visitorId*	string	A random string the client keeps per visitor; the same value continues the same conversation.
message*	string
locale	string	BCP-47 tag of the page, e.g. pt-PT. Optional.

ChatStreamEvent object

One Server-Sent Events frame of the reply; the response body is a sequence of these. event is the SSE event name and data its JSON payload: start first, then any number of delta (append text in order), then done — or error at any point.

ChatStreamEvent fields
Field	Type	Description
event*	string ∈ "start", "delta", "done", "error"
data*	start \| delta \| done \| error

PlatformStatus object

PlatformStatus fields
Field	Type	Description
ok*	boolean
status*	string ∈ "up", "degraded", "down"
stale	boolean	True when the reading is cached rather than live.
read_at	string (date-time)
components*	array of object
incidents	array of object

WebhookEventName string ∈ "booking.created", "message.taken", "lead.captured", "screening.recorded", "document.requested", "handover"

WebhookDelivery object

WebhookDelivery fields
Field	Type	Description
event*	WebhookEventName
at*	string (date-time)
data*	object

Headers

Header	Type	Description
X-API-Version	string ∈ "1"	The API version that answered; currently 1.
Deprecation	string	Present only on a deprecated operation: when it was deprecated (RFC 9745; `@` followed by Unix seconds).
Sunset	string	Present only on a deprecated operation: the HTTP-date after which it stops answering, at least 180 days after Deprecation (RFC 8594).
RateLimit-Limit	integer	Requests allowed in the current window.
RateLimit-Remaining	integer	Requests left in the current window.
RateLimit-Reset	integer	Seconds until the window resets.
Retry-After	integer	Seconds to wait before retrying.

Policies

NexiAgent (a NexiChat product) sells two AI assistants for small businesses: a call answering assistant and a 24/7 website chat.

This document describes everything a third party can call or receive. There is no management API: assistants are configured in the customer panel at https://my.nexiagent.com, or installed by the NexiAgent team.

Authentication. The chat endpoints carry no secret. A site's public key (pk_live_…) identifies the subscription, and the request is accepted only when its Origin header is on that site's allowed-domains list. Webhooks are authenticated the other way round: NexiAgent signs each delivery with HMAC-SHA256 and the receiver verifies it.

Rate limits. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until the window resets). A 429 adds Retry-After. Defaults: 30 chat messages per minute per IP, 60 per hour per conversation, 60 new conversations per 10 minutes per site, 60 /api/chat/hello loads per minute per IP, 120 status reads per minute per IP.

Errors. Every error is JSON: { "error": "<stable_code>", "message": "<sentence>", "docs": "<url>" }. Unknown paths under /api also answer in JSON.

Prices shown on the site are without VAT; VAT (23%) is added at checkout.

Versioning. This is version 1 of the API; every response says so in X-API-Version, and a request may pin it with the same header (a version that does not exist is refused with 400 unsupported_version). Paths are unversioned. Within a version, fields are only ever added: nothing is removed, renamed or retyped, and no new required input appears. A breaking change ships as a new version under new paths (/api/v2/…) while this version keeps answering. The policy is also machine-readable in x-versioning-policy.

Deprecation. A deprecated operation announces itself in its own responses: Deprecation (RFC 9745) gives the date it was deprecated, Sunset (RFC 8594) the date it stops answering — never less than 180 days later — and the operation is marked deprecated: true here with its replacement in the description. The same notice appears on the developer page. Nothing is deprecated today. See x-deprecation-policy.

Discovery. This document is served at /openapi.json and listed in /.well-known/api-catalog; /llms.txt explains the site to a language model, and every public page answers in Markdown to Accept: text/markdown. Webhook deliveries carry an at timestamp and an id in data, so a receiver can deduplicate retries.

Idempotency. POST /api/chat is a conversational turn and is not idempotent: sending the same message twice asks the assistant twice. Webhook deliveries are retried on failure and may arrive more than once; treat data.id as the idempotency key.