API Documentation

Base URL

https://attach.fast/api

GET /api/files

Retrieve a paginated list of site files ordered by creation date (newest first).

Query Parameters

Parameter	Type	Description	Default
page	integer	Page number	1
per_page	integer	Items per page (max 100)	10

Response

{
  "files": [
    {
      "id": 123,
      "token": "my-image.png",
      "filename": "my-image.png",
      "content_type": "image/png",
      "file_size": 524288,
      "url": "https://...",
      "download_url": "https://...",
      "folder": {
        "id": 456,
        "name": "avatars"
      },
      "created_at": "2025-12-30T16:18:00Z",
      "updated_at": "2025-12-30T16:18:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total_count": 45,
    "total_pages": 5
  }
}

GET /api/files/:id

Retrieve details for a specific file.

Response

{
  "id": 123,
  "token": "my-image.png",
  "filename": "my-image.png",
  "content_type": "image/png",
  "file_size": 524288,
  "url": "https://...",
  "download_url": "https://...",
  "folder": {
    "id": 456,
    "name": "avatars"
  },
  "created_at": "2025-12-30T16:18:00Z",
  "updated_at": "2025-12-30T16:18:00Z"
}

POST /api/files

Upload a new file with automatic folder creation and unique naming.

Request Body (multipart/form-data)

Field	Type	Required	Description
file	file	Yes	The file to upload
folder	string	No	Custom folder path/filename (e.g., "users/avatars/user_1")

File Naming & Folder Structure

Use the folder parameter to organize files:

• "image" - Root level file (extension added automatically)
• "users/avatar" - Creates "users" folder, file named "avatar.ext"
• "docs/reports/quarterly" - Creates nested folders "docs" → "reports"

Response (201 Created)

{
  "id": 124,
  "token": "users/avatar.png",
  "filename": "avatar.png",
  "content_type": "image/png",
  "file_size": 45678,
  "url": "https://...",
  "download_url": "https://...",
  "folder": {
    "id": 457,
    "name": "users"
  },
  "created_at": "2025-12-30T16:20:00Z",
  "updated_at": "2025-12-30T16:20:00Z"
}

PATCH /api/files/:id

Update the file's token (filename/path).

Request Body (JSON)

{
  "site_file": {
    "token": "new-filename.png"
  }
}

Response

Returns the updated file object with new token.

DELETE /api/files/:id

Permanently delete a file and its data from storage.

Response

204 No Content on successful deletion.

POST /api/large_files

Upload file chunks sequentially. The server assembles chunks and creates the final file when all chunks are received.

Upload Flow

1. Split your large file into chunks (recommended: 5MB each)
2. Upload each chunk with the same unique key
3. Server tracks progress and assembles file when complete
4. Final file is created and uploaded to storage

Request Body (multipart/form-data)

Field	Type	Required	Description
file	file	Yes	The chunk data
chunk	integer	Yes	Chunk number (1, 2, 3, etc.)
total_size	integer	Yes	Total size of original file in bytes
key	string	Yes	Unique identifier for this upload (must be same for all chunks)
folder	string	No	Target folder path (e.g., "videos/2025")

Response - Chunk Received (202 Accepted)

{
  "message": "Chunk received successfully",
  "status": "pending",
  "received_size": 10485760,
  "total_size": 52428800
}

Response - Upload Complete (201 Created)

{
  "message": "File upload completed successfully",
  "status": "complete"
}

Error Responses

// Missing required parameters (422 Unprocessable Entity)
{
  "errors": ["Missing chunk number"]
}

// Server error during assembly (500 Internal Server Error)
{
  "errors": ["Failed to create final file: [error details]"]
}

JavaScript Chunked Upload

async function uploadLargeFile(file, apiKey, options = {}) {
  const chunkSize = options.chunkSize || 5 * 1024 * 1024; // 5MB
  const uniqueKey = options.key || `${file.name}_${Date.now()}`;
  const folder = options.folder;
  
  const totalChunks = Math.ceil(file.size / chunkSize);
  
  for (let chunkNumber = 1; chunkNumber <= totalChunks; chunkNumber++) {
    const start = (chunkNumber - 1) * chunkSize;
    const end = Math.min(start + chunkSize, file.size);
    const chunk = file.slice(start, end);
    
    const formData = new FormData();
    formData.append('file', chunk);
    formData.append('chunk', chunkNumber.toString());
    formData.append('total_size', file.size.toString());
    formData.append('key', uniqueKey);
    if (folder) formData.append('folder', folder);
    
    const response = await fetch('/api/large_files', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`
      },
      body: formData
    });
    
    const result = await response.json();
    
    if (!response.ok) {
      throw new Error(result.errors.join(', '));
    }
    
    console.log(`Chunk ${chunkNumber}/${totalChunks} uploaded`);
    
    // Check if upload is complete
    if (result.status === 'complete') {
      console.log('Upload completed successfully!');
      return result;
    }
  }
}

cURL Example - Single Chunk

# Upload chunk 1 of 3
curl -X POST https://attach.fast/api/large_files \
  -H "Authorization: Bearer your-site-api-key" \
  -F "file=@chunk_001" \
  -F "chunk=1" \
  -F "total_size=52428800" \
  -F "key=my_video_2025.mp4" \
  -F "folder=videos/uploads"

Python Example

import requests
import os

def upload_large_file(file_path, api_key, chunk_size=5*1024*1024):
    file_size = os.path.getsize(file_path)
    file_name = os.path.basename(file_path)
    unique_key = f"{file_name}_{int(time.time())}"
    
    with open(file_path, 'rb') as f:
        chunk_number = 1
        
        while True:
            chunk = f.read(chunk_size)
            if not chunk:
                break
                
            files = {'file': chunk}
            data = {
                'chunk': chunk_number,
                'total_size': file_size,
                'key': unique_key,
                'folder': 'uploads'
            }
            
            response = requests.post(
                'https://attach.fast/api/large_files',
                headers={'Authorization': f'Bearer {api_key}'},
                files=files,
                data=data
            )
            
            result = response.json()
            
            if not response.ok:
                raise Exception(f"Upload failed: {result['errors']}")
                
            print(f"Chunk {chunk_number} uploaded")
            
            if result['status'] == 'complete':
                print("Upload completed!")
                return result
                
            chunk_number += 1

Chunk Size Recommendations

• 5MB chunks - Good default for most use cases
• 1-2MB chunks - For slower connections
• 10MB chunks - For very fast connections and large files
• Maximum: 100MB per chunk

Retry Logic

async function uploadChunkWithRetry(chunk, chunkNumber, totalSize, key, apiKey, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const result = await uploadChunk(chunk, chunkNumber, totalSize, key, apiKey);
      return result;
    } catch (error) {
      if (attempt === maxRetries) {
        throw error;
      }
      console.log(`Chunk ${chunkNumber} failed, retrying (${attempt}/${maxRetries})`);
      await new Promise(resolve => setTimeout(resolve, 1000 * attempt)); // Exponential backoff
    }
  }
}

Progress Tracking

function trackProgress(receivedSize, totalSize) {
  const percentage = (receivedSize / totalSize * 100).toFixed(1);
  const receivedMB = (receivedSize / 1024 / 1024).toFixed(1);
  const totalMB = (totalSize / 1024 / 1024).toFixed(1);
  
  console.log(`Progress: ${percentage}% (${receivedMB}MB / ${totalMB}MB)`);
  
  // Update UI progress bar
  updateProgressBar(percentage);
}

Scenario	Recommended API	Reason
Files under 5MB	/api/files	Simpler, single request upload
Files over 5MB	/api/large_files	Better performance, progress tracking, resumability
Slow/unreliable connections	/api/large_files	Retry individual chunks instead of entire file
Need progress tracking	/api/large_files	Built-in progress reporting

GET /api/folders

Retrieve folders with filtering and pagination, ordered by name.

Query Parameters

Parameter	Type	Description	Example
parent_id	integer	Get children of specific folder	?parent_id=123
root	boolean	Get only root-level folders	?root=true
page	integer	Page number (default: 1)	?page=2
per_page	integer	Items per page (max 100, default: 10)	?per_page=25

Response

{
  "folders": [
    {
      "id": 456,
      "name": "avatars",
      "parent_id": 123,
      "parent": {
        "id": 123,
        "name": "users"
      },
      "children_count": 2,
      "files_count": 15,
      "path": ["users", "avatars"],
      "created_at": "2025-12-30T16:00:00Z",
      "updated_at": "2025-12-30T16:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total_count": 8,
    "total_pages": 1
  }
}

GET /api/folders/:id

Retrieve a specific folder with its children and files.

Response

{
  "id": 456,
  "name": "avatars",
  "parent_id": 123,
  "parent": {
    "id": 123,
    "name": "users"
  },
  "children_count": 2,
  "files_count": 15,
  "path": ["users", "avatars"],
  "children": [
    {
      "id": 789,
      "name": "thumbnails",
      "parent_id": 456,
      "children_count": 0,
      "files_count": 5
    }
  ],
  "files": [
    {
      "id": 101,
      "token": "user_1.png",
      "filename": "user_1.png"
    }
  ],
  "created_at": "2025-12-30T16:00:00Z",
  "updated_at": "2025-12-30T16:00:00Z"
}

GET /api/folders/tree

Get complete hierarchical folder structure starting from root folders.

Response

{
  "tree": [
    {
      "id": 123,
      "name": "users",
      "files_count": 5,
      "children": [
        {
          "id": 456,
          "name": "avatars",
          "files_count": 15,
          "children": [
            {
              "id": 789,
              "name": "thumbnails", 
              "files_count": 5,
              "children": []
            }
          ]
        }
      ]
    },
    {
      "id": 124,
      "name": "documents",
      "files_count": 8,
      "children": []
    }
  ]
}

POST /api/folders

Create a new folder at root level or under an existing parent.

Request Body (JSON)

{
  "site_folder": {
    "name": "new-folder",
    "parent_id": 123
  }
}

Omit parent_id to create a root-level folder.

Response (201 Created)

{
  "id": 457,
  "name": "new-folder",
  "parent_id": 123,
  "parent": {
    "id": 123,
    "name": "users"
  },
  "children_count": 0,
  "files_count": 0,
  "path": ["users", "new-folder"],
  "created_at": "2025-12-30T16:25:00Z",
  "updated_at": "2025-12-30T16:25:00Z"
}

PATCH /api/folders/:id

Update folder name or move to different parent.

Request Body (JSON)

{
  "site_folder": {
    "name": "renamed-folder",
    "parent_id": 124
  }
}

Response

Returns the updated folder object.

DELETE /api/folders/:id

Delete an empty folder (no subfolders or files).

Error Responses

// 422 Unprocessable Entity
{
  "errors": ["Cannot delete folder with subfolders"]
}

// or
{
  "errors": ["Cannot delete folder containing files"]
}

Success Response

204 No Content on successful deletion.

Upload a file with folder structure

curl -X POST https://attach.fast/api/files \
  -H "Authorization: Bearer your-site-api-key" \
  -F "file=@/path/to/image.png" \
  -F "folder=users/avatars/user_1"

Upload file to root level

curl -X POST https://attach.fast/api/files \
  -H "Authorization: Bearer your-site-api-key" \
  -F "file=@/path/to/document.pdf"

List files with pagination

curl -X GET "https://attach.fast/api/files?page=1&per_page=20" \
  -H "Authorization: Bearer your-site-api-key"

Get specific file details

curl -X GET https://attach.fast/api/files/123 \
  -H "Authorization: Bearer your-site-api-key"

Create a folder

curl -X POST https://attach.fast/api/folders \
  -H "Authorization: Bearer your-site-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "site_folder": {
      "name": "new-folder",
      "parent_id": 123
    }
  }'

Get folder tree structure

curl -X GET https://attach.fast/api/folders/tree \
  -H "Authorization: Bearer your-site-api-key"

List root folders only

curl -X GET "https://attach.fast/api/folders?root=true" \
  -H "Authorization: Bearer your-site-api-key"

Delete a file

curl -X DELETE https://attach.fast/api/files/123 \
  -H "Authorization: Bearer your-site-api-key"

Upload a file with error handling

async function uploadFile(file, folder = null) {
  const formData = new FormData();
  formData.append('file', file);
  if (folder) formData.append('folder', folder);

  try {
    const response = await fetch('/api/files', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer your-site-api-key'
      },
      body: formData
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.errors.join(', '));
    }

    return await response.json();
  } catch (error) {
    console.error('Upload failed:', error.message);
    throw error;
  }
}

Fetch files with pagination

async function fetchFiles(page = 1, perPage = 10) {
  const response = await fetch(`/api/files?page=${page}&per_page=${perPage}`, {
    headers: {
      'Authorization': 'Bearer your-site-api-key'
    }
  });
  
  return await response.json();
}

Create folder hierarchy

async function createFolder(name, parentId = null) {
  const response = await fetch('/api/folders', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your-site-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      site_folder: {
        name: name,
        parent_id: parentId
      }
    })
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.errors.join(', '));
  }

  return await response.json();
}

Get complete folder tree

async function getFolderTree() {
  const response = await fetch('/api/folders/tree', {
    headers: {
      'Authorization': 'Bearer your-site-api-key'
    }
  });
  
  const data = await response.json();
  return data.tree;
}

import React, { useState } from 'react';

function FileUpload({ apiKey, onSuccess, onError }) {
  const [uploading, setUploading] = useState(false);
  const [folder, setFolder] = useState('');

  const handleUpload = async (e) => {
    const file = e.target.files[0];
    if (!file) return;

    setUploading(true);
    
    try {
      const formData = new FormData();
      formData.append('file', file);
      if (folder) formData.append('folder', folder);

      const response = await fetch('/api/files', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${apiKey}`
        },
        body: formData
      });

      if (!response.ok) {
        const error = await response.json();
        throw new Error(error.errors.join(', '));
      }

      const result = await response.json();
      onSuccess(result);
      setFolder(''); // Reset folder input
    } catch (error) {
      onError(error.message);
    } finally {
      setUploading(false);
    }
  };

  return (
    <div>
      <input 
        type="text" 
        placeholder="Optional: folder/path/filename"
        value={folder}
        onChange={(e) => setFolder(e.target.value)}
      />
      <input 
        type="file" 
        onChange={handleUpload}
        disabled={uploading}
      />
      {uploading && <p>Uploading...</p>}
    </div>
  );
}

