List Task Files

Endpoint

GET /v2/tasks/{task_id}/files

Authentication

This endpoint requires an OAuth access token. Send it as a bearer token:

Authorization: Bearer your_access_token

Required scope: files:read

This endpoint hangs off /tasks but is gated on files:read, not tasks:read, because it returns file references. A token with only tasks:read gets a 403.

Path Parameters

Parameter	Type	Required	Description
`task_id`	integer	Yes	Unique identifier for the task

Query Parameters

Parameter	Type	Required	Description
`include_attachments`	boolean	No	When `true`, also return task-level and activity-log attachments in the `attachments` field. Defaults to `false`.

Request Example

curl -X GET "https://platform.chamelio.ai/v2/tasks/12345/files?include_attachments=true" \
  -H "Authorization: Bearer your_access_token"

import requests

task_id = 12345

url = f"https://platform.chamelio.ai/v2/tasks/{task_id}/files"
headers = {
    "Authorization": "Bearer your_access_token"
}
params = {
    "include_attachments": True
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

const taskId = 12345;

const response = await fetch(
  `https://platform.chamelio.ai/v2/tasks/${taskId}/files?include_attachments=true`,
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer your_access_token'
    }
  }
);

const data = await response.json();
console.log(data);

Response

Success Response

Status Code: 200 OK

{
  "task_id": 12345,
  "files": [
    {
      "file_id": "document_789",
      "file_name": "acme_contract.pdf",
      "variable_id": "contract_file",
      "created_at": "2025-01-20T10:30:00Z",
      "step_id": "intake_step"
    },
    {
      "file_id": "document_790",
      "file_name": "reviewed_contract.pdf",
      "variable_id": null,
      "created_at": "2025-01-20T10:45:00Z",
      "step_id": "review_step"
    },
    {
      "file_id": "attachment_123",
      "file_name": "insurance_certificate.pdf",
      "variable_id": "insurance_doc",
      "created_at": "2025-01-20T11:00:00Z",
      "step_id": "approval_step"
    }
  ],
  "total_files": 3,
  "attachments": [
    {
      "file_id": "attachment_456",
      "file_name": "email_thread.pdf",
      "variable_id": null,
      "created_at": "2025-01-20T12:00:00Z",
      "step_id": null
    }
  ]
}

Response Fields

Field	Type	Description
`task_id`	integer	ID of the task
`files`	array	List of files associated with the task (maximum 10 files returned)
`total_files`	integer	Total number of files for this task
`attachments`	array	Task-level and activity-log attachments. Only populated when `include_attachments=true`; otherwise an empty array. Each entry uses the same File Object fields below (with `variable_id` and `step_id` always `null`).

File Object Fields

Field	Type	Description
`file_id`	string	Unique file identifier (format: `document_{id}` for documents, `attachment_{id}` for attachments)
`file_name`	string	Name of the file
`variable_id`	string or null	ID of the variable this file is associated with. `null` if the file was generated by a step rather than collected into a variable
`created_at`	string	ISO 8601 timestamp when the file was created/uploaded
`step_id`	string or null	ID of the workflow step that created or collected this file. `null` for task-level attachments

Error Responses

400 Bad Request

Returned when the access token has no user behind it. client_credentials tokens act as the admin who created the application, so this applies only to tokens issued before application creators were recorded.

{
  "detail": "client_credentials tokens are not associated with a user"
}

401 Unauthorized

Returned when the access token is missing, unknown, revoked, or expired, or when an X-API-Key was sent instead of a bearer token. See OAuth error responses.

{
  "detail": "Invalid access token"
}

403 Forbidden

Returned when the token lacks the required scope:

{
  "detail": "Insufficient scope; this endpoint requires: files:read"
}

Or when the user may not access this task:

{
  "detail": "You do not have access to this resource"
}

404 Not Found

Returned when the task does not exist.

{
  "detail": "Not found"
}

429 Too Many Requests

Returned when your organization exceeds its per-minute request limit.

{
  "detail": "Rate limit exceeded"
}

500 Internal Server Error

Returned when the request fails due to a server error.

{
  "detail": "Failed to list task files"
}

Notes

This endpoint returns at most 10 files. If the task has more than 10 files, only the first 10 are returned. Use the total_files count to determine if there are more files.

Use the file_id from this response with the Download File endpoint to retrieve the actual file content.

File IDs are prefixed with document_ for documents and attachment_ for attachments. Ensure you pass the complete file ID including the prefix when downloading files.

Set include_attachments=true to also retrieve task-level and activity-log attachments (such as emailed documents) in the attachments array. These are not tied to a workflow variable or step, so their variable_id and step_id are null.

Use Cases

This endpoint is useful for:

File inventory - List all files involved in a workflow task
Document tracking - Track which documents were uploaded or generated at each step
Bulk download - Retrieve file IDs for downloading all task-related files
Audit trails - Document what files were part of a workflow execution

Overview

API Key Access

OAuth App Access

Webhooks

Endpoint

Authentication

Path Parameters

Query Parameters

Request Example

Response

Success Response

Response Fields

File Object Fields

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

429 Too Many Requests

500 Internal Server Error

Notes

Use Cases

​Endpoint

​Authentication

​Path Parameters

​Query Parameters

​Request Example

​Response

​Success Response

​Response Fields

​File Object Fields

​Error Responses

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​429 Too Many Requests

​500 Internal Server Error

​Notes

​Use Cases

Endpoint

Authentication

Path Parameters

Query Parameters

Request Example

Response

Success Response

Response Fields

File Object Fields

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

429 Too Many Requests

500 Internal Server Error

Notes

Use Cases