Overview

The VelociFile API gives your systems programmatic access to insurance regulatory filings: search the catalog, read every version VelociFile has served for a filing, download hash-verified source PDFs, and subscribe to changes with signed webhooks. The same operations are available to AI agents over MCP.

The API follows the VelociFile filing contract, version 1.0.0.

What you can do

Task	Operation	Page
List states, product lines, filing types, statuses and carriers	GET /taxonomies	Filings and versions
Search filings by state, product line, carrier, filing type, status and effective date	POST /filings/search	Quickstart
Read a filing and its version history	GET /filings/{filing_id}, GET /filings/{filing_id}/versions	Filings and versions
Get a manifest of a version’s documents with SHA-256 hashes	GET .../manifest	Manifests and integrity
Download a source PDF through a short-lived URL	GET .../documents/{document_id}/download	Manifests and integrity
Watch a filing or a search for changes	POST /watchers	Watchers
Receive signed change events, or replay them	webhooks, GET /watchers/{watcher_id}/events	Webhooks
Use all of the above from an agent	POST /mcp	MCP

Base URLs

Environment	Base URL	Key prefix
Production	https://api.velocifile.ai/v1	vf_live_
Sandbox	https://api.dev.velocifile.ai/v1	vf_test_

Sandbox and production are separate systems with separate keys. Build against sandbox first. See Environments.

Conventions

• JSON in and out, UTF-8. Dates are YYYY-MM-DD. Timestamps are UTC with a trailing Z.
• IDs are strings that match ^[A-Za-z0-9][A-Za-z0-9._-]*$ and are at most 128 characters long.
• Every response carries an X-Request-Id header. Quote it when you contact support.
• Requests and responses reject unknown fields. Send exactly the documented properties.
• Every failure uses one error envelope.

Where to start

1. Get a sandbox key from VelociFile. Keys are issued by VelociFile staff, never self-served.
2. Run your first search.
3. Read Pagination and Filings and versions before you build a sync, because search is a live view and not a frozen snapshot.
4. Read the contract deviations. Five behaviors differ from the original packet.

The full operation list, with request and response schemas and a try-it console, is in the API reference. The raw contract is published at /openapi.json.