Files API
Access and delete files uploaded with form submissions. These endpoints require a project API key (fep_...).
Get a File
GET /api/v1/files/{id}Returns the file's metadata and a signed download URL that expires after one hour.
Example Request
curl "https://atlasforms.app/api/v1/files/file-uuid" \
-H "Authorization: Bearer fep_your_api_key"Response
{
"data": {
"id": "file-uuid",
"filename": "document.pdf",
"mime_type": "application/pdf",
"size_bytes": 102400,
"category": "document",
"url": "https://...",
"expires_in": 3600
}
}Response Fields
| Field | Description |
|---|---|
id | Unique file ID |
filename | Original name of the uploaded file |
mime_type | MIME type (e.g., image/jpeg) |
size_bytes | Size in bytes |
category | image, video, document, or other |
url | Signed URL to download the file |
expires_in | Seconds until url expires (3600) |
To download the file, fetch url:
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:
GET /api/v1/files/{id}?variant=thumbnail| Variant | Description |
|---|---|
public | Default |
thumbnail | Small preview |
medium | Medium size |
large | Large size |
Arbitrary dimensions, cropping, quality, and format conversion are not supported.
Delete a File
DELETE /api/v1/files/{id}Deletes the file from storage.
{ "success": true, "deleted_id": "file-uuid" }Files in a Submission
GET /api/v1/submissions/{id} includes the submission's file metadata:
curl "https://atlasforms.app/api/v1/submissions/submission-uuid" \
-H "Authorization: Bearer fep_your_api_key"{
"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
{ "error": "File upload incomplete" }401 Unauthorized
{ "error": "Invalid API key" }404 Not Found
Returned for unknown files and for files that belong to another project.
{ "error": "File not found" }429 Rate Limited
{ "error": "Rate limit exceeded" }Webhooks with Files
When submissions include files, the webhook payload contains file metadata:
{
"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:
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);
});