HTTP Status Codes

Code	Meaning	When Used
200	OK	Successful GET, PATCH requests
201	Created	Successful file upload, folder creation
204	No Content	Successful deletion
400	Bad Request	Malformed request parameters
401	Unauthorized	Invalid or missing API key
404	Not Found	File, folder, or endpoint not found
422	Unprocessable Entity	Validation errors, business logic violations

Standard Error Response Format

{
  "errors": [
    "File is required",
    "Token has already been taken"
  ]
}

File Upload Errors (422 Unprocessable Entity)

// Missing file
{
  "errors": ["File is required"]
}

// Duplicate token (if token conflicts)
{
  "errors": ["Token has already been taken"]
}

// Invalid file type (if validation exists)
{
  "errors": ["File type not allowed"]
}

Folder Deletion Errors (422 Unprocessable Entity)

// Folder contains subfolders
{
  "errors": ["Cannot delete folder with subfolders"]
}

// Folder contains files
{
  "errors": ["Cannot delete folder containing files"]
}

Authentication Errors (401 Unauthorized)

// Missing Authorization header
{
  "errors": ["Authorization required"]
}

// Invalid API key
{
  "errors": ["Invalid API key"]
}

Resource Not Found (404 Not Found)

// File or folder doesn't exist
{
  "errors": ["Record not found"]
}