Folio API Documentation

Folio provides structured API access to US intellectual property data. Query USPTO trademarks, patent and trademark assignments, and TTAB proceedings from a single, consistent REST API.

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 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	50
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 (present on trademark, TTAB, and assignment endpoints) indicates the date of the most recent USPTO bulk data ingestion.

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.

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.
• Health — service liveness (no authentication required).

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