Files API Documentation

Binary file storage API for documents, images, and any file format up to 100MB.

Quick Reference

Base URL:

https://api.ainoflow.io

Authentication:

Authorization: Bearer your_api_key_here

Supported File Types

Documents

PDF, DOC, DOCX, TXT, RTF

Images

JPEG, PNG, GIF, BMP, TIFF, WebP

Media

MP4, AVI, MP3, WAV

Data

JSON, XML, CSV, Excel

Other

Any binary format

Main Endpoints

GET

List All Categories

/api/v1/files

Get all distinct categories with file counts. Useful for navigation and discovering what categories exist.

Response (200 OK):

[
  { "category": "documents", "count": 87 },
  { "category": "images", "count": 245 },
  { "category": "temp", "count": 12 }
]

Response header: X-Total-Count shows total number of categories

POST

Upload File (Auto-generated Key)

/api/v1/files/{category}

Upload a binary file with auto-generated UUID key. Supports direct file upload or URL-based upload.

Path Parameters:

category

required

- Logical grouping (namespace), max 100 chars

Request Body (multipart/form-data):

file

optional

- Binary file data (required if sourceUrl not provided)

sourceUrl

optional

- URL to download file from (required if file not provided)

contentType

optional

- Override content type detection

expiresAt

optional

- File expiration date (ISO 8601)

Direct File Upload:

curl -X POST "https://api.ainoflow.io/api/v1/files/documents" \
  -H "Authorization: Bearer your_api_key_here" \
  -F "file=@contract.pdf" \
  -F "contentType=application/pdf"

URL-based Upload:

curl -X POST "https://api.ainoflow.io/api/v1/files/images" \
  -H "Authorization: Bearer your_api_key_here" \
  -F "sourceUrl=https://example.com/photo.jpg"

URL-based upload includes automatic content-type detection

Response (201 Created):

{
  "category": "documents",
  "key": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "fileName": "contract.pdf",
  "contentType": "application/pdf",
  "size": 1048576,
  "version": 1,
  "etag": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "createdAt": "2024-01-15T10:30:00Z",
  "expiresAt": null,
  "downloadUrl": "https://storage.example.com/...",
  "downloadUrlExpiresAt": "2024-01-15T11:30:00Z"
}

POST

Upload File (Explicit Key)

/api/v1/files/{category}/{key}

Upload a new file with your own custom key. Returns 409 Conflict if file already exists.

Path Parameters:

category

required

- Logical grouping (namespace), max 100 chars

key

required

- Unique identifier, max 200 chars

Request Body (multipart/form-data):

file

optional

- Binary file data (required if sourceUrl not provided)

sourceUrl

optional

- URL to download file from (required if file not provided)

contentType

optional

- Override content type detection

expiresAt

optional

- File expiration date (ISO 8601)

Request:

curl -X POST "https://api.ainoflow.io/api/v1/files/documents/contract-2024.pdf" \
  -H "Authorization: Bearer your_api_key_here" \
  -F "file=@contract.pdf" \
  -F "contentType=application/pdf"

Response (201 Created):

{
  "category": "documents",
  "key": "contract-2024.pdf",
  "fileName": "contract-2024.pdf",
  "contentType": "application/pdf",
  "size": 1048576,
  "version": 1,
  "etag": "a1b2c3d4e5f6g7h8...",
  "createdAt": "2024-01-15T10:30:00Z",
  "expiresAt": null,
  "downloadUrl": "https://storage.example.com/...",
  "downloadUrlExpiresAt": "2024-01-15T11:30:00Z"
}

Note: Returns 409 Conflict if file already exists. Use PUT to update/replace existing files.

PUT

Update/Replace File

/api/v1/files/{category}/{key}

Upload or replace a file at specified location. Creates if not exists, updates if exists.

Path Parameters:

category

required

- Logical grouping (namespace)

key

required

- Unique identifier inside category

Request Body (multipart/form-data):

file

optional

- Binary file data (required if sourceUrl not provided)

sourceUrl

optional

- URL to download file from (required if file not provided)

contentType

optional

- Override content type detection

expiresAt

optional

- File expiration date (ISO 8601)

Request:

curl -X PUT "https://api.ainoflow.io/api/v1/files/documents/contract-2024.pdf" \
  -H "Authorization: Bearer your_api_key_here" \
  -F "file=@contract-v2.pdf"

Response:

Returns 200 OK if file was replaced, 201 Created if new file was created. Same response format as POST endpoint.

GET

Download File

/api/v1/files/{category}/{key}

Download binary file content directly

Query Parameters:

isInline

optional

- If true, sets Content-Disposition to inline for browser display (default: false)

Request:

# Download as attachment
curl -X GET "https://api.ainoflow.io/api/v1/files/documents/contract-2024.pdf" \
  -H "Authorization: Bearer your_api_key_here" \
  -o contract.pdf

# Display inline in browser
curl -X GET "https://api.ainoflow.io/api/v1/files/images/logo.png?isInline=true" \
  -H "Authorization: Bearer your_api_key_here"

Response Headers:

