File management

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.

Method	Endpoint	Purpose
`POST`	`/api/rest/files`	Upload a file
`GET`	`/api/rest/files`	List 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 field	Required	Description
`file`	Yes	The file binary.
`providerType`	Yes	The storage provider to use.
`filename`	Yes	Display name for the file.
`contentType`	Yes	MIME type — validated against an allowlist.

Provider types

Value	Backend
`ARCHIE_STORAGE`	Built-in Archie storage
`GCS`	Google Cloud Storage
`S3`	Amazon S3
`AZURE`	Azure Blob Storage
`FILESTACK`	Filestack

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:

Category	Examples
Images	All `image/*` (jpeg, png, gif, webp, svg+xml, bmp, tiff, avif)
Video	All `video/*` (mp4, webm, quicktime)
Audio	All `audio/*` (mpeg, wav, ogg)
Text	All `text/*` (plain, csv, html, xml)
Documents	`application/pdf`, `application/rtf`, MS Office, OpenXML formats
Archives	`application/zip`, `application/gzip`, `application/x-tar`
Data	`application/json`, `application/xml`
Generic	`application/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"

Parameter	Default	Max
`page`	1	—
`pageSize`	20	100

{
  "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

Status	Scenario
400	Missing required form fields.
404	File not found.
413	File exceeds the maximum upload size.
422	Unsupported 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

How do I store a file alongside a record?

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.

Are upload URLs cached?

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.

What's the maximum file size?

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.

Can I switch storage providers later?

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.

What happens if I delete a file that's referenced by a record?

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.

Home

Blueprint

Design

Frontend

Backend

Assets

Upload a file

Provider types

Response — 201

Supported MIME types

List files

Download a file

Delete a file

Errors

Permissions

FAQ

​Upload a file

​Provider types

​Response — 201

​Supported MIME types

​List files

​Download a file

​Delete a file

​Errors

​Permissions

​FAQ

Upload a file

Provider types

Response — 201

Supported MIME types

List files

Download a file

Delete a file

Errors

Permissions

FAQ