File Endpoints

Complete API reference for file management endpoints.

File endpoints are part of the Admin API tier. All endpoints are under /api/v1/files and require API key authentication.

GET /files

List files in a space with cursor pagination.

curl "https://api.tzzl.io/api/v1/files?space_id=SPACE_ID&limit=20" \
  -H "Authorization: Bearer sk_a1b2c3d4..."

Query Parameters:

Parameter	Required	Description
`space_id`	Yes	Space to list files from
`limit`	No	Items per page
`cursor`	No	Pagination cursor

GET /files/:id

Get a single file by ID.

curl https://api.tzzl.io/api/v1/files/FILE_ID \
  -H "Authorization: Bearer sk_a1b2c3d4..."

Response:

{
  "data": {
    "id": "01HQ...",
    "name": "image-01HQ...",
    "original_name": "photo.jpg",
    "mime_type": "image/jpeg",
    "size": 245000,
    "storage_path": "a1b2c3/image-01HQ...",
    "type": "upload",
    "resource_type": "image",
    "status": "active",
    "extension": "jpg",
    "public_id": null,
    "ref": null,
    "folder_path": null,
    "storage_meta": {
      "width": 1920,
      "height": 1080,
      "blur_hash": "LEHV6nWB2yk8...",
      "face_detections": []
    }
  }
}

GET /files/by-ref

Look up a file by its custom reference.

curl "https://api.tzzl.io/api/v1/files/by-ref?space_id=SPACE_ID&ref=my-custom-ref" \
  -H "Authorization: Bearer sk_a1b2c3d4..."

Query Parameters:

Parameter	Required	Description
`space_id`	Yes	Space to search in
`ref`	Yes	Custom reference string

PUT /files

Update a file's properties.

curl -X PUT https://api.tzzl.io/api/v1/files \
  -H "Authorization: Bearer sk_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "id": "01HQ...",
    "original_name": "renamed.jpg"
  }'

Parameters:

Field	Type	Required	Validation
`id`	string	Yes	Must exist
`name`	string	No	Max 255
`original_name`	string	No	Max 255
`mime_type`	string	No	Max 255
`size`	integer	No	Min 1
`storage_path`	string	No	Max 255
`space`	string	No	Must be valid space handle
`folder_path`	string	No	Must be valid folder path
`folder_id`	string	No	Must be valid folder ID

DELETE /files/:id

Delete a file and all its transformed variants.

curl -X DELETE https://api.tzzl.io/api/v1/files/FILE_ID \
  -H "Authorization: Bearer sk_a1b2c3d4..."

Removes the file from the database, cloud storage, and all cached transformed variants.

PUT /files/:id/access-control

Update file-level access control.

curl -X PUT https://api.tzzl.io/api/v1/files/FILE_ID/access-control \
  -H "Authorization: Bearer sk_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "access_control": {
      "requires_auth": true
    }
  }'

DELETE /files/:id/access-control

Reset file access control to inherited defaults.

curl -X DELETE https://api.tzzl.io/api/v1/files/FILE_ID/access-control \
  -H "Authorization: Bearer sk_a1b2c3d4..."

POST /files/:id/signed-url

Generate a signed delivery URL for the file.

curl -X POST https://api.tzzl.io/api/v1/files/FILE_ID/signed-url \
  -H "Authorization: Bearer sk_a1b2c3d4..."

Returns a time-limited CDN URL with HMAC-SHA256 signature. Default expiration: 1 hour.

POST /files/urls

Generate batch URLs for multiple files.

curl -X POST https://api.tzzl.io/api/v1/files/urls \
  -H "Authorization: Bearer sk_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "file_ids": ["01HQ...", "01HR...", "01HS..."]
  }'

GET /files/:id/signed-access

Validate and access a file using a signed URL.

Auth required: No (validated via signed URL parameters)

This endpoint is used for direct file access with a previously generated signed URL.

PreviousSpace Endpoints NextFolder Endpoints