Authentication and regions

Every fileAI API request carries an API key in the x-api-key header and goes to the host of the instance your workspace lives on. The API is REST over HTTPS, with the same paths, methods and bodies on every instance.

Before you start

You need:

A fileAI account. Sign up or sign in on the Developer Portal. Already use the fileAI app at orion.file.ai? The same sign-in works on both, so you can move between them without signing in again. Self-serve and enterprise accounts both work.
An API key. Only workspace admins can create one (see below).
An approved AI Schema (Verify in the app) if you want structured values back. fileAI suggests schemas as files arrive; confirm or edit them in the app. See AI Schemas and Concepts.

Create an API key

Choose your project

Sign in to the Developer Portal as a workspace admin, then pick the organization and project from the switcher at the top.

Create the key

Open API Keys in the sidebar and click Create API Key. Fill in the form, then click Generate token:

Name: anything that tells you where the key is used.
Expiration: 7, 30, 60 or 90 days, or Never.
Permissions: Read only (fetch data, but not change it) or Full Access (read and change data).

A project key works for both fileScout and fileForensics.

Copy it now

The key is shown once. Copy it and store it in a secret manager or environment variable.

The Developer Portal works with Developer Portal workspaces. If your workspace was set up in the fileAI app, create keys in the app instead: Settings → API Keys at orion.file.ai.

Treat the key like a password. Never commit it to source control or ship it in client-side code. Anyone holding it can act on your workspace.

Key types

There are two kinds of key. Both work on one instance only.

Key	Reaches	Project on each request
Project key	One project.	Not needed. The key’s own project is used and any `x-project-id` header is ignored.
Personal key	Several projects, across the workspaces the key covers. MCP clients use these.	Required: send the project id in an `x-project-id` header. Without it the request returns `400`; a project you can’t open returns `403`.

Personal keys cannot call PATCH /v1/project/setting, which needs a project admin. See Concepts for how workspaces, projects and folders relate.

What a key can do

Key state	What happens
Read-only	`GET` requests only. Any other method returns `403` with code `READONLY_KEY`.
Inactive	Every request returns `403` (`API key is inactive.`).
Missing or unknown	`401` (`API key is missing` or `Invalid API key.`).

Authenticate a request

Send the key in the x-api-key header:

curl "https://api.orion.file.ai/prod/v1/health-check" \
  -H "x-api-key: $FILEAI_API_KEY"

import os, requests

r = requests.get(
    "https://api.orion.file.ai/prod/v1/health-check",
    headers={"x-api-key": os.environ["FILEAI_API_KEY"]},
)
print(r.json())

const r = await fetch("https://api.orion.file.ai/prod/v1/health-check", {
  headers: { "x-api-key": process.env.FILEAI_API_KEY },
});
console.log(await r.json());

Response

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

Try requests in the docs

Every endpoint page in the API reference tab has a playground. Enter your key, pick your region from the server dropdown, and send the request. The code samples update to match, so you can copy a snippet that already points at the right host.

Regions

fileAI runs separate instances. Each serves exactly the same API and differs only in the hostname.

Instance	Region	Base URL	App
Default	Hosted in the US	`https://api.orion.file.ai/prod/v1`	orion.file.ai
`au`	Australia	`https://api.orion.au.file.ai/prod/v1`	orion.au.file.ai
`sg`	Singapore	`https://api.orion.sg.file.ai/prod/v1`	orion.sg.file.ai
`jp`	Japan	`https://api.orion.jp.file.ai/prod/v1`	orion.jp.file.ai

Use the default unless you have been told otherwise. Every example in these docs uses it. Not sure which instance your workspace is on? Ask your account manager or support@file.ai.

A workspace belongs to exactly one instance, and a key only authenticates on the host that issued it. A request to another instance fails authentication even though the endpoint exists there. Switch the base URL and the key together.

Switching between instances

Only the hostname changes, so switching never means rewriting a request. Keep the host in one variable and build every path from it:

# Default
export FILEAI_BASE_URL="https://api.orion.file.ai/prod/v1"

# Singapore
export FILEAI_BASE_URL="https://api.orion.sg.file.ai/prod/v1"

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

Every guide sets FILEAI_BASE_URL to …/prod/v1 and appends the endpoint path, for example $FILEAI_BASE_URL/files/upload. In Python and Node the guides use BASE = "https://api.orion.file.ai/prod/v1" the same way. In a one-off cURL command, replace the host and leave the path, query string, headers and body as they are:

# Default
curl "https://api.orion.file.ai/prod/v1/files" -H "x-api-key: $FILEAI_API_KEY"

# Same call, Japan instance
curl "https://api.orion.jp.file.ai/prod/v1/files" -H "x-api-key: $FILEAI_API_KEY"

Request conventions

Convention	Detail
Methods	`GET`, `POST`, `PATCH` and `DELETE`.
Request bodies	JSON (`Content-Type: application/json`) for every endpoint except `POST /v1/extract`, `POST /v1/split`, `POST /v1/classify` and `POST /v1/files/schema/import`. Those take `multipart/form-data`; the extract, split and classify endpoints take the document in a `file` field, up to 50 MB.
Project	Personal keys send `x-project-id` on each request. See Key types.
File uploads	Files go straight to storage through a presigned URL, not through the API. See Uploads.
Request ids	Every response carries an `X-Request-Id` header. Quote it when you contact support. See Request ids.
Errors	RFC 9457 problem documents with a stable `code`. See Errors.
Retries	Send an `Idempotency-Key` header on JSON writes to make retries safe. Multipart endpoints ignore it. See Idempotency.
Rate limits	Requests over your limit return `429`. See Rate limits.
Pagination	List endpoints page their results. See Pagination.

API quickstart

Upload a file and read its values in about 5 minutes.

Errors

Status codes, problem documents and error codes.

Idempotency

Retry writes without applying them twice.

Workspace setup

Invite your team and manage roles.

Get started

Products

Build

Go live

Authentication and regions

Before you start

Create an API key

Key types

What a key can do

Authenticate a request

Try requests in the docs

Regions

Switching between instances

Request conventions

API quickstart

Errors

Idempotency

Workspace setup

​Before you start

​Create an API key

​Key types

​What a key can do

​Authenticate a request

​Try requests in the docs

​Regions

​Switching between instances

​Request conventions

​Related

API quickstart

Errors

Idempotency

Workspace setup

Before you start

Create an API key

Key types

What a key can do

Authenticate a request

Try requests in the docs

Regions

Switching between instances

Request conventions

Related