API Overview
The Veritrellis REST API is the core authorization boundary. Every permit begins with a call here.
Base URL
https://api.veritrellis.ai
All endpoints are versioned under /v1. The current stable version is v1.
Authentication
The public API authenticates with API key bearer tokens. Include your key in every request:
Authorization: Bearer vt_sandbox_01HXXX...
API keys are scoped to a workspace and environment (sandbox or production). A sandbox key cannot authorize production-environment requests.
API keys carry full authorization for your workspace. Never expose them in a browser, mobile app, or client-side code.
Request format
Send JSON with Content-Type: application/json:
curl -sS https://api.veritrellis.ai/v1/authorize \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{ ... }'
Response format
All responses are JSON. Successful responses include a top-level decision field. Error responses include error and message:
{
"error": "unauthorized",
"message": "API key not found or expired"
}
HTTP status codes
| Code | Meaning |
|---|---|
200 | Request succeeded |
202 | Permit not yet issued — approval is pending |
400 | Bad request — check your payload schema |
401 | Missing or invalid API key |
403 | Key does not have access to this workspace/environment |
404 | Resource not found |
409 | Terminal conflict — permit will not be issued for this request |
422 | Validation error — payload failed schema checks |
429 | Rate limit exceeded |
500 | Internal server error |
API surfaces
The API is segmented into three surfaces, each with its own authentication boundary:
Public API
Audience: your backend, agents, connectors, and SDK integrations.
Authentication: API key bearer token.
| Route | Method | Purpose |
|---|---|---|
/v1/authorize | POST | Submit an action for authorization |
/v1/permits/:requestId | GET | Fetch permit after approval |
/v1/workspaces/:workspaceId/.well-known/jwks.json | GET | Retrieve workspace public keys for permit verification |
/v1/connectors/:installationId/invoke | POST | Invoke from a connector integration (HubSpot, Intercom, Zendesk) |
/v1/gateway/execute | POST | Feature-gated execution boundary |
/public/requests/:requestId/summary | GET | Unauthenticated summary for UI extensions |
Admin API
Audience: the Veritrellis admin app.
Authentication: session token (WorkOS AuthKit).
Routes under /admin/* cover workspace management, member access, policies, requests, approvals, approver groups, API keys, audit, connectors, and billing.
Internal API
Audience: ops tooling only.
Authentication: INTERNAL_SERVICE_TOKEN in the Authorization header.
Routes under /internal/* cover customer operations, entitlement overrides, billing sync, and internal reporting. Not for external use.
Endpoint detail pages
- Public endpoints — complete request/response details for
/v1routes - Admin endpoints — admin session-authenticated routes
- Internal endpoints — ops-only routes
OpenAPI reference
A machine-readable OpenAPI spec and generated endpoint inventory are available: