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.
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 |
For full endpoint definitions, request and response schemas, and interactive examples see Vora Swagger documentation.