Overview
The typesearch HTTP API, version 1: base URL, authentication, errors and versioning.
Base URL
https://api.typesearch.aiEvery endpoint lives under /v1. Requests and responses are JSON (Content-Type: application/json);
field names are snake_case.
Authentication
Send your key as Authorization: Bearer ts_live_… or x-api-key: ts_live_…. See
Authentication.
Client identification
Optionally, tell us which library or integration makes the request with
X-Typesearch-Client: <name>/<version> (for example my-agent/1.2.0). The official SDKs and integrations
send it for you. It is only used for aggregate usage statistics: it never affects authentication, billing or
rate limits.
Endpoints
| Endpoint | ||
|---|---|---|
| POST | /v1/search | Search the index. |
| POST | /v1/search/site | Search a live site. Returns a job. |
| GET | /v1/jobs/{id} | A job’s status and result. |
| POST | /v1/similar | Articles about the same story as a URL. |
| POST | /v1/contents | Metadata and excerpts of up to 10 URLs. |
| POST | /v1/charts | Create a chart card. |
| GET | /v1/charts | List your charts. |
| GET | /v1/charts/{id} | Get a chart. |
| PATCH | /v1/charts/{id} | Change its type, theme, title or language. Free. |
| DELETE | /v1/charts/{id} | Delete a chart. |
| GET | /embed/{file} | A chart’s public embed, PNG or SVG. No key. |
| GET | /v1/usage | Usage and limits of your key. |
Errors
Errors are RFC 9457 problem details with a stable code. See
Errors for every code, and Rate limits for the limit headers.
Versioning
/v1 only changes by adding: new response fields, and new options with a default. Anything breaking will
ship as /v2, with notice. Ignore fields you don’t know, and don’t send fields that aren’t documented —
unknown request fields are rejected.
OpenAPI
The whole contract is an OpenAPI 3.1 document, generated from the same schemas that validate every request. Use it to generate a client in any language, or to import the API into your tools.