API quickstart

What you’ll have at the end: a document uploaded through the API and its extracted values back as structured JSON, plus the fileId you need for every other guide.

You need: a fileAI workspace and an API key. Workspace admins create keys in the fileAI app. Keys only work on the instance that issued them.

Set your key and base URL

export FILEAI_API_KEY="your-api-key"
export FILEAI_BASE_URL="https://api.orion.file.ai/prod/v1"

Using a regional instance? Swap the host. See Regions.Check the connection:

curl "$FILEAI_BASE_URL/health-check" -H "x-api-key: $FILEAI_API_KEY"

Response

{ "message": "Public API is up and running!" }

Request an upload URL

fileAI uploads go straight to storage. First ask for a presigned URL:

curl -X POST "$FILEAI_BASE_URL/files/upload" \
  -H "x-api-key: $FILEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "fileName": "invoice.pdf", "fileType": "application/pdf" }'

import os, requests

BASE = os.environ["FILEAI_BASE_URL"]
HEADERS = {"x-api-key": os.environ["FILEAI_API_KEY"]}

upload = requests.post(
    f"{BASE}/files/upload",
    headers=HEADERS,
    json={"fileName": "invoice.pdf", "fileType": "application/pdf"},
).json()

const BASE = process.env.FILEAI_BASE_URL;
const headers = { "x-api-key": process.env.FILEAI_API_KEY };

const upload = await fetch(`${BASE}/files/upload`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ fileName: "invoice.pdf", fileType: "application/pdf" }),
}).then((r) => r.json());

Response

{
  "uploadId": "…",
  "presignedUploadURL": "https://…",
  "s3Path": "…"
}

Upload the file

PUT the raw bytes to presignedUploadURL. The URL expires after 5 minutes.

curl -X PUT "<presignedUploadURL>" \
  -H "Content-Type: application/pdf" \
  --data-binary @invoice.pdf

Processing starts automatically once the upload lands.

Track processing

Poll the upload until its steps complete, or skip polling by passing a callbackURL when you request the upload (processing callbacks). Async jobs compares the two.

curl "$FILEAI_BASE_URL/uploads/<uploadId>" -H "x-api-key: $FILEAI_API_KEY"

The response lists each processing step in statuses and the resulting documents in files. Note the fileId of your document.

Read the structured values

curl "$FILEAI_BASE_URL/files/<fileId>/values" -H "x-api-key: $FILEAI_API_KEY"

Response (trimmed)

{
  "formValues": [
    {
      "fileId": "…",
      "schemaName": "Invoice",
      "fields": [
        { "title": "Supplier", "type": "string", "value": "Northwind Supplies" },
        { "title": "Total due", "type": "number", "value": 4820 }
      ]
    }
  ],
  "count": 1,
  "currentPage": 1
}

formValues holds one entry per AI Schema, each with its fields: the field’s title, type and extracted value. Data types explains each value shape. To see where a value came from on the page, see Citations and validations.

Next steps

Shape the output with AI Schemas

Define exactly which fields you want, across one file or many.

Large files and batches

Multipart uploads, batch registration and ZIP archives.

Extract without storing

One-shot extract, split and classify jobs.

Authentication and regions

API keys, regional base URLs and request conventions.

Get started

Products

Build

Go live

Next steps

Shape the output with AI Schemas

Large files and batches

Extract without storing

Authentication and regions

​Next steps

Shape the output with AI Schemas

Large files and batches

Extract without storing

Authentication and regions

Next steps