Docs → API quickstart
API quickstart
End to end: read your open conversations, create one, send a message, register a webhook, verify its signature and handle a retry. Each sample below is run, as written, against the real API handlers (and the real webhook delivery engine) in our test suite, so what you copy is what works.
1. Get a key
In the dashboard open Settings → API keys, create a key with the conversations:read, conversations:write and webhooks:write scopes (the last one is for registering a webhook in step 2; add webhooks:read to look at deliveries later), and export it. The key is shown once. A call outside the key’s scopes answers 403 insufficient_scope and names the scope it needs.
export VELOR_API_KEY=velor_live_...2. curl
Read
curl "https://app.velorplatforms.com/api/v1/conversations?status=open&limit=5" \
-H "Authorization: Bearer $VELOR_API_KEY"Write
curl -X POST "https://app.velorplatforms.com/api/v1/conversations" \
-H "Authorization: Bearer $VELOR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: quickstart-0001" \
-d '{"visitor_email":"ada@example.com","initial_message":"Hi, I need help with my order."}'The create answers 201 with the conversation under data. Send the same Idempotency-Key again and you get the original response back, marked Idempotent-Replay: true, instead of a second conversation.
Send a message
Put the conversation id from the create response in CONVERSATION_ID. The message is added as agent and answers 201 with the message under data.
curl -X POST "https://app.velorplatforms.com/api/v1/conversations/$CONVERSATION_ID/messages" \
-H "Authorization: Bearer $VELOR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: quickstart-msg-0001" \
-d '{"role":"agent","content":"Thanks for reaching out. Your order shipped today."}'Register a webhook endpoint
The URL must be HTTPS and public. The response includes the signing secret (whsec_…) once; store it as VELOR_WEBHOOK_SECRET. With the same Idempotency-Key, a retry returns the same secret instead of registering a second endpoint.
curl -X POST "https://app.velorplatforms.com/api/v1/webhooks" \
-H "Authorization: Bearer $VELOR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: quickstart-hook-0001" \
-d '{"url":"https://example.com/webhooks/velor","events":["conversation.created","message.created","conversation.resolved"],"description":"Quickstart"}'3. TypeScript
Install @velorplatforms/sdk (it is in the repository and not on npm yet; the curl and Python samples need no package). The client retries 5xx responses on its own backoff; on any error it exposes the server’s Retry-After as err.retryAfterMs, so you decide how long to wait after a 429.
import { VelorClient } from "@velorplatforms/sdk";
const velor = new VelorClient({ apiKey: process.env.VELOR_API_KEY });
// 1. Read: your open conversations.
const open = await velor.conversations.list({ status: "open", limit: 5 });
console.log("open conversations:", open.data.length);
// 2. Write: start a conversation. The key makes a retry replay, not duplicate.
const created = await velor.conversations.create(
{ visitor_email: "ada@example.com", initial_message: "Hi, I need help with my order." },
{ idempotencyKey: "quickstart-0001" },
);
console.log("created:", created.data.id);
// 3. Send a message into it as an agent.
const outbox = velor.conversations.messages;
const sent = await outbox.create(created.data.id, {
role: "agent",
content: "Thanks for reaching out. Your order shipped today.",
});
console.log("message:", sent.data.id);
// 4. Register a webhook endpoint. The signing secret is returned ONCE, here.
const hook = await velor.webhooks.create(
{
url: "https://example.com/webhooks/velor",
events: ["conversation.created", "message.created", "conversation.resolved"],
},
{ idempotencyKey: "quickstart-hook-0001" },
);
console.log("webhook:", hook.id, hook.secret.slice(0, 6));4. Python
Standard library only; no packages to install.
import json, os, urllib.request
BASE = "https://app.velorplatforms.com"
KEY = os.environ["VELOR_API_KEY"]
def call(method, path, body=None, headers=None):
req = urllib.request.Request(
BASE + path,
method=method,
data=json.dumps(body).encode() if body is not None else None,
headers={"Authorization": "Bearer " + KEY, "Content-Type": "application/json", **(headers or {})},
)
with urllib.request.urlopen(req) as res:
return json.load(res)
# 1. Read: your open conversations.
open_ = call("GET", "/api/v1/conversations?status=open&limit=5")
print("open conversations:", len(open_["data"]))
# 2. Write: start a conversation. The key makes a retry replay, not duplicate.
created = call(
"POST",
"/api/v1/conversations",
{"visitor_email": "ada@example.com", "initial_message": "Hi, I need help with my order."},
{"Idempotency-Key": "quickstart-0001"},
)
print("created:", created["data"]["id"])
# 3. Send a message into it as an agent.
sent = call(
"POST",
"/api/v1/conversations/" + created["data"]["id"] + "/messages",
{"role": "agent", "content": "Thanks for reaching out. Your order shipped today."},
)
print("message:", sent["data"]["id"])
# 4. Register a webhook endpoint. The signing secret is returned ONCE, here.
hook = call(
"POST",
"/api/v1/webhooks",
{"url": "https://example.com/webhooks/velor",
"events": ["conversation.created", "message.created", "conversation.resolved"]},
{"Idempotency-Key": "quickstart-hook-0001"},
)
print("webhook:", hook["id"], hook["secret"][:6])5. Receive and verify
Every delivery is signed: x-velor-signature is sha256= and the HMAC-SHA256 of timestamp.rawBody, with the timestamp in x-velor-timestamp. Verify the raw body, reject anything older than five minutes, and answer 2xx quickly. Velor times out after 10 seconds.
Node (with the SDK)
import { createServer } from "node:http";
import { verifyEventWebhook } from "@velorplatforms/sdk";
const secret = process.env.VELOR_WEBHOOK_SECRET; // the whsec_... returned when you created the endpoint
const seen = new Set(); // use a table with a unique key on event.id in production
createServer(async (req, res) => {
// Verify the RAW body: parsing and re-serialising it changes the bytes.
const chunks = [];
for await (const chunk of req) chunks.push(chunk);
const rawBody = Buffer.concat(chunks).toString("utf8");
const result = await verifyEventWebhook(rawBody, req.headers, secret);
if (!result.valid) {
res.writeHead(401).end(result.reason);
return;
}
// A retry re-sends the same event with the same id. Handle each id once and
// still answer 2xx, or Velor keeps retrying.
const event = JSON.parse(rawBody);
if (seen.has(event.id)) {
console.log("duplicate:", event.id);
res.writeHead(200).end("duplicate");
return;
}
seen.add(event.id);
console.log("handling:", event.type, event.id);
res.writeHead(200).end("ok");
}).listen(3000);Python (standard library)
import hashlib
import hmac
import time
def verify_velor_webhook(raw_body: str, timestamp: str, signature: str,
secret: str, prev_signature: str | None = None) -> bool:
"""raw_body: the request body exactly as received, before any JSON parsing.
timestamp: x-velor-timestamp (Unix seconds). signature: x-velor-signature.
prev_signature: x-velor-prev-signature, present for 24 hours after a rotation."""
if not secret:
return False
try:
skew = time.time() - float(timestamp)
except ValueError:
return False
if skew > 300 or skew < -60: # replay window / clock drift
return False
expected = hmac.new(secret.encode(), f"{timestamp}.{raw_body}".encode(),
hashlib.sha256).hexdigest()
for candidate in (signature, prev_signature):
if not candidate:
continue
received = candidate[7:] if candidate.startswith("sha256=") else candidate
if hmac.compare_digest(received, expected):
return True
return False
import json
import os
from http.server import BaseHTTPRequestHandler, HTTPServer
SECRET = os.environ["VELOR_WEBHOOK_SECRET"] # the whsec_... returned when you created the endpoint
seen = set() # use a table with a unique key on event["id"] in production
class Handler(BaseHTTPRequestHandler):
def do_POST(self):
# Verify the RAW body: parsing and re-serialising it changes the bytes.
raw = self.rfile.read(int(self.headers.get("Content-Length", 0))).decode("utf-8")
if not verify_velor_webhook(
raw,
self.headers.get("x-velor-timestamp", ""),
self.headers.get("x-velor-signature", ""),
SECRET,
self.headers.get("x-velor-prev-signature"),
):
self.send_response(401)
self.end_headers()
return
# A retry re-sends the same event with the same id. Handle each id once
# and still answer 2xx, or Velor keeps retrying.
event = json.loads(raw)
if event["id"] in seen:
print("duplicate:", event["id"], flush=True)
else:
seen.add(event["id"])
print("handling:", event["type"], event["id"], flush=True)
self.send_response(200)
self.end_headers()
self.wfile.write(b"ok")
def log_message(self, *args): # keep stdout for your own logging
pass
HTTPServer(("", int(os.environ.get("PORT", "3000"))), Handler).serve_forever()
6. Handle a retry
A delivery that fails (non-2xx, a timeout, a network error) is tried three times, about 5 and 30 seconds apart, with the same event id and Idempotency-Key each time, and x-velor-attempt counting up. The receivers above handle each id once and still answer 2xx for a repeat. A delivery that exhausts its attempts is listed by GET /api/v1/webhooks/deliveries?status=failed and can be re-sent with POST /api/v1/webhooks/deliveries/:id/retry; it keeps its original id, so the same check absorbs it. See Webhooks for the full event list.
Pagination
List endpoints take limit and cursor. Each answer carries a next_cursor: pass it back as cursor to get the next page, and stop when it is null. The cursor is opaque; do not build one (a malformed one answers 400 invalid_cursor). A limit above the largest value is lowered to it, and a missing or non-numeric one uses the default. There is no offset or page number. Where next_cursor sits differs by endpoint, so check the table:
| Endpoint | Results under | next_cursor at | Default limit | Largest limit |
|---|---|---|---|---|
| /api/v1/conversations | data | pagination.next_cursor | 25 | 100 |
| /api/v1/conversations/{id}/events | data | next_cursor | 50 | 200 |
| /api/v1/contacts | contacts | next_cursor | 25 | 100 |
| /api/v1/knowledge | sources | next_cursor | 25 | 100 |
| /api/v1/calls | calls | next_cursor | 20 | 100 |
| /api/v1/evals/datasets | datasets | next_cursor | 50 | 100 |
| /api/v1/evals/runs | runs | next_cursor | 20 | 100 |
| /api/v1/webhooks/deliveries | data | next_cursor | 25 | 100 |
Reading every page with the SDK:
import { VelorClient } from "@velorplatforms/sdk";
const velor = new VelorClient({ apiKey: process.env.VELOR_API_KEY });
let cursor;
let total = 0;
do {
const page = await velor.contacts.list({ limit: 100, cursor });
total += page.contacts.length;
cursor = page.next_cursor ?? undefined; // null on the last page
} while (cursor);
console.log("contacts:", total);Next
- Errors, rate limits and idempotency
- Receive events with signed webhooks
- The full reference is the OpenAPI document at
/api/v1/openapi.json; a Postman collection is at/velor-api.postman_collection.json.