Skip to main content

Documentation Index

Fetch the complete documentation index at: https://archie.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

The REST API exposes a small set of endpoints for moving files in and out of your project. They work against whichever storage backend you’ve configured in App Services → File Manager — Google Cloud Storage, Amazon S3, Azure Blob Storage, Filestack, or the built-in Archie Storage.
MethodEndpointPurpose
POST/api/rest/filesUpload a file
GET/api/rest/filesList uploaded files
GET/api/rest/files/{fileId}Download a file
DELETE/api/rest/files/{fileId}Delete a file

​
Upload a file

Send a multipart/form-data request. Don’t set Content-Type manually — let curl (or your HTTP client) generate the boundary header. 
curl -X POST "https://your-gateway.example.com/gw/api/rest/files" \
  -H "Authorization: Bearer archie_YOUR_API_KEY" \
  -H "X-Project-ID: your-project-id" \
  -F "file=@/path/to/document.pdf" \
  -F "providerType=ARCHIE_STORAGE" \
  -F "filename=document.pdf" \
  -F "contentType=application/pdf"
Form fieldRequiredDescription
fileYesThe file binary.
providerTypeYesThe storage provider to use.
filenameYesDisplay name for the file.
contentTypeYesMIME type — validated against an allowlist.

​
Provider types

ValueBackend
ARCHIE_STORAGEBuilt-in Archie storage
GCSGoogle Cloud Storage
S3Amazon S3
AZUREAzure Blob Storage
FILESTACKFilestack
The provider must be configured in App Services → File Manager before files can be uploaded to it.

​
Response — 201

{
  "data": {
    "fileId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "url": "https://your-gateway.example.com/files?id=encrypted-token"
  }
}
The url is a signed, time-bounded URL. Persist the fileId if you need a stable reference; regenerate fresh URLs at read time when needed.

​
Supported MIME types

The API accepts a broad allowlist by prefix:
CategoryExamples
ImagesAll image/* (jpeg, png, gif, webp, svg+xml, bmp, tiff, avif)
VideoAll video/* (mp4, webm, quicktime)
AudioAll audio/* (mpeg, wav, ogg)
TextAll text/* (plain, csv, html, xml)
Documentsapplication/pdf, application/rtf, MS Office, OpenXML formats
Archivesapplication/zip, application/gzip, application/x-tar
Dataapplication/json, application/xml
Genericapplication/octet-stream
Unsupported types return 422 Unprocessable Entity.

​
List files

curl -X GET "https://your-gateway.example.com/gw/api/rest/files?page=1&pageSize=20" \
  -H "Authorization: Bearer archie_YOUR_API_KEY" \
  -H "X-Project-ID: your-project-id"
ParameterDefaultMax
page1—
pageSize20100
{
  "data": {
    "items": [
      {
        "fileId": "a1b2c3d4-...",
        "filename": "document.pdf",
        "mimetype": "application/pdf",
        "url": "https://your-gateway.example.com/files?id=encrypted-token"
      }
    ],
    "pagination": { "page": 1, "pageSize": 20, "total": 42 }
  }
}

​
Download a file

curl -X GET "https://your-gateway.example.com/gw/api/rest/files/a1b2c3d4-..." \
  -H "Authorization: Bearer archie_YOUR_API_KEY" \
  -H "X-Project-ID: your-project-id" \
  -o downloaded-document.pdf
The response body is the raw file binary. Headers include the original Content-Type, a Content-Disposition with the filename, and a 1-year Cache-Control header.

​
Delete a file

curl -X DELETE "https://your-gateway.example.com/gw/api/rest/files/a1b2c3d4-..." \
  -H "Authorization: Bearer archie_YOUR_API_KEY" \
  -H "X-Project-ID: your-project-id"
Returns 204 No Content on success. The file is removed from the storage provider.

​
Errors

StatusScenario
400Missing required form fields.
404File not found.
413File exceeds the maximum upload size.
422Unsupported MIME type.
For the full error format, see Error handling.

​
Permissions

File-management endpoints obey the same Role-Based Access rules as other endpoints. Configure who can upload, download, and delete in App Services. For finer-grained access (per-record file permissions), reference the file from a Data Model record and govern access via that table’s permissions.

​
FAQ

Upload the file to get a fileId, then store the fileId (and any metadata you care about) on a JSONB or text field on your record. At read time, fetch the record and re-issue the file’s signed URL through the download endpoint.
The upload url is a signed token with an expiry. Don’t persist it — persist the fileId and generate fresh URLs at read time. Downloads of the binary itself are cached for one year by default.
The default upload limit is enforced at the gateway. Exceeding it returns 413 Payload Too Large. For very large files, use a direct-to-storage upload pattern through your provider’s SDK and store only the resulting object key in Archie.
Yes — configure a new provider in File Manager and point new uploads at it. Existing files stay where they were uploaded; migrate them with a script if you want to consolidate.
The reference becomes a broken link. Archie doesn’t enforce referential integrity between records and files — clean up references when you delete files, or add a server-side check before deletion.