API Design

Overview

This document defines the API contract for Vora - authentication requirements and error handling that developers should reference when building integrations.

The Vora API is a REST API that returns JSON. All requests are made over HTTPS.

Content Type

All responses return:

Content-Type: application/json

Request bodies, where applicable should also be sent as JSON with the following header

Content-Type: application/json

Rate Limiting

Rate limits are enforced per API key to protect infrastructure stability and ensure consistent performance across all integrations.

info

Tier-based rate limits are placeholders pending customer validation. A global rate limit applies to all customers until tiers are finalized. Final limits will be defined in a separate Pricing & Tiers document (not yet published).

Current Global Limit

Window	Limit
Per minute	TBD
Per day	TBD

Planned Tier Limits

Tier	Per Minute	Per Day
Starter	TBD	TBD
Pro	TBD	TBD
Enterprise	Custom	Custom

Response Headers

Every API response includes the following headers so your integration can monitor usage

Header	Description
X-RateLimit-Limit	Your total allowed request for the current window
X-RateLimit-Remaining	Requests remaining in the current window
X-RateLimit-Reset	Unix timestamp when the current window resets

When the Limit is Exceeded

If you exceed your rate limit, the API returns the below response

429 Too Many Requests

Pause requests until the time indicated in the below header before retrying

X-RateLimit-Reset

Error Codes

All errors follow a consistent response shape regardless of the endpoint or error type

Error Response Schema

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "You have exceeded your rate limit. Please retry after 1714480800.",
    "details": {}
  }
}

Field	Type	Description
code	string	Machine-readable error code
message	string	Human-readable description of the error
details	object	Additional context where applicable, otherwise empty

HTTP Status Codes

Status	Code	Description
400	bad_request	Missing or invalid query parameters
401	unauthorized	API key is missing or invalid
403	forbidden	API key does not have access to this resource
404	not_found	The requested record does not exist
429	rate_limit_exceeded	Rate limit reached for current window
500	internal_server_error	Something went wrong on Vora's end

Pagination

All list endpoints return paginated results. Vora uses offset-based pagination.

Request Parameters

Parameter	Type	Required	Default	Description
limit	integer	No	20	Number of records to return. Maximum 100.
offset	integer	No	0	Number of records to skip before returning results

Example Request

GET /v1/enforcement?limit=20&offset=40
Authorization: Bearer vora_live_xxxxxxxxxxxx

Response Envelope

{
  "data": [],
  "pagination": {
    "total": 843,
    "limit": 20,
    "offset": 40,
    "has_more": true
  }
}

Field	Type	Description
data	array	The list of records for the current page
total	integer	Total number of matching records
limit	integer	The limit applied to this request
offset	integer	The offset applied to this request
has_more	boolean	Whether additional records exist beyond this page

Filtering & Sorting

Parameters listed here apply globally - individual endpoint definitions in the Vora Swagger documentation note which filters are available per endpoint.

Date Range Filtering

Parameter	Type	Description
date_from	ISO 8601 date	Return records on or after this date
date_to	ISO 8601 date	Return records on or before this date

Example

GET /v1/enforcement?date_from=2024-01-01&date_to=2024-12-31

Keyword Search

Parameter	Type	Description
query	string	Search by entity name. Partial matches supported

Example

GET /v1/enforcement?query=acme+bank

Enum Filtering

Enum filters accept a single value or a comma-separated list of values

Example

GET /v1/enforcement?source=cfpb,occ

Sorting

Parameter	Type	Default	Description
sort_by	string	action_date	Field to sort by
sort_order	enum	desc	Sort direction. Accepts asc or desc

Example

GET /v1/enforcement?sort_by=action_date&sort_order=asc

Combining Filters

All filters can be combined in a single request

Example

GET /v1/enforcement?query=acme+bank&source=cfpb,occ&date_from=2024-01-01&sort_order=asc

Versioning

The API version is included in the base URL. This ensures breaking changes never affect existing integrations without notice

Breaking vs Non-Breaking Changes

Non-breaking changes may be added to any version at any time without notice. These include:

• New optional query parameters
• New fields added to existing response schemas
• New endpoints
• New enum values

Breaking changes will always be released as a new version with a deprecation notice and migration guide before the previous version is sunset. These include:

• Removed or renamed fields
• Changed response shapes
• Modified authentication behavior
• Removed endpoints

V1 - Current

Status	ACTIVE
Released	2026
Base URL	https://api.withvora.com/v1

What's Included in V1

• Enforcement action search and lookup (/v1/enforcement, /v1/enforcement/:id)
• License record search and lookup (/v1/licenses, /v1/licenses/:id)
• Data source listing (/v1/sources)
• Health check (/v1/health)
• API key authentication

Authentication

Vora uses API key authentication. Every request must include a valid API key passed as a Bearer token in the Authorization header

API Key Format

vora_live_xxxxxxxxxxxxxxxxxxxx

Keys prefixed with vora_live_ are production keys. When we introduce a sandbox environment, test keys will use the vora_test_ prefix.

Passing Your API Key

GET /v1/enforcement
Authorization: Bearer vora_live_xxxxxxxxxxxxxxxxxxxx

Key Management

API Keys are generated and managed from the Vora dashboard. You can create, rotate, and revoke keys at any time. Rotating a key immediately invalidates the previous one.

Security

• Never expose your API key in client-side code or public repositories
• Rotate your key immediately if you believe it has been compromised
• Each key is tied to your account and all usage is logged against it.

Authentication Errors

Status	Code	Description
401	unauthorized	API Key is missing or invalid
403	forbidden	API Key is valid but does not have access to this resource

info

For full endpoint definitions, request and response schemas, and interactive examples see Vora Swagger documentation.