> ## Documentation Index
> Fetch the complete documentation index at: https://docs.file.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Get all files
> Get all files of the current organization and workspace.
This endpoint is paginated. Use the `page` and `limit` query parameters to control pagination.
Alternatively, pass the `cursor` query parameter (empty for the first page) to use cursor pagination: the response envelope becomes `{ data, pagination: { limit, nextCursor, hasMore } }` and pages are stable under concurrent writes. Follow `nextCursor` until `hasMore` is false; keep the same sort and filter parameters for every page of a walk.
Use the optional `updatedAfter` query parameter to filter files that have been updated on or after the specified timestamp (ISO 8601 format).
Use the optional `createdAfter` query parameter to filter files that have been created on or after the specified timestamp (ISO 8601 format).
These filters are useful for batch processes that need to fetch only files modified or created since the last sync.
Use the optional `directoryId` query parameter to return only files that belong to the specified directory (or sub-directory). Files in nested descendants are not included; pass the sub-directory id directly to fetch its files.
Get all files in the organization and workspace bound to your API key.
## Query Parameters
| Parameter | Type | Required | Default | Description |
| ------------ | ------ | -------- | ----------- | --------------------------------------------------------------------------------- |
| fileIds | string | No | — | Comma-separated file ids to fetch |
| directoryId | string | No | — | Return only files belonging to this directory |
| updatedAfter | string | No | — | Only files updated on or after this ISO 8601 timestamp |
| createdAfter | string | No | — | Only files created on or after this ISO 8601 timestamp |
| page | number | No | 1 | Page number for pagination |
| limit | number | No | 100 | Number of items per page |
| sortBy | string | No | `createdAt` | Field to sort by |
| sortOrder | string | No | `ASC` | Sort direction (`ASC` or `DESC`) |
| cursor | string | No | — | Opaque cursor. Send it (empty for the first page) to switch to cursor pagination. |
This endpoint supports both pagination modes. Send the `cursor` parameter
(empty value for the first page) to use cursor pagination; omit it entirely to
keep the legacy `page`/`limit` response shape. See
[Pagination](/docs-api/api-pagination) for the full comparison.
## Filtering by directory
`directoryId` returns only files **directly** linked to that directory. Files in
nested descendants are not included — pass the sub-directory id directly to fetch
its files.
Examples use the default base URL, `https://api.orion.file.ai/prod/v1`. If
your workspace is on an instance-specific host, swap the hostname and change
nothing else — see [Switching between
instances](/docs-api/api-intro#switching-between-instances).
```bash theme={null}
curl -X GET "https://api.orion.file.ai/prod/v1/files?directoryId=68218006ebc72170fdb221f7" \
-H "x-api-key: YOUR_API_KEY"
```
## Incremental sync
`updatedAfter` and `createdAfter` let batch processes fetch only what changed
since the last run. See
[Incremental Data Loading](/docs-api/api-incremental-data-loading) for the full
Change Data Capture pattern.
```bash theme={null}
curl -X GET "https://api.orion.file.ai/prod/v1/files?updatedAfter=2025-07-01T00:00:00.000Z" \
-H "x-api-key: YOUR_API_KEY"
```
## Pagination
Send `cursor` to get a stable walk that is unaffected by concurrent writes.
The response becomes `{ data, pagination }`.
```json theme={null}
{
"data": [{ "id": "649e2d2d2d2d2d2d2d2d2d2d" }],
"pagination": { "limit": 50, "nextCursor": "eyJjcmVhdGVkQXQi...", "hasMore": true }
}
```
Follow `nextCursor` until `hasMore` is `false`, keeping the same sort and
filter parameters for every page of the walk.
Omit `cursor` and the response keeps its original shape.
```json theme={null}
{
"files": [{ "id": "649e2d2d2d2d2d2d2d2d2d2d" }],
"count": 1350,
"currentPage": 1
}
```
See [Pagination](/docs-api/api-pagination) for the full comparison.
## Errors
A `422` is returned when `updatedAfter` or `createdAfter` is not a valid ISO 8601
timestamp. See [Error responses](/docs-api/api-errors).
## OpenAPI
````yaml get /prod/v1/files
openapi: 3.0.0
info:
title: Public API
description: >-
### Welcome to fileAI’s Public API Documentation.
This API allows users to check the health of the system, upload and manage
files, and manage AI Schemas.
Should you have any questions, please reach out to fileAI via the “Contact a
Developer” link below.
[Contact a Developer](mailto:support@file.ai)
### Prerequisites
Before using our API, please ensure you complete the following prerequisites
- You must have a fileAI account. Sign up or login
[here](https://orion.file.ai/en/sign-up)
- You must have an API Key. After creating your fileAI account, you can
generate your API Key. Refer to the Authentication section below for more
details.
### Authentication
All API requests require an API key for authentication.
- To obtain your API key, please log in to your fileAI account and navigate
to Project Settings in your dashboard
- Keep your API key secure and do not share it publicly.
### How to Use Your API Key
Once you have your API key:
- Click the Authorize button on the top-right of this page
- Enter your API Key under Value
- Click Authorize to start making authenticated requests directly from the
documentation
version: '1.0'
contact: {}
servers:
- url: https://api.orion.file.ai
description: Default. Use this unless your workspace is on an instance.
- url: https://api.orion.{instance}.file.ai
description: Instance-specific host.
variables:
instance:
default: au
enum:
- au
- sg
- jp
description: >-
Instance hosting your workspace: au (Australia), sg (Singapore), jp
(Japan).
security: []
tags:
- name: Public API V1
paths:
/prod/v1/files:
get:
tags:
- Public API V1
summary: Get all files
description: >-
Get all files of the current organization and workspace.
This endpoint is paginated. Use the `page` and `limit` query parameters
to control pagination.
Alternatively, pass the `cursor` query parameter (empty for the first
page) to use cursor pagination: the response envelope becomes `{ data,
pagination: { limit, nextCursor, hasMore } }` and pages are stable under
concurrent writes. Follow `nextCursor` until `hasMore` is false; keep
the same sort and filter parameters for every page of a walk.
Use the optional `updatedAfter` query parameter to filter files that
have been updated on or after the specified timestamp (ISO 8601 format).
Use the optional `createdAfter` query parameter to filter files that
have been created on or after the specified timestamp (ISO 8601 format).
These filters are useful for batch processes that need to fetch only
files modified or created since the last sync.
Use the optional `directoryId` query parameter to return only files that
belong to the specified directory (or sub-directory). Files in nested
descendants are not included; pass the sub-directory id directly to
fetch its files.
operationId: PublicAPIController_getAllDocuments
parameters:
- name: fileIds
required: false
in: query
description: File Ids
schema:
example: 649e2d2d2d2d2d2d2d2d2d2d
type: string
- name: updatedAfter
required: false
in: query
description: Filter files updated on or after this timestamp (ISO 8601 format)
schema:
example: '2025-01-01T00:00:00.000Z'
type: string
- name: createdAfter
required: false
in: query
description: Filter files created on or after this timestamp (ISO 8601 format)
schema:
example: '2025-01-01T00:00:00.000Z'
type: string
- name: directoryId
required: false
in: query
description: >-
Filter files that belong to the given directory (or sub-directory)
id. Only files directly linked to this directory are returned;
descendants are not included.
schema:
example: 649e2d2d2d2d2d2d2d2d2d2d
type: string
- name: page
required: false
in: query
description: Page number
schema:
default: 1
example: 1
type: number
- name: limit
required: false
in: query
description: Number of items per page
schema:
default: 100
example: 100
type: number
- name: sortBy
required: false
in: query
description: Field to sort by
schema:
default: createdAt
example: createdAt
type: string
- name: sortOrder
required: false
in: query
description: Sort direction
schema:
default: ASC
example: ASC
type: string
enum:
- ASC
- DESC
- name: cursor
required: false
in: query
description: >-
Opaque pagination cursor. Provide the parameter (empty value for the
first page) to switch to cursor pagination: the response becomes {
data, pagination: { limit, nextCursor, hasMore } } with default
limit 50 (max 100). Omit it entirely for legacy page/limit
pagination. In cursor mode sortBy must be one of createdAt,
updatedAt, _id, and cursors are bound to the sortBy/sortOrder they
were minted with.
schema:
type: string
responses:
'200':
description: >-
The list of files is found. Offset mode (default) returns `{files,
count, currentPage}`; cursor mode (when the `cursor` query parameter
is present) returns `{data, pagination}`.
content:
application/json:
examples:
offset:
summary: Offset pagination (default)
value:
files:
- fileId: 53d6a0b1-2a8d-4ed9-9e6a-ceaef7ca3908
fileName: file1.jpg
fileType: image/jpeg
fileSize: 261928
fileStoragePath: path/to/file1.jpg
fileHash: >-
be3ef5fbb21e31c1281300b23b1c918a8ba54427c799aea21865f68d5efd01b7
uploadId: f2538513-f0b9-4aa8-9c57-bc0a85c77de6
status: processed
currency: USD
summary: Example file
referenceId: 1e70a5e860
isDuplicate: false
isEmbedded: false
schemaId: 6835aca6030a79ffaabca742
fileClass: Receipt
fileContactId: 6835aca2281d9ed1bab90b11
fileContactName: Example Company
createdAt: '2025-05-27T12:14:24.258Z'
updatedAt: '2025-05-27T12:14:24.258Z'
directoryIds:
- 6a0d8fa8e00fd1d2a80c6aa7
- 6a0d8fa8e00fd1d2a80c6ab1
exportInfo:
integrationExportStatus: completed
integrationExportMessages:
- System successfully received result
integrationExportUpdatedAt: '2025-05-27T14:30:00.000Z'
count: 1
currentPage: 1
cursor:
summary: Cursor pagination (`cursor` param present)
value:
data:
- fileId: 53d6a0b1-2a8d-4ed9-9e6a-ceaef7ca3908
fileName: file1.jpg
createdAt: '2025-05-27T12:14:24.258Z'
updatedAt: '2025-05-27T12:14:24.258Z'
pagination:
limit: 50
nextCursor: eyJ2IjoxLCJrIjpb...
hasMore: true
schema:
oneOf:
- $ref: '#/components/schemas/GetAllDocumentsOffsetOutput'
- $ref: '#/components/schemas/GetAllDocumentsCursorOutput'
'401':
description: Missing or invalid API key.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'403':
description: Read-only or inactive API key.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'404':
description: Resource not found.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'422':
description: Invalid timestamp parameter
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
examples:
Invalid updatedAfter:
summary: Invalid updatedAfter
value:
type: https://errors.file.ai/validation-failed
title: Validation failed
status: 422
detail: Invalid updatedAfter. Must be a valid ISO 8601 timestamp.
instance: /v1/{route}
code: VALIDATION_FAILED
requestId: 0f1c8e03-978e-40d5-bc93-6894a57f9324
errors: []
message: Invalid updatedAfter. Must be a valid ISO 8601 timestamp.
error: Unprocessable Entity
statusCode: 422
Invalid createdAfter:
summary: Invalid createdAfter
value:
type: https://errors.file.ai/validation-failed
title: Validation failed
status: 422
detail: Invalid createdAfter. Must be a valid ISO 8601 timestamp.
instance: /v1/{route}
code: VALIDATION_FAILED
requestId: 0f1c8e03-978e-40d5-bc93-6894a57f9324
errors: []
message: Invalid createdAfter. Must be a valid ISO 8601 timestamp.
error: Unprocessable Entity
statusCode: 422
'429':
description: Rate limit exceeded.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'500':
description: Unexpected internal error.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
security:
- x-api-key: []
components:
schemas:
GetAllDocumentsOffsetOutput:
type: object
properties:
files:
type: array
items:
$ref: '#/components/schemas/DocumentForPAOutput'
count:
type: number
description: Total number of matching files
currentPage:
type: number
required:
- files
- count
- currentPage
GetAllDocumentsCursorOutput:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/DocumentForPAOutput'
pagination:
$ref: '#/components/schemas/CursorPaginationMeta'
required:
- data
- pagination
ProblemDetailsDto:
type: object
properties:
type:
type: string
description: A URI identifying the problem type.
example: https://errors.file.ai/validation-failed
title:
type: string
description: Stable, human-readable summary of the problem type.
example: Validation failed
status:
type: number
description: HTTP status code.
example: 422
detail:
type: string
description: Human-readable explanation specific to this occurrence.
example: One or more fields are invalid.
instance:
type: string
description: URI reference for this occurrence (the request path).
example: /v1/files/upload
code:
type: string
description: Stable machine-readable error code.
example: VALIDATION_FAILED
requestId:
type: string
description: Correlation id for this request.
example: 0f1c8e03-978e-40d5-bc93-6894a57f9324
errors:
description: Field-level violations (validation only).
type: array
items:
$ref: '#/components/schemas/ProblemErrorItemDto'
retryAfter:
type: number
description: Seconds until the client may retry (present on 429 only).
example: 42
message:
type: string
description: Legacy key (deprecated — use `detail`/`title`).
example: Validation failed
error:
type: string
description: Legacy key (deprecated — use `title`).
example: Unprocessable Entity
statusCode:
type: number
description: Legacy key (deprecated — use `status`).
example: 422
required:
- type
- title
- status
- detail
- instance
- code
- requestId
- errors
- message
- error
- statusCode
DocumentForPAOutput:
type: object
properties: {}
CursorPaginationMeta:
type: object
properties:
limit:
type: number
description: Page size applied (default 50, max 100)
nextCursor:
type: string
description: Opaque cursor for the next page; null when hasMore is false
nullable: true
hasMore:
type: boolean
required:
- limit
- nextCursor
- hasMore
ProblemErrorItemDto:
type: object
properties:
code:
type: string
example: REQUIRED
detail:
type: string
example: must not be empty
pointer:
type: string
description: JSON Pointer to the offending body field.
example: '#/fileName'
parameter:
type: string
description: Name of the offending query/header parameter.
example: limit
required:
- code
- detail
securitySchemes:
x-api-key:
type: apiKey
in: header
name: x-api-key
description: API key for authentication
````