Reference

API reference

One base URL, one header, JSON in and out. The interactive Swagger UI shows every request and response schema and lets you try calls with your own key, and the raw OpenAPI schema can generate a client in any language.

Basics

Base URL: https://api.hayfork.dev
Authentication: Authorization: Bearer <key> on every request except GET /health. See API keys and scopes.
Content type: application/json, except file upload which is a form upload (multipart/form-data).
Request ids: every response carries an x-request-id header. Quote it when you write to us about a request.
Ids: collections, sources, documents, chunks, crawl jobs and keys are identified by strings. Store them as they are. Resources in other workspaces return 404.

Endpoints

The scope column is the minimum scope the key must hold.

Identity and system

Method and path	Scope	Purpose
`GET /health`	none	Dependency health. Returns 200 when the API, database, queue and index are up.
`GET /me`	search	Workspace, scopes, plan and this month's usage for the calling key or session.
`GET /capabilities`	search	What this deployment allows: connectors, whether the crawler may render JavaScript, the page size limit.
`GET /embedding-profile`	search	The embedding model, dimension, chunk size and index the deployment uses.
`GET /openai-tools.json`	search	Function-calling tool definitions. See Search for agents.

Search

Method and path	Scope	Purpose
`POST /search`	search	Search a collection with full-text and vector ranking combined. Body: `collection_id`, `query` (1 to 2,000 characters), `top_k` (1 to 50, default 10), `collapse_documents` (default true, one hit per document).
`POST /retrieve`	search	Full passages for LLM prompts, grouped by document with citation numbers and a token estimate. Body documented in Search for agents.

Collections

Method and path	Scope	Purpose
`GET /collections`	search	List collections with their document and source counts.
`POST /collections`	ingest	Create. Body: `name`, optional `description`, `data_source_ids`.
`GET /collections/ID`	search	Read one.
`PATCH /collections/ID`	ingest	Rename, describe, or change included sources.
`DELETE /collections/ID`	ingest	Remove the collection. Sources and documents are kept.
`PUT /collections/ID/data-sources/SOURCE_ID`	ingest	Attach a source.
`DELETE /collections/ID/data-sources/SOURCE_ID`	ingest	Detach a source. Its documents stay indexed for other collections.

Data sources and documents

Method and path	Scope	Purpose
`GET /data-sources`	search	List sources. Filter with `?collection_id=`.
`POST /data-sources`	ingest	Create. Body: `name`, `source_type` (`upload` or `website`), optional `configuration`, `collection_ids`.
`GET /data-sources/ID`	search	Read one, with document and indexed counts and the saved sync settings.
`DELETE /data-sources/ID`	ingest	Remove the source and every document in it.
`POST /data-sources/ID/reindex`	ingest	Re-embed stored content with the current embedding model. `POST /reindex` does the whole workspace.
`GET /documents`	search	The 200 most recent documents. Filter with `?data_source_id=` or `?collection_id=`.
`POST /documents/upload`	ingest	Multipart upload: `data_source_id` and one or more `files`. See File uploads.
`GET /documents/ID`	search	Document metadata and status.
`GET /documents/ID/chunks`	search	The indexed chunks of a document, in order. `?limit=` caps the count.
`DELETE /documents/ID`	ingest	Remove a document, its file and its index entries.

Crawling

Method and path	Scope	Purpose
`POST /crawl/check`	ingest	Inspect a URL without indexing: policy, reachability, robots.txt, sitemap size, llms.txt, JavaScript-only pages.
`POST /crawl`	ingest	Start a crawl. Body documented in Website sources. Returns `202` with the job.
`GET /crawl`	search	List crawl jobs.
`GET /crawl/ID`	search	Job status, pages crawled, limit and error.
`POST /crawl/ID/cancel`	ingest	Stop a running crawl. Pages already indexed stay.
`POST /crawl/ID/retry`	ingest	Resume an interrupted or failed crawl with its remaining page budget.

Benchmarks

A benchmark suite is a set of questions for a collection, each with the documents that should come back. Running it scores retrieval so you can see whether a new source or setting made results better or worse.

Method and path	Scope	Purpose
`POST /benchmarks`	ingest	Create a suite. Body: `name`, `collection_id`, `top_k`, and 1 to 500 `cases`. Case shape in Swagger.
`GET /benchmarks`	search	List suites with their latest scores.
`GET /benchmarks/ID`	search	One suite with its cases and runs.
`POST /benchmarks/ID/run`	ingest	Run every case against the collection now.
`DELETE /benchmarks/ID`	ingest	Remove a suite.
`GET /industry-benchmarks`	search	Ready-made public question sets you can copy into a suite.

API keys

Method and path	Scope	Purpose
`GET /api-keys`	admin	List keys: id, name, scopes, expiry, last use. Never the secret.
`POST /api-keys`	admin	Create. Body: `name`, `scopes`, optional `expires_in_days`. The secret is returned once.
`DELETE /api-keys/ID`	admin	Revoke immediately.

Limits

Queries up to 2,000 characters; top_k up to 50 on both search and retrieve.
Uploaded files up to 50 MB each; PDF, DOCX, TXT and Markdown only.
Crawls up to 20,000 pages per job, capped at the documents left on your plan; crawled pages up to 5 MB each.
Plan limits on sources, documents and monthly searches return 429. See plan limits.

Errors

Errors are JSON with a detail string that says what to change. Validation failures are 422 and name the field.

Status	When
`400`	A crawl URL the policy refuses, or an option this deployment does not allow.
`401`	Missing, revoked or expired key.
`403`	Key lacks the scope, or email not yet verified for ingest calls.
`404`	Not in your workspace.
`413`	File over 50 MB.
`415`	Unsupported file type.
`422`	Invalid body or field value.
`429`	Plan limit reached.
`503`	The job queue was unavailable and the crawl did not start. Retry.