Files API

The Files API enables uploading source documents and listing resource IDs that can be resolved through the authenticated document-session endpoint.

List Files

Retrieve all files in a specific container (folder) for your organization.

GET /api/v1/files/{container}

Path Parameters

Parameter	Type	Required	Description
`container`	string	Yes	Container/folder name (e.g., ‘templates’, ‘documents’, ‘input’)

Request Example

curl -X GET "https://api.artosai.com/api/v1/files/documents" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "files": [
    {
      "name": "protocol.pdf",
      "resource_id": "sourcefile-org-id/documents/protocol.pdf"
    },
    {
      "name": "csr-data.xlsx",
      "resource_id": "sourcefile-org-id/documents/csr-data.xlsx"
    }
  ]
}

Response Fields

Field	Type	Description
`files`	array	Array of file objects
`files[].name`	string	File name
`files[].resource_id`	string	Opaque Artos resource identifier to pass to the document-session endpoint.

Status Codes

200 OK: Successfully retrieved file list
400 Bad Request: Authentication failed
401 Unauthorized: Missing or invalid Bearer token
500 Internal Server Error: S3 operation failed

Upload File

Upload a file to S3. Automatically converts DOCX to PDF (except in templates container). Validates file type by extension and MIME type.

POST /api/v1/files/upload

Request

Content-Type: multipart/form-data

Parameter	Type	Required	Description
`file_name`	string	Yes	Name to give the uploaded file
`file_content`	file	Yes	Binary file content
`container`	string	Yes	Container/folder name for upload

Supported File Types

.docx - Word documents
.pdf - PDF documents
.csv - CSV files
.xlsx - Excel spreadsheets
.rtf - Rich Text Format

Request Example

curl -X POST "https://api.artosai.com/api/v1/files/upload" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file_name=protocol.pdf" \
  -F "file_content=@/path/to/protocol.pdf" \
  -F "container=documents"

Python Example

import requests

url = "https://api.artosai.com/api/v1/files/upload"
headers = {"Authorization": "Bearer YOUR_TOKEN"}

files = {
    "file_name": (None, "protocol.pdf"),
    "container": (None, "documents"),
    "file_content": open("/path/to/protocol.pdf", "rb")
}

response = requests.post(url, headers=headers, files=files)
print(response.json())

Response

{
  "message": "File uploaded successfully"
}

Status Codes

200 OK: File uploaded successfully
400 Bad Request: File validation failure (invalid type, size, etc.)
401 Unauthorized: Missing or invalid Bearer token
500 Internal Server Error: S3 upload failed

Error Examples

Invalid File Type:

{
  "detail": "File type .exe is not supported"
}

Missing Required Field:

{
  "detail": "Missing required parameter: container"
}

Auto-Conversion: DOCX to PDF

Files uploaded as .docx are automatically converted to PDF (except in the templates container):

Input: document.docx
Output: document.pdf
Exception: Files uploaded to templates container are not converted

This ensures compatibility with document processing pipelines while allowing template files to remain in their original format.

Container Types

Common container names and their purposes:

Container	Purpose
`documents`	Processed documents
`templates`	Template files (not auto-converted)
`input`	Source documents for ingestion
`output`	Generated output files

Downloading Files

For source-file viewers, use POST /source-file with the source file’s resource_id and the user’s organization Bearer token. This endpoint authorizes the user on every request and does not accept a document session token:

curl -X POST "https://api.artosai.com/source-file" \
  -H "Authorization: Bearer $OKTA_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"resource_id":"sourcefile-org-id/input/protocol.pdf"}' \
  -o protocol.pdf

OnlyOffice uses the separate POST /document-file-session and POST /generate-onlyoffice-config flow. For ordinary session-based document viewers, use the session endpoint to obtain a short-lived session token:

SESSION_TOKEN="<session_token returned by document-file-session>"
curl "https://api.artosai.com/open-document" \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -o protocol.pdf

Never put the document session token in ?session_token=.... Query strings are commonly captured by access logs, browser history, proxies, and monitoring systems. The query-string form is reserved for the OnlyOffice server-to-server request and is accepted only when accompanied by a separately signed OnlyOffice JWT; a copied URL alone cannot download the file.

Getting Started

API Reference

Core Concepts

Single-Tenant

Cookbooks

NPM SDK Reference

Integrations

Deployment

Files API

Files API

List Files

Path Parameters

Request Example

Response

Response Fields

Status Codes

Upload File

Request

Supported File Types

Request Example

Python Example

Response

Status Codes

Error Examples

Auto-Conversion: DOCX to PDF

Container Types

Downloading Files

​Files API

​List Files

​Path Parameters

​Request Example

​Response

​Response Fields

​Status Codes

​Upload File

​Request

​Supported File Types

​Request Example

​Python Example

​Response

​Status Codes

​Error Examples

​Auto-Conversion: DOCX to PDF

​Container Types

​Downloading Files

Files API

List Files

Path Parameters

Request Example

Response

Response Fields

Status Codes

Upload File

Request

Supported File Types

Request Example

Python Example

Response

Status Codes

Error Examples

Auto-Conversion: DOCX to PDF

Container Types

Downloading Files