Folio API Documentation

Folio provides structured API and MCP access to hard-to-use U.S. public-record datasets: USPTO trademarks, patent and trademark assignment archives, TTAB proceedings, and FDA NDC drugs.

All responses are JSON. Endpoints follow REST conventions with predictable pagination, error handling, and rate limiting.

This page covers the cross-cutting concerns — authentication, rate limits, pagination, errors. For the full endpoint-by-endpoint reference with request/response schemas and a try-it console, see the API reference. The raw OpenAPI 3.0.3 spec is at /openapi.yaml.

Authentication

All endpoints except /v1/health require an X-API-Key header. You can get a free API key from the pricing section of the homepage.

curl -H "X-API-Key: fo_live_abc123" \
  "https://folioapi.com/v1/health"

Requests without a valid key receive a 401 Unauthorized response.

Rate Limits

Rate limits are applied per API key. Exceeding your tier's limits returns 429 Too Many Requests with a Retry-After header.

Tier	Requests/sec	Daily Limit
Free	1	250
Pro ($49/mo)	5	5,000
Business ($199/mo)	20	50,000
Enterprise	Custom	Custom

Response Format

Paginated Responses

List endpoints return results in an envelope with pagination metadata:

{
  "results": [...],
  "total": 142,
  "limit": 50,
  "offset": 0,
  "data_freshness": "2026-04-10"
}

The data_freshness field, where present, is endpoint-specific: trademark and TTAB surfaces report USPTO trademark bulk-corpus currency, assignment endpoints report the latest assignment record date, and FDA NDC endpoints report the latest successful NDC ingest. Assignment and drug endpoints may also include a coverage_note describing source coverage.

Errors

Errors return an appropriate HTTP status code with a JSON body:

{
  "error": "at least one of owner_name, mark_name, or serial_number is required"
}

Common status codes: 400 (bad request), 401 (missing or invalid API key), 403 (tier restriction), 404 (not found), 429 (rate limit exceeded), 502 (upstream failure).

Guides

Task-oriented walkthroughs for common use cases, with working code samples:

• How to search USPTO trademarks programmatically — owner, mark-text, class, and date-range filters.
• A TSDR alternative: trademark status and prosecution history — per-serial records and event feeds as JSON.
• Retrieving patent assignment history via API — assignment chains by patent, application, or party.
• Querying FDA NDC drugs via API — search the current FDA NDC snapshot by drug name, ingredient, labeler, NDC, or RxCUI, including current excluded records.
• Folio MCP server — connect Claude Code, Cursor, or another remote Streamable-HTTP MCP client with custom-header support to Folio's remote tools.
• Folio for AI research agents — use Folio as a structured data layer for diligence and monitoring workflows.

Endpoint Reference

The full endpoint-by-endpoint reference — request parameters, response schemas, example payloads, and a try-it console — is rendered from our OpenAPI specification at /reference. It covers all available endpoints:

• Trademarks — search, detail, prosecution history.
• Historical Assignments — trademark and patent assignment records.
• TTAB — Trademark Trial and Appeal Board proceedings.
• Drugs — FDA NDC Directory: search, detail, packages, applications, and labelers.
• Health — service liveness (no authentication required).

Need the raw machine-readable spec for SDK generation or request validation? It's at /openapi.yaml.