VerexaDocs
Dashboard

API reference

The HTTP API behind every SDK: base URL, authentication, conventions and errors.

Every Verexa SDK is a thin client over the same HTTP API. This page covers what every request has in common: where it goes, how it is authenticated and how the service answers. Each endpoint is documented on its own page.

  • One host, one version. Every endpoint lives under https://api.verexa.dev, with the version in the path
  • A key scopes the request. A key belongs to one project and one environment, and nothing in a request body can widen that
  • JSON in, JSON out. Bodies and responses are JSON, and errors are a single line of plain text
  • One verdict shape. Every check, over HTTP or through an SDK, answers with the same fields

Base URL

All endpoints are served from https://api.verexa.dev over HTTPS. The host is the same for every project and environment: there is no per-environment URL, and the key decides which project and environment a request acts on.

Authentication

Every endpoint except the health probes requires an API key as a Bearer token in the Authorization header:

An authenticated request
curl "https://api.verexa.dev/v1/events?limit=1" \  -H "Authorization: Bearer $VEREXA_API_KEY"
  • One key, one scope. A key belongs to one project and one environment, and every request is scoped by it: a check, an event read or a policy publish can only touch that project and environment
  • Live keys and test keys. Keys minted for prod start with vx_live_; keys minted for dev start with vx_test_
  • Managed in the dashboard. Create and revoke keys under Settings → API keys in the dashboard
The plaintext is shown once
The dashboard displays a new key exactly once, at creation. The service stores only a hash, so a lost key cannot be recovered - revoke it and create another.

Endpoints

Three endpoints make up the customer-facing API:

EndpointWhat it doesReference
POST /v1/checkRun the detectors on one piece of text and get a verdictCheck
GET /v1/eventsRead the checks recorded for your project and environmentEvents
GET, PUT /v1/policyRead and publish the detector overrides in force for each profilePolicy

Two unauthenticated probes sit alongside them: GET /v1/health reports which optional layers (classifier, judge, cache) are configured, and GET /healthz is a liveness probe with an empty body.

Request and response conventions

  • JSON bodies and responses. Send a JSON body with Content-Type: application/json on POST and PUT, and expect application/json back. Field names are camelCase, and enum values are lowercase (input, output, allow, flag, redact, block)
  • Timestamps are RFC 3339, in UTC, for example 2026-08-18T10:00:00Z. The since and until filters on event reads take the same format
  • Trace ids come from you. Every check carries a caller-supplied traceId; send any string and the service records it as-is, grouping the checks of one turn. See Events and traces
  • One verdict shape. Every check, over HTTP or through an SDK, answers with the same fields. Core concepts walks through them

Errors

There is no JSON error envelope. A failed request answers with a status code and a one-line plain-text body:

StatusBodyWhen
400invalid request body, phase must be input or output, cursor must be a positive integer, unknown profileThe JSON is malformed or a field is missing or invalid; the message names the problem
401unauthorizedThe key is missing, invalid or revoked
405method not allowedThe path does not accept that method
500internal errorThe check failed unexpectedly; the SDK's fail mode decides what the caller gets
503identity store unavailable, event store unavailable, policy store not configured, could not persist policyA dependency needed to answer the request is unreachable
A 503 is not a rejection
A 401 is a decision: the key was checked and rejected. A 503 means the key could not be checked at all, and a key verified in the last 24 hours keeps working while the identity store is unreachable.

When a check cannot be answered and you call through an SDK, the SDK does not raise: it returns a fallback verdict with degraded: true, with the action set by its fail mode (allow by default, block when fail closed). See Core concepts.

Versioning

The version is in the path. Every customer endpoint is served under /v1, and there is no version header to send. /healthz sits outside the prefix as the liveness probe that deployment checks call.

Limits

  • No rate limit. The service does not rate limit requests today
  • Checks run on their profile's budget. A check that outruns its budget answers with degraded: true and lists the skipped detectors in degradedDetectors, instead of failing. See Core concepts
  • Event pages hold up to 2000. A page returns the newest events, 100 by default and 2000 at most, and carries a nextCursor while more remain. See the Events API
  • A request has 30 seconds. The service reads a request and writes its response within 30 seconds. The SDKs give up earlier: 2 seconds per check by default

Next steps