Conviro API · v1 · stable

Ship an AI support agent in 5 minutes

A REST API and webhooks for resolving tickets, capturing leads, and handing off to humans — backed by your own knowledge base, without you building the orchestration.

Start building API reference Get API key

Base URL: api.conviro.io/v1
Auth: Bearer token
Response: JSON · p50 ~450ms

zsh — conviro

$ curl -s api.conviro.io/v1/api/sessions/sess_3f2a/messages \
  -H "Authorization: Bearer cvr_live_***" \
  -d '{"content":"How do I return an order?"}'

# 200 OK — 412ms
{
  "requestId": "req_1H8zKj9m2QrT",
  "latencyMs": 412,
  "intent": "refund.request",
  "confidence": 0.94,
  "model": "conviro-resolve-2",
  "message": { "content": "..." }
}

Quick start

Your first successful request

Three steps. Copy-pasteable. You will see a real AI response within sixty seconds — or skip signup entirely and try it from your terminal right now.

Try without an API key — right now

5 req/min per IP

curl -X POST https://conviro.io/api/developers/demo \
  -H "Content-Type: application/json" \
  -d '{"content": "I want to return my last order"}'

1
Create an API key
Go to Settings → API Keys and create a key with the chat:write scope. It is shown once — store it in your secret manager.
Get API key
2
Send a message
POST to /sessions/:id/messages with a Bearer token. Use your existing session id, or create one first with POST /sessions.
3
Handle the response
You get back requestId, latencyMs, the AI reply, the detected intent, a confidence score, and suggested actions. Route low-confidence answers to a human.

curl -X POST https://api.conviro.io/v1/api/sessions/SESSION_ID/messages \
  -H "Authorization: Bearer cvr_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Can I return an item I bought yesterday?"}'

Response

200 OK · application/json

{
  "requestId": "req_1H8zKj9m2QrT",
  "latencyMs": 412,
  "sessionId": "sess_3f2a9e4b",
  "intent": "refund.request",
  "confidence": 0.94,
  "model": "conviro-resolve-2",
  "message": {
    "id": "msg_a12b7c",
    "role": "assistant",
    "content": "Items bought in the last 30 days can be returned. I've started the return for you.",
    "createdAt": "2026-04-14T10:22:03.412Z"
  },
  "suggestedActions": [
    { "type": "create_ticket", "label": "Open return" }
  ]
}

Playground

Try it right now — no signup

Real HTTP requests to a rate-limited demo endpoint. Every response shows requestId, latencyMs, intent, and confidence.

Live endpoint

Demo agent

POST /api/developers/demo

Simulate

Hi 👋 I'm a live demo. Try a preset, click a use-case above, or type your own.

greetingconf 1.00

What the API returned

{
  "intent": "greeting",
  "confidence": 1,
  "model": "conviro-resolve-2",
  "message": {
    "role": "assistant",
    "content": "Hi 👋 I'm a live demo. Try a preset, click a use-case above, or type your own."
  }
}

The demo endpoint is rate limited to 5 req/min per IP. A real API key gets 60 rpm by default (configurable).

Use cases

What teams actually build

Click any card to run it live in the playground — you’ll see the real API response within a second.

Reference

API surface

The endpoints you will use most. Base URL: https://api.conviro.io/v1/api

Full reference

Method	Path	Required scope	Description
POST	/sessions	`chat:write`	Create a new chat session
GET	/sessions/:id	`chat:read`	Retrieve a session with its messages
POST	/sessions/:id/messages	`chat:write`	Send a message and get AI response
POST	/knowledge	`kb:write`	Add a knowledge base item
DELETE	/knowledge/:id	`kb:write`	Delete a knowledge base item
GET	/analytics/summary	`analytics:read`	Get a workspace analytics summary
POST	/webhooks	`webhooks:write`	Register a webhook endpoint

chat:readRead sessions and messages

chat:writeCreate sessions and send messages

kb:readRead knowledge base items

kb:writeCreate and delete knowledge base items

analytics:readRead analytics data

webhooks:writeManage webhook endpoints

SDKs

Libraries & clients

We’re shipping official SDKs in phases. The REST API is small, stable, and easy to wrap — you don’t have to wait.

Node.js / TypeScript

Official · coming soon

// @conviro/sdk — in private beta. The REST API
// already works great with fetch/axios today.

PHP

Official · coming soon

// composer require conviro/sdk — in private beta.
// Use the cURL example below in the meantime.

Python

Community

# No official SDK yet — the REST API is small enough
# that plain `requests` or `httpx` works well.

Go, Ruby, C#

Use the REST API directly

// No SDK — any HTTP client works. The auth header
// is the only thing you need.

Browse the cookbook WooCommerce pluginWorking snippets for embeds, webhooks, CRM bridges, and platform plugins.

Errors

Predictable error shapes

Every non-2xx response uses the same JSON envelope. Include requestId when you contact support.

Status	Name	When it happens
400	Bad Request	The request body or parameters are invalid.
401	Unauthorized	Missing or invalid API key.
403	Forbidden	API key is valid but lacks the required scope.
404	Not Found	The requested resource does not exist.
429	Too Many Requests	Rate limit exceeded. Respect the Retry-After header.
500	Server Error	Something went wrong on our side. Retry with backoff.

Response body

application/json

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "API key is missing or invalid.",
  "requestId": "req_1H8z...",
  "docsUrl": "https://conviro.io/developers#errors"
}

On 429, respect the Retry-After header. On 5xx, retry with exponential backoff up to three attempts.

Webhooks

Real-time events, verified

We sign every delivery with HMAC-SHA256. Failed deliveries retry three times with exponential backoff. A circuit breaker quarantines repeatedly failing endpoints for 60s.

Events

session.startedA new chat session is created
session.closedA chat session is closed
session.escalatedA session is handed off to a human agent
message.newA new message is sent in a session
lead.capturedA lead is captured from a chat
handoff.requestedA visitor requests a human agent
csat.submittedA CSAT rating is submitted
ticket.createdA support ticket is created
ticket.resolvedA support ticket is resolved
ai.failedAI response generation failed

Payload

POST your-endpoint · application/json

{
  "event": "session.closed",
  "deliveryId": "whk_4T2u...",
  "timestamp": "2026-04-14T10:22:03.412Z",
  "data": {
    "sessionId": "sess_3f2a...",
    "chatbotId": "bot_123",
    "visitorId": "v_789",
    "csatScore": 5,
    "messageCount": 12
  }
}

Verify the signature

node.js

// Node.js — HMAC verification
import crypto from 'crypto';

const signature = req.headers['x-webhook-signature'];
const body = JSON.stringify(req.body);

const expected = crypto
  .createHmac('sha256', process.env.WEBHOOK_SECRET)
  .update(body)
  .digest('hex');

if (signature !== expected) {
  return res.status(401).end();
}

How it works

One API call, a full pipeline

You post a message — we handle classification, retrieval, generation, and routing. You get back a single response with everything you need to decide what happens next.

Visitor
Sends a message
Classify
Intent + confidence
Knowledge
Retrieve from your KB
Generate
Answer + suggested actions
Escalate (maybe)
Low confidence → human

Typical latency: ~450ms p50
Rate limit: 60 rpm per key · configurable
Retry-safe: Idempotent retries · webhook back-off

Ready when you are

Your first API call is 60 seconds away

Create an API key, copy the quick-start snippet, see a real response. Free tier includes enough calls to build and test.

Get API key Open dashboard

Ship an AI support agent in 5 minutes

Your first successful request

Create an API key

Send a message

Handle the response