POST /api/v1/jobs — Create a Document Parsing Job

The POST /api/v1/jobs endpoint accepts a document and starts a parse or compare job on FileRouter’s hosted infrastructure. You can submit documents in two ways: as a JSON body with a public URL, or as a raw binary body for direct file uploads. The endpoint always returns immediately with a job ID and an initial status — you then poll GET /api/v1/jobs/{jobId} to retrieve the result.

POST https://filerouter.dev/api/v1/jobs

The TypeScript SDK (FileRouterClient) handles all headers and body serialization automatically, including idempotency key generation. Use the REST API directly only if you’re integrating from a non-TypeScript environment.

Required Headers

Authorization

string

required

Bearer token authentication. Format: Bearer <your-api-key>. See Authentication for details.

Idempotency-Key

string

required

A unique key (8–255 characters) that makes this request safely retryable. If you send the same Idempotency-Key a second time with the same request body, the API returns the original job rather than creating a new one. Use a random UUID or a deterministic key derived from your request content.

Request Formats

JSON Body (URL input)
Binary Body (file upload)

Use this format when your document is accessible at a public HTTP or HTTPS URL. Set Content-Type: application/json and send the job parameters as a JSON object.

Content-Type

Content-Type: application/json

Body Parameters

operation

string

required

The job operation to perform. Must be either "parse" (process with one provider) or "compare" (process with multiple providers side-by-side).

source.url

string

required

The HTTP or HTTPS URL of the document to process. The URL must be publicly accessible from FileRouter’s infrastructure.

outputs

array

required

An array of output format IDs to request (at least one required). Example: ["markdown"]. The available output IDs depend on the provider’s declared capabilities.

pages

array

An optional array of one-based page numbers to process. When omitted, FileRouter processes the entire document. Example: [1, 2, 3].

provider

string

The provider ID to use for a parse operation (e.g., "llamaparse", "mistral-ocr"). When omitted, FileRouter uses a default provider. Only valid when operation is "parse".

providers

array

An array of provider IDs to use for a compare operation. Requires at least one entry. Only valid when operation is "compare".

providerOptions

object

Optional namespaced provider-specific options. Keys are provider IDs; values are objects containing that provider’s native options. Example: { "llamaparse": { "premium_mode": true } }.

includeRaw

boolean

When true, the completed job result includes the full raw response from the provider alongside the normalized outputs. Defaults to false. Use this only when you need provider-native data — raw responses can be large, especially for image-heavy documents.

Example

Create a URL-based parse job

curl https://filerouter.dev/api/v1/jobs \
  --request POST \
  --header "Authorization: Bearer $FILEROUTER_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: parse-annual-report-2024" \
  --data '{
    "operation": "parse",
    "outputs": ["markdown"],
    "source": {
      "url": "https://example.com/annual-report-2024.pdf"
    },
    "provider": "llamaparse"
  }'

Use this format to upload a document directly. Set Content-Type to the document’s MIME type and send the raw file bytes as the request body. All job parameters travel as request headers with the X-FileRouter-* prefix.FileRouter accepts uploads up to 100 MB. The request body streams directly into storage — it is never buffered in memory during ingress.

Content-Type

Set Content-Type to the document’s MIME type, for example:

Content-Type: application/pdf

FileRouter resolves the MIME type in this order: the explicit Content-Type you provide, inference from the filename extension in X-FileRouter-Filename, then a fallback to application/octet-stream.

Upload Headers

X-FileRouter-Filename

string

required

The URL-encoded filename of the document, including its extension (e.g., annual-report-2024.pdf → annual-report-2024.pdf). FileRouter uses this for MIME inference and for naming the stored object. Encode non-ASCII characters with encodeURIComponent.

X-FileRouter-Operation

string

required

The operation to perform: "parse" or "compare".

X-FileRouter-Outputs

string

required

A comma-separated list of output format IDs to request. Example: markdown or markdown,pages.

X-FileRouter-Pages

string

Optional comma-separated list of one-based page numbers to process. Example: 1,2,3. When omitted, FileRouter processes the entire document.

