Documentation Menu

File uploads and downloads

Upload a file

POST /channels/{id}/files/upload

Requires authentication.

Upload a file to a channel. The file is stored on the server and a file object is returned with an ID that can be referenced when sending a message. Maximum file size and allowed types are configured server-side.

Parameters

Name In Type Description
id path string Channel ID

Request body

Content type: multipart/form-data

Field Type Required Description
file file yes -

Responses

200 File uploaded

{
  "file": {
    "id": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
    "filename": "report.pdf",
    "size": 1048576,
    "content_type": "application/pdf"
  }
}

400 Bad request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters"
  }
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

403 Forbidden

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "You do not have permission to perform this action"
  }
}

404 Not found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

Download a file

GET /files/{id}/download

Download a file by ID. Supports both authenticated requests (Bearer token) and signed URLs (with expires, uid, and sig query parameters) for sharing files externally.

Parameters

Name In Type Description
id path string -
expires query integer Unix timestamp when the signed URL expires
uid query string User ID for signed URL verification
sig query string HMAC-SHA256 signature for signed URL verification

Responses

  • 200 File content — binary file content 401 Unauthorized
{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

403 Forbidden

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "You do not have permission to perform this action"
  }
}

404 Not found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

Get a signed download URL for a file

POST /files/{id}/sign-url

Requires authentication.

Generate a time-limited signed URL for downloading a file without authentication. Useful for embedding file links in emails or sharing with external users.

Parameters

Name In Type Description
id path string -

Responses

200 Signed URL

{
  "file_id": "01JQ3KMT6BMRXP0WCDG9HQSYNF",
  "url": "/files/01JQ3KMT6B/download?sig=abc",
  "expires_at": "2025-01-15T09:30:00Z"
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

403 Forbidden

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "You do not have permission to perform this action"
  }
}

404 Not found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

Get signed download URLs for multiple files

POST /files/sign-urls

Requires authentication.

Generate signed download URLs for multiple files in a single request. More efficient than calling the single-file endpoint repeatedly.

Request body 

{
  "file_ids": [
    "string"
  ]
}

Responses

200 Signed URLs

{
  "urls": [
    {
      "file_id": "01JQ3KMT6BMRXP0WCDG9HQSYNF",
      "url": "/files/01JQ3KMT6B/download?sig=abc",
      "expires_at": "2025-01-15T09:30:00Z"
    }
  ]
}

400 Bad request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters"
  }
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

Delete a file

POST /files/{id}/delete

Requires authentication.

Delete a file from the server. Only the file uploader or a workspace admin/owner can delete files.

Parameters

Name In Type Description
id path string -

Responses

200 File deleted

{
  "success": true
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

403 Forbidden

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "You do not have permission to perform this action"
  }
}

404 Not found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}