> ## Documentation Index
> Fetch the complete documentation index at: https://docs.filerouter.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# FileRouter REST API — Base URL, Versioning, and Endpoints

> FileRouter REST API base URL, versioning, content types, OpenAPI spec location, and the two core endpoints for creating and retrieving parse jobs.

The FileRouter REST API gives you direct HTTP access to document parsing and comparison jobs from any language or environment. All endpoints live under a single base URL, return JSON responses, and use `application/problem+json` for structured error details. If you're working in TypeScript, the `FileRouterClient` from `@file_router/sdk` wraps this API automatically — but for any other environment, this reference covers everything you need.

## Base URL

```
https://filerouter.dev
```

Every versioned endpoint is prefixed with `/api/v1/`. The current version is `v1`.

## Authentication

All `/api/v1/` endpoints require a Bearer token in the `Authorization` header:

```
Authorization: Bearer <your-api-key>
```

See the [Authentication](/api/authentication) page for full details and error shapes.

## Content Types

* **Request bodies** — send `application/json` for URL-based jobs, or a raw binary body with the document's MIME type (e.g., `application/pdf`) for file uploads.
* **Responses** — all success responses use `application/json`.
* **Error responses** — all error responses use `application/problem+json`.

## Response Headers

Every response from the API includes an `X-Request-ID` header containing a unique identifier for that request. Include this value when contacting support.

## OpenAPI Specification

FileRouter publishes an OpenAPI 3.1 document you can use to generate client code or explore the API in tools like Swagger UI or Scalar.

```
GET /api/openapi.json
```

This endpoint requires no authentication and returns the full OpenAPI 3.1 schema.

## Endpoints

<CardGroup cols={2}>
  <Card title="POST /api/v1/jobs" icon="circle-plus" href="/api/create-job">
    Create a document parse or compare job. Supports both URL-based and binary file upload inputs.
  </Card>

  <Card title="GET /api/v1/jobs/{jobId}" icon="circle-dot" href="/api/get-job">
    Poll job status and retrieve the parsed result when the job completes.
  </Card>
</CardGroup>

| Method | Path                   | Description                   |
| ------ | ---------------------- | ----------------------------- |
| `POST` | `/api/v1/jobs`         | Create a parse or compare job |
| `GET`  | `/api/v1/jobs/{jobId}` | Get job status and result     |

## Health Check

You can verify the API is reachable and the database is responsive with the health endpoint. It requires no authentication.

```bash title="Check API health" theme={null}
curl https://filerouter.dev/api/v1/health
```

```json title="Health response" theme={null}
{ "status": "ok" }
```

<Note>
  The health endpoint returns `Cache-Control: no-store` — each request actively checks the database connection rather than serving a cached response.
</Note>

## Error Format

All API errors return `application/problem+json` bodies. A 404 for an unknown route, for example, looks like this:

```json title="404 route not found" theme={null}
{
  "status": 404,
  "code": "route_not_found",
  "detail": "No route matched the request path.",
  "title": "Not Found",
  "type": "https://filerouter.dev/problems/route-not-found",
  "instance": "/api/v1/missing",
  "request_id": "01J2Y9QX3MXJQHD2YQ9N7J93M4"
}
```

The `request_id` in the error body always matches the `X-Request-ID` response header, so you can correlate errors across logs and support tickets.