X-FileRouter-Provider

string

The provider ID to use for a parse operation. Only used when X-FileRouter-Operation is parse.

X-FileRouter-Providers

string

A comma-separated list of provider IDs for a compare operation. Only used when X-FileRouter-Operation is compare.

X-FileRouter-Provider-Options

string

Optional URL-encoded JSON string of namespaced provider options. Example: encodeURIComponent(JSON.stringify({ llamaparse: { premium_mode: true } })).

X-FileRouter-Include-Raw

string

Set to "true" to include the full raw provider response in the result. Defaults to "false".

Example

Upload a local PDF file

curl https://filerouter.dev/api/v1/jobs \
  --request POST \
  --header "Authorization: Bearer $FILEROUTER_API_KEY" \
  --header "Content-Type: application/pdf" \
  --header "Idempotency-Key: upload-report-q3-001" \
  --header "X-FileRouter-Filename: q3-report.pdf" \
  --header "X-FileRouter-Operation: parse" \
  --header "X-FileRouter-Outputs: markdown" \
  --header "X-FileRouter-Provider: llamaparse" \
  --data-binary @q3-report.pdf

Responses

202 Accepted — Job created

The API accepted your request and created a new job. The job is now queued or already running.

202 response body

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}

Show Response fields

string

required

The UUID of the newly created job. Use this value to poll GET /api/v1/jobs/{jobId}.

status

string

required

The initial job status. One of "queued", "running", "complete", or "failed".

200 OK — Idempotent replay

You sent an Idempotency-Key that already exists for your account with the same request body. The API returns the original job without starting a new workflow. The response shape is identical to 202.

200 idempotent replay body

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}

Error Responses

400 Bad Request

The request body or headers failed validation. The response body describes the specific field or constraint that failed.

400 error body

{
  "status": 400,
  "code": "validation_error",
  "detail": "outputs: Required",
  "title": "Bad Request",
  "type": "https://filerouter.dev/problems/validation-error",
  "instance": "/api/v1/jobs",
  "request_id": "01J2Y9QX3MXJQHD2YQ9N7J93M4"
}

401 Unauthorized

The Authorization header is missing, invalid, or the API key has been disabled or expired. See Authentication for details.

401 error body

{
  "status": 401,
  "code": "unauthorized",
  "detail": "Missing FileRouter API key.",
  "title": "Unauthorized",
  "type": "https://filerouter.dev/problems/unauthorized",
  "instance": "/api/v1/jobs",
  "request_id": "01J2Y9QX3MXJQHD2YQ9N7J93M4"
}

409 Conflict — Idempotency conflict

You sent the same Idempotency-Key with a different request body. FileRouter will not overwrite an existing idempotency record. Use a new, unique key for a different request.

409 error body

{
  "status": 409,
  "code": "idempotency_conflict",
  "detail": "A job with this idempotency key already exists with different parameters.",
  "title": "Conflict",
  "type": "https://filerouter.dev/problems/idempotency-conflict",
  "instance": "/api/v1/jobs",
  "request_id": "01J2Y9QX3MXJQHD2YQ9N7J93M4"
}

413 Content Too Large

The uploaded file exceeds the 100 MB request body limit. Split your document or contact support about large-file upload sessions.

500 Internal Server Error

An unexpected server-side error occurred. The response includes a request_id — include it when contacting support.

Overview

Endpoints

POST /api/v1/jobs — Create a Document Parsing Job

Required Headers

Request Formats

Content-Type

Body Parameters

Example

Content-Type

Upload Headers

Example

Responses

202 Accepted — Job created

200 OK — Idempotent replay

Error Responses

​Required Headers

​Request Formats

​Content-Type

​Body Parameters

​Example

​Content-Type

​Upload Headers

​Example

​Responses

​202 Accepted — Job created

​200 OK — Idempotent replay

​Error Responses

Required Headers

Request Formats

Content-Type

Body Parameters

Example

Content-Type

Upload Headers

Example

Responses

202 Accepted — Job created

200 OK — Idempotent replay

Error Responses