API Overview

The Tuzzle API is a RESTful JSON API split into two tiers: the Upload API for high-throughput file uploads, and the Admin API for managing spaces, files, folders, and configurations.

Base URL

https://api.tzzl.io/api/v1

All endpoints are prefixed with /api/v1/.

API Tiers

Upload API

High-throughput endpoints for uploading and delivering files. These are the hot path, designed for frequent production use.

Admin API

Management endpoints for configuring spaces, querying files, and managing resources. Called less frequently, used for setup, configuration, and asset management.

Authentication

Both API tiers accept the same authentication methods. Include a space-scoped API key as a Bearer token in the Authorization header:

Authorization: Bearer sk_a1b2c3d4...

API keys can also be passed as a query parameter:

https://api.tzzl.io/api/v1/files?api_key=sk_a1b2c3d4...

You can create and manage API keys from the Tuzzle dashboard. See API Keys for details.

Request Format

• Content-Type: application/json for JSON bodies, multipart/form-data for file uploads
• Method: Standard HTTP methods (GET, POST, PUT, DELETE)

Response Format

All responses return JSON. Successful responses wrap data in a data key:

{
  "data": { ... }
}

List responses include pagination metadata:

{
  "data": [ ... ],
  "path": "/api/v1/files",
  "per_page": 20,
  "next_cursor": "eyJpZCI6...",
  "prev_cursor": null
}

Pagination

The API uses cursor-based pagination. Use the next_cursor value to fetch the next page:

GET /api/v1/files?space_id=SPACE_ID&limit=20&cursor=eyJpZCI6...

IDs

All resource IDs use ULIDs, which are sortable, unique identifiers:

01HQ3KBVZ1MXYZ9ABC2DEF3GH4

Rate Limiting

Each API tier has its own rate limit profile:

When rate-limited, the API returns 429 Too Many Requests with a Retry-After header.

Error Responses

Errors return appropriate HTTP status codes with a JSON body:

{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."]
  }
}

See the Errors page for a complete list of error codes.