Skip to main content
Every VisIQ REST endpoint shares the same conventions for errors, versioning, and pagination. This page is the single reference the per-facet API references point back to. The base URL for all of them is https://api.visiqlabs.com.

​
Validation errors

A request that fails schema validation returns 400 Bad Request with a machine-readable body. The error field is always a short string; a details field carries the underlying diagnostics.
The error string names what failed to parse:
The details payload has one of three concrete shapes depending on the endpoint — all are derived from the same underlying validator, so all pinpoint the offending field(s):
  • Flattened (the unified POST /evaluate and the /orchestrate/* endpoints): { "formErrors": [...], "fieldErrors": { "field": ["message"] } }.
  • Raw issues (the unified /rules CRUD): an array of issue objects, each { "code": "...", "path": ["field"], "message": "..." }.
  • Mapped (the /record/* endpoints): an array of { "field": "path.to.field", "message": "..." }.
Path-parameter errors (Invalid rule ID, etc.) and Invalid JSON body carry no details.
Every write endpoint validates its entire body before touching the database (input is validated with a strict schema first), so a 400 means nothing was persisted.

​
Versioned vs unversioned paths

Two path conventions coexist, and which one an endpoint uses is deliberate.

/v1/* — the versioned read API

Cross-cutting and query endpoints live under a /v1 prefix: the decision audit-log reads (/v1/allow/audit-log, /v1/recall/audit-log, /v1/record/audit-log), decision polling (/v1/allow/decisions/:id), and resources like credentials, events, and notifications. The prefix marks the stable, URL-versioned public surface.

Unversioned — the governance planes

The governance surfaces are mounted at the root without a version segment: /allow/*, /recall/*, /orchestrate/*, /rules/*, /evaluate, and /record/*. They are kept unversioned for product isolation, and their evolution is governed by the SDK wire contract below, not by a URL version.
Practically: a versioned read endpoint keeps its /v1 path stable and adds fields additively; a governance-plane endpoint evolves under the bundle-dialect contract. The OEM Partner API is a third, separate surface with its own dated version header and a 12-month deprecation window — see Versioning & deprecation.

​
List pagination

List endpoints accept page (default 1) and limit query parameters and return a paginated envelope. The default and maximum limit, and the name of the page-size field in the response, vary by surface: Both fields hold the same value — the effective page size — under a different key. total is an accurate server-side count over the (vendor-scoped) query.

​
Authentication & rate limits

All endpoints authenticate with a Bearer credential and are rate-limited per key (default 600 requests / 60 seconds). Credentials come in two audiences — operational harness keys confined to the SDK routes, and management keys governed by permission grants. The full model, error codes, and the permission ↔ endpoint matrix live in Managing API Keys.

​
Stability policy

The platform is pre-1.0 — there is no frozen wire-compatibility guarantee yet, and the SDK surface may change across a minor release until v1.0 GA. Two properties hold regardless of version, because a governance product cannot be casual about them:
1

Additive-only, readers ship first

The control plane never emits a bundle construct — a new outcome verb, field, or operation facet — that the reading SDK cannot already enforce. The SDK that understands a construct is published before the plane emits it. Write your clients as tolerant readers: ignore response fields you don’t recognize rather than failing on them.
2

Fail closed on the unrecognized

An SDK treats any construct it does not recognize as must-understand and resolves it to the fail-closed outcome for a confirmed-enforcing agent — never fail open. A version skew can degrade coverage but never safety.
For the full posture — the pre-1.0 stance, the invariants, and the compatibility window that takes effect at v1.0 — see SDK versioning & compatibility. For the separately-versioned partner surface, see OEM Partner API versioning.