Files API

On this page

Upload files for analysis and download them again. See Files.

Paths are relative to https://<your-atlas-host>/api/v1. For the API key and headers every request needs, see Authentication.

Scroll horizontally to see the full table.

Endpoint	What it does
GET /files/	List files in a workspace
POST /files/upload/	Upload a file to a workspace for processing
GET /files/{file_id}/	Get a file’s details and processing status
DELETE /files/{file_id}/	Delete a file
PATCH /files/{file_id}/	Rename a file’s user-facing display name
GET /files/{file_id}/download/	Download a file’s original content
POST /files/{file_id}/reprocess/	Re-run parsing/profiling for a file (e.g

List files

GET /files/

List files in a workspace.

Parameters

Scroll horizontally to see the full table.

Name	In	Type	Required	Description
`workspace_id`	query	UUID	Yes
`status`	query	string		`pending`, `processing`, `ready` or `failed`.
`category`	query	string		`tabular`, `document`, `image` or `unknown`.
`q`	query	string		Case-insensitive search on the file name.
`limit`	query	integer
`offset`	query	integer

Response A list of objects:

Scroll horizontally to see the full table.

Field	Type	Description
`id`	UUID
`display_name`	string
`original_filename`	string
`workspace_id`	UUID
`storage_path`	string
`mime_type`	string
`file_size`	integer
`category`	string	From the extension: `tabular` (csv, xlsx, parquet…), `document` (pdf, txt, md), `image`, or `unknown`.
`status`	string	`pending`, then `processing`, then `ready` or `failed` (see `error_message`).
`error_message`	string
`summary`	string	AI-generated summary of the file’s content.
`schema_info`	object	Structure extracted from the file, such as columns, row count, and sheets.
`uploaded_by_id`	UUID
`created_at`	datetime
`updated_at`	datetime
`is_stuck`	boolean	Pending or processing for over 30 minutes without progress; reprocess it.

Upload file

POST /files/upload/

Upload a file to a workspace for processing.

Form fields

Scroll horizontally to see the full table.

Field	Type	Required
`file`	file	Yes
`workspace_id`	UUID	Yes

Response

Scroll horizontally to see the full table.

Field	Type	Description
`id`	UUID
`display_name`	string
`original_filename`	string
`workspace_id`	UUID
`storage_path`	string
`mime_type`	string
`file_size`	integer
`category`	string	From the extension: `tabular` (csv, xlsx, parquet…), `document` (pdf, txt, md), `image`, or `unknown`.
`status`	string	`pending`, then `processing`, then `ready` or `failed` (see `error_message`).
`error_message`	string
`summary`	string	AI-generated summary of the file’s content.
`schema_info`	object	Structure extracted from the file, such as columns, row count, and sheets.
`uploaded_by_id`	UUID
`created_at`	datetime
`updated_at`	datetime
`is_stuck`	boolean	Pending or processing for over 30 minutes without progress; reprocess it.

Get file

GET /files/{file_id}/

Get a file’s details and processing status.

Parameters

Scroll horizontally to see the full table.

Name	In	Type	Required
`file_id`	path	UUID	Yes

Response

Scroll horizontally to see the full table.

Field	Type	Description
`id`	UUID
`display_name`	string
`original_filename`	string
`workspace_id`	UUID
`storage_path`	string
`mime_type`	string
`file_size`	integer
`category`	string	From the extension: `tabular` (csv, xlsx, parquet…), `document` (pdf, txt, md), `image`, or `unknown`.
`status`	string	`pending`, then `processing`, then `ready` or `failed` (see `error_message`).
`error_message`	string
`summary`	string	AI-generated summary of the file’s content.
`schema_info`	object	Structure extracted from the file, such as columns, row count, and sheets.
`uploaded_by_id`	UUID
`created_at`	datetime
`updated_at`	datetime
`is_stuck`	boolean	Pending or processing for over 30 minutes without progress; reprocess it.

Delete file

DELETE /files/{file_id}/

Delete a file.

Parameters

Scroll horizontally to see the full table.

Name	In	Type	Required
`file_id`	path	UUID	Yes

Response

The raw file content.

Rename file

PATCH /files/{file_id}/

Rename a file’s user-facing display name.

Parameters

Scroll horizontally to see the full table.

Name	In	Type	Required
`file_id`	path	UUID	Yes

Request body

Scroll horizontally to see the full table.

Field	Type	Required
`display_name`	string	Yes

Response

Scroll horizontally to see the full table.

Field	Type	Description
`id`	UUID
`display_name`	string
`original_filename`	string
`workspace_id`	UUID
`storage_path`	string
`mime_type`	string
`file_size`	integer
`category`	string	From the extension: `tabular` (csv, xlsx, parquet…), `document` (pdf, txt, md), `image`, or `unknown`.
`status`	string	`pending`, then `processing`, then `ready` or `failed` (see `error_message`).
`error_message`	string
`summary`	string	AI-generated summary of the file’s content.
`schema_info`	object	Structure extracted from the file, such as columns, row count, and sheets.
`uploaded_by_id`	UUID
`created_at`	datetime
`updated_at`	datetime
`is_stuck`	boolean	Pending or processing for over 30 minutes without progress; reprocess it.

Download file

GET /files/{file_id}/download/

Download a file’s original content.

Parameters

Scroll horizontally to see the full table.

Name	In	Type	Required
`file_id`	path	UUID	Yes

Response

The raw file content.

Reprocess file

POST /files/{file_id}/reprocess/

Re-run parsing/profiling for a file (e.g. after a processing failure).

Parameters

Scroll horizontally to see the full table.

Name	In	Type	Required
`file_id`	path	UUID	Yes

Response

Scroll horizontally to see the full table.

Field	Type	Description
`id`	UUID
`display_name`	string
`original_filename`	string
`workspace_id`	UUID
`storage_path`	string
`mime_type`	string
`file_size`	integer
`category`	string	From the extension: `tabular` (csv, xlsx, parquet…), `document` (pdf, txt, md), `image`, or `unknown`.
`status`	string	`pending`, then `processing`, then `ready` or `failed` (see `error_message`).
`error_message`	string
`summary`	string	AI-generated summary of the file’s content.
`schema_info`	object	Structure extracted from the file, such as columns, row count, and sheets.
`uploaded_by_id`	UUID
`created_at`	datetime
`updated_at`	datetime
`is_stuck`	boolean	Pending or processing for over 30 minutes without progress; reprocess it.

What’s next?

API overview: authentication, worked examples, and error handling
Webhooks: get events pushed to your systems instead of polling
Service accounts: create the key an integration uses