API Endpoints

Complete reference for the FileChute REST API. All endpoints require API key authentication and are prefixed with /api/v1.

File Requests

List requests

GET /api/v1/requests

Returns all file requests for the authenticated user. Supports pagination with ?page=1&limit=20.

Get a request

GET /api/v1/requests/:id

Returns a single file request with its checklist items and upload status.

Create a request

POST /api/v1/requests

{
  "title": "2025 Tax Documents",
  "recipientEmail": "client@example.com",
  "dueDate": "2025-04-15",
  "checklistItems": [
    { "label": "W-2 Forms", "description": "From all employers" },
    { "label": "1099 Statements" }
  ]
}

Creates a new file request and optionally sends an email to the recipient.

Close a request

PATCH /api/v1/requests/:id/close

Closes the request, preventing further uploads.

Uploads

List uploads for a request

GET /api/v1/requests/:id/uploads

Returns all uploaded files for a request, including file name, size, content type, and download URL.

Download a file

GET /api/v1/uploads/:uploadId/download

Returns a signed download URL valid for 5 minutes.

Clients

List clients

GET /api/v1/clients

Returns all clients for the authenticated user.

Create a client

POST /api/v1/clients

{
  "name": "Jane Smith",
  "email": "jane@example.com",
  "company": "Smith & Associates"
}

Webhooks

List webhooks

GET /api/v1/webhooks

Create a webhook

POST /api/v1/webhooks

{
  "url": "https://your-app.com/webhook",
  "events": ["file.uploaded", "request.completed"]
}

Webhook payloads are signed with HMAC-SHA256. The signature is included in the X-FileChute-Signature header.

Response format

All responses are JSON. Successful responses include the data directly:

{
  "id": "abc-123",
  "title": "Tax Documents",
  "status": "active",
  ...
}

Error responses include an error field:

{
  "error": "Request not found"
}

Status codes

• 200 — Success
• 201 — Created
• 400 — Bad request (invalid input)
• 401 — Unauthorized (missing or invalid API key)
• 404 — Not found
• 429 — Rate limited
• 500 — Server error