• Content-Type - Original file content type
• Content-Length - File size in bytes
• Content-Disposition - attachment or inline
• ETag - File hash for caching
• Last-Modified - When file was last updated

GET

Get File Metadata

/api/v1/files/{category}/{key}/meta

Get metadata about a file without downloading the content

Response (200 OK):

{
  "category": "documents",
  "key": "invoice-123.pdf",
  "fileName": "invoice-123.pdf",
  "contentType": "application/pdf",
  "size": 1048576,
  "etag": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T14:20:00Z",
  "expiresAt": null,
  "version": 3,
  "createdBy": "api_key_123",
  "updatedBy": "api_key_456"
}

Response Headers:

X-Category, X-Key, ETag, X-Version, X-Updated-At

GET

Get Pre-signed Download URL

/api/v1/files/{category}/{key}/url

Get a pre-signed URL for direct file download without API authentication

Query Parameters:

expirySeconds

optional

- URL expiration time in seconds (default: 3600, max: 86400)

Request:

curl -X GET "https://api.ainoflow.io/api/v1/files/documents/contract-2024.pdf/url?expirySeconds=7200" \
  -H "Authorization: Bearer your_api_key_here"

Response (200 OK):

{
  "downloadUrl": "https://storage.example.com/files/documents/contract-2024.pdf?signature=...",
  "downloadUrlExpiresAt": "2024-01-15T12:30:00Z"
}

Pre-signed URL can be used without authentication until it expires

GET

List Files in Category

/api/v1/files/{category}

Get all files in a specific category with pagination and sorting

Query Parameters:

limit

optional

- Items per page (1-1000, default: 100)

offset

optional

- Number of items to skip (default: 0)

prefix

optional

- Filter files by key prefix

sortBy

optional

- Sort field: key, createdAt, updatedAt, size (default: createdAt)

sortOrder

optional

- Sort order: asc, desc (default: asc)

aggregate

optional

- If true, returns full object with pagination metadata

Response (200 OK) - Default Array:

[
  {
    "category": "documents",
    "key": "invoice-123.pdf",
    "fileName": "invoice-123.pdf",
    "contentType": "application/pdf",
    "size": 1048576,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T14:20:00Z",
    "expiresAt": null
  }
]

Response (aggregate=true):

{
  "category": "documents",
  "items": [...],
  "totalCount": 250,
  "page": 1,
  "pageSize": 100,
  "totalPages": 3
}

Response headers: X-Category, X-Total-Count, X-Page, X-Limit, X-Total-Pages

DELETE

Delete File

/api/v1/files/{category}/{key}

Remove a file from storage permanently

Response (200 OK):

{
  "category": "documents",
  "key": "invoice-123.pdf"
}

Example Usage

cURL Examples

Upload with auto-generated key

curl -X POST "https://api.ainoflow.io/api/v1/files/documents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@contract.pdf"

Upload from external URL

curl -X POST "https://api.ainoflow.io/api/v1/files/images/logo.png" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "sourceUrl=https://cdn.example.com/assets/logo.png"

Upload with expiration

curl -X POST "https://api.ainoflow.io/api/v1/files/temp" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@session-data.json" \
  -F "expiresAt=2024-01-16T10:30:00Z"

Get pre-signed URL

curl "https://api.ainoflow.io/api/v1/files/documents/report.pdf/url?expirySeconds=7200" \
  -H "Authorization: Bearer YOUR_API_KEY"

List files sorted by size

curl "https://api.ainoflow.io/api/v1/files/documents?sortBy=size&sortOrder=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Download a file

curl "https://api.ainoflow.io/api/v1/files/documents/invoice-123.pdf" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o downloaded-invoice.pdf

Delete a file

curl -X DELETE "https://api.ainoflow.io/api/v1/files/documents/invoice-123.pdf" \
  -H "Authorization: Bearer YOUR_API_KEY"

Common Error Codes

400

Bad Request - Invalid file upload or parameter validation failed

401

Unauthorized - Missing or invalid API key

404

Not Found - File not found, deleted, or expired

409

Conflict - File already exists (POST only, use PUT to overwrite)

413

Payload Too Large - File exceeds 100MB size limit

429

Too Many Requests - Rate limit or storage limit exceeded

500

Internal Server Error - Storage operation failed

Ready to Get Started?

Create your free account and get your API key in minutes.

Get API Key Learn More

Files API Documentation

Documents

Images

Archives

Media

Data

Other

Main Endpoints

Response (200 OK):

Path Parameters:

Request Body (multipart/form-data):

Direct File Upload:

URL-based Upload:

Response (201 Created):

Path Parameters:

Request Body (multipart/form-data):

Request:

Response (201 Created):

Path Parameters:

Request Body (multipart/form-data):

Request:

Response:

Query Parameters:

Request:

Response Headers:

Response (200 OK):

Response Headers:

Query Parameters:

Request:

Response (200 OK):

Query Parameters:

Response (200 OK) - Default Array:

Response (aggregate=true):

Response (200 OK):

Example Usage

Upload with auto-generated key

Upload from external URL

Upload with expiration

Get pre-signed URL

List files sorted by size

Download a file

Delete a file

Common Error Codes

Ready to Get Started?