Files API

Access and download files uploaded with form submissions.

Get File Info

http

GET /api/v1/files/{id}

Returns metadata about an uploaded file.

Example Request

bash

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

Response

json

{
  "id": "file-uuid",
  "submission_id": "submission-uuid",
  "form_id": "form-uuid",
  "original_filename": "document.pdf",
  "mime_type": "application/pdf",
  "file_size_bytes": 102400,
  "file_category": "document",
  "field_name": "attachment",
  "uploaded_at": "2024-01-15T10:30:00Z",
  "download_url": "https://atlasforms.app/api/v1/files/file-uuid/download?token=xxx"
}

Response Fields

Field	Description
`id`	Unique file ID
`submission_id`	Associated submission
`form_id`	Form that received the file
`original_filename`	Original name of uploaded file
`mime_type`	MIME type (e.g., `image/jpeg`)
`file_size_bytes`	Size in bytes
`file_category`	`image`, `document`, `video`, `other`
`field_name`	Form field name
`uploaded_at`	Upload timestamp
`download_url`	Signed URL to download

Download File

http

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

Downloads the file content. Returns a redirect to a signed URL.

Example Request

bash

curl -L "https://atlasforms.app/api/v1/files/file-uuid/download" \
  -H "Authorization: Bearer fep_your_api_key" \
  -o document.pdf

The -L flag follows the redirect to the actual file.

Image Transformations (Business+)

For image files on Business and Enterprise plans, transform on-the-fly:

http

GET /api/v1/files/{id}/download?w=800&h=600&fit=cover

Parameters

Parameter	Description	Example
`w`	Width in pixels	`800`
`h`	Height in pixels	`600`
`fit`	Resize mode	`cover`, `contain`, `fill`
`q`	Quality (1-100)	`85`
`f`	Output format	`webp`, `jpeg`, `png`

Examples

bash

# Thumbnail (200x200, cropped to cover)
curl "https://atlasforms.app/api/v1/files/{id}/download?w=200&h=200&fit=cover"

# Resize to max 1200px width, WebP format
curl "https://atlasforms.app/api/v1/files/{id}/download?w=1200&f=webp&q=85"

# Specific dimensions, contain mode (no crop)
curl "https://atlasforms.app/api/v1/files/{id}/download?w=800&h=600&fit=contain"

List Files in Submission

Files are included in submission responses:

bash

curl "https://atlasforms.app/api/v1/submissions/submission-uuid" \
  -H "Authorization: Bearer fep_your_api_key"

json

{
  "id": "submission-uuid",
  "data": { ... },
  "files": [
    {
      "id": "file-uuid-1",
      "field": "photo",
      "filename": "profile.jpg",
      "type": "image/jpeg",
      "size": 245000
    },
    {
      "id": "file-uuid-2",
      "field": "resume",
      "filename": "resume.pdf",
      "type": "application/pdf",
      "size": 102400
    }
  ]
}

Access Tokens

Some file URLs include access tokens for direct access:

https://atlasforms.app/api/v1/files/{id}?token=xxx

Access tokens:

Expire after 24 hours

Are single-use for downloads

Don't require API key authentication

This is useful for sharing files with systems that can't pass authentication headers.

Error Responses

401 Unauthorized

json

{ "error": "Invalid API key" }

403 Forbidden

json

{ "error": "Access denied to this file" }

404 Not Found

json

{ "error": "File not found" }

410 Gone

json

{ "error": "File has been deleted" }

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) {
    // Download each file
    const response = await fetch(
      `https://atlasforms.app/api/v1/files/${file.id}/download`,
      {
        headers: { Authorization: `Bearer ${process.env.ATLAS_API_KEY}` },
        redirect: 'follow',
      }
    );

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

  res.sendStatus(200);
});

Projects & Forms Webhooks