Skip to main content

​
Files API

The Files API enables uploading source documents to S3 and retrieving files with presigned URLs for direct download.

​
List Files

Retrieve all files in a specific container (folder) for your organization. 
GET /api/v1/files/{container}

​
Path Parameters

ParameterTypeRequiredDescription
containerstringYesContainer/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",
      "url": "https://s3.amazonaws.com/bucket/protocol.pdf?X-Amz-Algorithm=..."
    },
    {
      "name": "csr-data.xlsx",
      "url": "https://s3.amazonaws.com/bucket/csr-data.xlsx?X-Amz-Algorithm=..."
    }
  ]
}

​
Response Fields

FieldTypeDescription
filesarrayArray of file objects
files[].namestringFile name
files[].urlstringPresigned S3 URL for direct access

​
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
ParameterTypeRequiredDescription
file_namestringYesName to give the uploaded file
file_contentfileYesBinary file content
containerstringYesContainer/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:
ContainerPurpose
documentsProcessed documents
templatesMRT template files (not auto-converted)
inputSource documents for ingestion
outputGenerated output files

​
Presigned URLs

File URLs returned by the API are presigned S3 URLs that:
  • Allow direct download without additional authentication
  • Expire after 1 hour for security
  • Require HTTPS to access
  • Are organization-scoped in the URL path

​
Using Presigned URLs

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

# Download file using presigned URL (no auth needed)
curl -X GET "https://s3.amazonaws.com/bucket/file.pdf?X-Amz-Algorithm=..."