docs · developer · api

API reference

reference

The shipped HTTP surface — chat, documents, config, webhooks. Stateful chat uses an API key plus a signed visitor credential.

VeriCite exposes a versioned HTTP API under `/api/v1/`. Every request authenticates with an `X-API-Key` header carrying a public (`pk_`) or secret (`sk_`) key minted on the API keys page. Stateful chat additionally uses a server-minted signed visitor credential. This reference documents only the surface that is actually shipped and served by the gateway — chat, documents, config, an improvements export, and webhook management.

What this covers

The endpoints below are the live, gateway-mounted routes. All paths are prefixed with `/api/v1`. Requests are scoped to the tenant that owns the API key — you never pass a tenant id.

Authentication

Send your key on every request. Before query, stream, feedback, or session-history calls, mint or refresh a signed anonymous identity with `POST /api/v1/chat/visitor-credential`. The gateway resolves the tenant from the key; there is no separate tenant parameter.

bashbash

curl -X POST https://api.vericite.ai/api/v1/chat/visitor-credential \  -H 'X-API-Key: pk_live_your_public_key'

X-API-Key (required)header

A pk_ public key or sk_ secret key. Missing or invalid keys return 401 (API key required. Provide X-API-Key header.). Mint and revoke keys on the API keys page.

X-VC-User-Id (protected chat)header

The visitorId returned by the visitor-credential endpoint. It must match the signed token.

X-VC-Visitor-Credential (protected chat)header

The signed visitorCredential returned by the visitor-credential endpoint. Present it alone to the issuance endpoint to refresh while preserving the visitor id.

Public key (`pk_`)prefix

Intended for browser/widget-side use; lower-trust surface.

Secret key (`sk_`)prefix

Server-side, full-trust. Keep out of client bundles.

Breaking chat authentication change — API-key-only requests to query, stream, feedback, and session-history endpoints are rejected. Acquire a credential before the protected call, refresh it through `/api/v1/chat/visitor-credential`, and stop on acquisition failure. There is no unsigned fallback.

bashbash

curl https://api.vericite.ai/api/v1/chat/query \  -H 'X-API-Key: pk_live_your_public_key' \  -H 'X-VC-User-Id: <visitorId>' \  -H 'X-VC-Visitor-Credential: <visitorCredential>' \  -H 'Content-Type: application/json' \  -d '{ "query": "What are the library hours?", "sessionId": "<uuid>" }'

Chat

post/api/v1/chat/query

post/api/v1/chat/stream

post/api/v1/chat/feedback

get/api/v1/chat/suggestions

get/api/v1/chat/sessions

get/api/v1/chat/sessions/:id

POST /chat/querychat

Ask a question; returns a single cited answer payload. Requires both signed visitor headers.

POST /chat/streamchat

Same signed visitor contract as query, but streams the answer as server-sent events.

POST /chat/feedbackchat

Record thumbs/feedback against a prior answer for the verified visitor.

GET /chat/suggestionschat

Suggested starter prompts for the tenant.

GET /chat/sessionschat

List conversation sessions owned by the verified visitor.

GET /chat/sessions/:idchat

Fetch a single session and its exchanges only when owned by the verified visitor.

Documents

post/api/v1/documents

get/api/v1/documents/:id

POST /documentsdocuments

Upload a source document (multipart file, optional title, category, tags). Triggers processing.

GET /documents/:iddocuments

Fetch one document, including its processing state.

GET /documentsdocuments

List documents; also /documents/summary, /documents/reprocess-estimate, and /documents/:id/pipeline for processing detail.

Terminal status is `ready` — A successfully processed document ends at status `ready` — there is no `completed` state. Poll `/documents/:id` (or `/documents/:id/pipeline`) for `ready` rather than waiting on a status string the API never emits. DOCX uploads are accepted at the gateway but rejected by the text-extraction pipeline (only PDF, plain text/Markdown, and images are extractable); convert to a supported format first.

Config

get/api/v1/config/ratelimits

get/api/v1/config/widget

get/api/v1/config/guardrails

GET /config/ratelimitsconfig

Effective per-minute rate limit for your tenant (plan tier plus any override).

GET /config/fallbackconfig

Fallback / escalation configuration.

GET /config/embeddingsconfig

Embedding configuration.

GET /config/widgetconfig

Widget configuration the embed loads.

GET /config/guardrailsconfig

Guardrail configuration. The PUT /config/guardrails save is superadmin-only — tenant keys can read but not write (403).

GET /config/:type/versionsconfig

Version history for a config block.

Improvements export

get/api/v1/improvements/export

`GET /improvements/export` returns the answer-improvement queue for offline review. The same router also serves `GET /improvements`, `GET /improvements/:id`, and `POST /improvements/:id/approve`.

Webhooks

get/api/v1/webhooks

post/api/v1/webhooks

del/api/v1/webhooks/:id

get/api/v1/webhooks/:id/deliveries

post/api/v1/webhooks/:id/trigger

post/api/v1/webhooks/:id/deliveries/:deliveryId/retry

GET /webhookswebhooks

List configured webhook endpoints.

POST /webhookswebhooks

PATCH /webhooks/:idwebhooks

Update a webhook (e.g. eventType, url, active).

DELETE /webhooks/:idwebhooks

Remove a webhook.

GET /webhooks/:id/deliverieswebhooks

List delivery attempts for a webhook.

POST /webhooks/:id/triggerwebhooks

Manually fire a delivery for the webhook.

POST /webhooks/:id/deliveries/:deliveryId/retrywebhooks

Re-attempt a specific past delivery.

Deliveries are HMAC-signed: VeriCite sends an `x-webhook-signature` header (computed from the webhook's secret over the payload) plus `x-webhook-event`, and an SSRF guard rejects internal/private hosts and non-HTTPS URLs at delivery time. Verify the signature on your receiver.

Webhooks do not auto-fan-out — There is no automatic event dispatch. Deliveries fire only when you call `POST /webhooks/:id/trigger` or retry a past delivery — registering a webhook does not subscribe it to a live event stream. Treat the event-name field as metadata: the names offered in the console UI, the schema's documented set, and the set actually emitted do not currently line up.

Rate limits

Limits are per tenant, per minute, by plan tier.

Starterplan

60 requests / minute.

Professionalplan

300 requests / minute.

Enterpriseplan

1000 requests / minute.

Tenant overridebehavior

A configured per-tenant override takes precedence over the plan-tier limit when set.

Exceeding the limitbehavior

Returns 429 with error code RATE_LIMIT_EXCEEDED.

Per-key rate_limit is ignored — The per-key `rate_limit` column has no effect — the gateway enforces only the tenant's plan-tier limit (or the tenant override). Do not rely on setting a limit on an individual key; it is never read at request time.

Not shipped — do not integrate against these

Phantom surface — Some marketing material references endpoints and tools that do not exist in the product. They are not served and will not work.

`/v1/answer` is not a real endpoint — use `POST /api/v1/chat/query`.
There are no official TypeScript, Python, Go, or Ruby SDKs. Call the HTTP API directly.
No Confluence, SharePoint, or Notion connectors ship — ingest sources via `POST /api/v1/documents`.

referenceWidget embedDrop the widget on any page with a script tag and a custom element.

featureAPI keysCreate and rotate the pk_ and sk_ keys used by the API and widget.

referenceRate limitsPer-plan request ceilings and the 429 response shape.

Was this page helpful?