A
Atlas
...

Files API

Access and delete files uploaded with form submissions. These endpoints require a project API key (fep_...).

Get a File

http
GET /api/v1/files/{id}

Returns the file's metadata and a signed download URL that expires after one hour.

Example Request

bash
curl "https://atlasforms.app/api/v1/files/file-uuid" \
  -H "Authorization: Bearer fep_your_api_key"

Response

json
{
  "data": {
    "id": "file-uuid",
    "filename": "document.pdf",
    "mime_type": "application/pdf",
    "size_bytes": 102400,
    "category": "document",
    "url": "https://...",
    "expires_in": 3600
  }
}

Response Fields

FieldDescription
idUnique file ID
filenameOriginal name of the uploaded file
mime_typeMIME type (e.g., image/jpeg)
size_bytesSize in bytes
categoryimage, video, document, or other
urlSigned URL to download the file
expires_inSeconds until url expires (3600)

To download the file, fetch url:

bash
curl -o document.pdf "$(curl -s "https://atlasforms.app/api/v1/files/file-uuid" \
  -H "Authorization: Bearer fep_your_api_key" | jq -r .data.url)"

Image Variants (Business)

On the Business plan, uploaded images are stored in Cloudflare Images. Pass variant to get a preset size:

http
GET /api/v1/files/{id}?variant=thumbnail
VariantDescription
publicDefault
thumbnailSmall preview
mediumMedium size
largeLarge size

Arbitrary dimensions, cropping, quality, and format conversion are not supported.


Delete a File

http
DELETE /api/v1/files/{id}

Deletes the file from storage.

json
{ "success": true, "deleted_id": "file-uuid" }

Files in a Submission

GET /api/v1/submissions/{id} includes the submission's file metadata:

bash
curl "https://atlasforms.app/api/v1/submissions/submission-uuid" \
  -H "Authorization: Bearer fep_your_api_key"
json
{
  "data": {
    "id": "submission-uuid",
    "data": { "...": "..." },
    "files": [
      {
        "id": "file-uuid-1",
        "filename": "profile.jpg",
        "mime_type": "image/jpeg",
        "size_bytes": 245000,
        "category": "image"
      }
    ]
  }
}

Use each file's id with GET /api/v1/files/{id} to get a download URL.


Error Responses

400 Bad Request

json
{ "error": "File upload incomplete" }

401 Unauthorized

json
{ "error": "Invalid API key" }

404 Not Found

Returned for unknown files and for files that belong to another project.

json
{ "error": "File not found" }

429 Rate Limited

json
{ "error": "Rate limit exceeded" }

Webhooks with Files

When submissions include files, the webhook payload contains file metadata:

json
{
  "event": "submission.created",
  "submission": {
    "id": "submission-uuid",
    "data": { "...": "..." },
    "files": [
      {
        "id": "file-uuid",
        "field": "attachment",
        "filename": "document.pdf",
        "type": "application/pdf",
        "size": 102400
      }
    ]
  }
}

To download files from your webhook handler:

javascript
app.post('/webhook', async (req, res) => {
  const { submission } = req.body;

  for (const file of submission.files || []) {
    const meta = await fetch(`https://atlasforms.app/api/v1/files/${file.id}`, {
      headers: { Authorization: `Bearer ${process.env.ATLAS_API_KEY}` },
    }).then((r) => r.json());

    const response = await fetch(meta.data.url);
    const buffer = await response.arrayBuffer();
    // Save or process the file...
  }

  res.sendStatus(200);
});