> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sigmic.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Artifacts

> List and download files generated by a task

# Artifacts

Retrieve files generated in a task's workspace. This includes uploaded files, generated outputs, and any files created by the agent during execution.

## List Artifacts

```bash theme={null}
GET /api/v1/tasks/{id}/artifacts
Authorization: Bearer {api_key}
```

### Path Parameters

| Parameter | Type   | Description                |
| --------- | ------ | -------------------------- |
| `id`      | string | The unique task identifier |

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "files": [
      {
        "name": "output.csv",
        "path": "downloads/output.csv",
        "size": 1024,
        "mimeType": "text/csv",
        "category": "csv",
        "modifiedAt": "2026-01-26T16:00:00.000Z"
      },
      {
        "name": "report.pdf",
        "path": "downloads/report.pdf",
        "size": 50432,
        "mimeType": "application/pdf",
        "category": "pdf",
        "modifiedAt": "2026-01-26T16:01:00.000Z"
      },
      {
        "name": "data.csv",
        "path": "uploads/data.csv",
        "size": 2048,
        "mimeType": "text/csv",
        "category": "csv",
        "modifiedAt": "2026-01-26T15:50:00.000Z"
      }
    ]
  }
}
```

### File Object

| Field        | Type   | Description                                         |
| ------------ | ------ | --------------------------------------------------- |
| `name`       | string | Filename                                            |
| `path`       | string | Relative path in workspace                          |
| `size`       | number | File size in bytes                                  |
| `mimeType`   | string | MIME type (e.g., `text/csv`, `application/pdf`)     |
| `category`   | string | File category (e.g., `csv`, `pdf`, `image`, `code`) |
| `modifiedAt` | string | ISO timestamp of last modification                  |

<Note>
  This endpoint works for both active sessions and completed tasks. When a session has expired, files are retrieved from the preserved workspace.
</Note>

### Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -s https://api.sigmic.ai/api/v1/tasks/YOUR_TASK_ID/artifacts \
    -H "Authorization: Bearer sigmic_your_key_here" | jq
  ```

  ```javascript JavaScript theme={null}
  const taskId = 'c37c1d78-4d23-4e53-949a-ddd775f25e01';

  const response = await fetch(
    `https://api.sigmic.ai/api/v1/tasks/${taskId}/artifacts`,
    { headers: { 'Authorization': 'Bearer sigmic_your_key_here' } }
  );

  const { data } = await response.json();
  console.log(`Found ${data.files.length} files:`);
  data.files.forEach(f => console.log(`  ${f.name} (${f.size} bytes)`));
  ```

  ```python Python theme={null}
  import requests

  task_id = 'c37c1d78-4d23-4e53-949a-ddd775f25e01'

  response = requests.get(
      f'https://api.sigmic.ai/api/v1/tasks/{task_id}/artifacts',
      headers={'Authorization': 'Bearer sigmic_your_key_here'}
  )

  files = response.json()['data']['files']
  for f in files:
      print(f"{f['name']} ({f['size']} bytes) - {f['mimeType']}")
  ```
</CodeGroup>

***

## Download Artifact

Download a specific file from the task's workspace.

```bash theme={null}
GET /api/v1/tasks/{id}/artifacts/download?path={filePath}
Authorization: Bearer {api_key}
```

### Path Parameters

| Parameter | Type   | Description                |
| --------- | ------ | -------------------------- |
| `id`      | string | The unique task identifier |

### Query Parameters

| Parameter | Type   | Required | Description                                     |
| --------- | ------ | -------- | ----------------------------------------------- |
| `path`    | string | Yes      | Relative file path (from the artifacts listing) |

### Response

Binary file content with the following headers:

| Header                | Description                         |
| --------------------- | ----------------------------------- |
| `Content-Type`        | MIME type of the file               |
| `Content-Disposition` | `attachment; filename="output.csv"` |
| `Content-Length`      | File size in bytes                  |

### Examples

<CodeGroup>
  ```bash cURL theme={null}
  # Download to current directory
  curl -O https://api.sigmic.ai/api/v1/tasks/YOUR_TASK_ID/artifacts/download?path=downloads/output.csv \
    -H "Authorization: Bearer sigmic_your_key_here"

  # Save with custom filename
  curl -o my-report.pdf https://api.sigmic.ai/api/v1/tasks/YOUR_TASK_ID/artifacts/download?path=downloads/report.pdf \
    -H "Authorization: Bearer sigmic_your_key_here"
  ```

  ```javascript JavaScript theme={null}
  const taskId = 'c37c1d78-4d23-4e53-949a-ddd775f25e01';
  const filePath = 'downloads/output.csv';

  const response = await fetch(
    `https://api.sigmic.ai/api/v1/tasks/${taskId}/artifacts/download?path=${encodeURIComponent(filePath)}`,
    { headers: { 'Authorization': 'Bearer sigmic_your_key_here' } }
  );

  // Save as file (Node.js)
  const buffer = await response.arrayBuffer();
  const fs = await import('fs');
  fs.writeFileSync('output.csv', Buffer.from(buffer));

  // Or create a download link (browser)
  const blob = await response.blob();
  const url = URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = 'output.csv';
  a.click();
  ```

  ```python Python theme={null}
  import requests

  task_id = 'c37c1d78-4d23-4e53-949a-ddd775f25e01'
  file_path = 'downloads/output.csv'

  response = requests.get(
      f'https://api.sigmic.ai/api/v1/tasks/{task_id}/artifacts/download',
      headers={'Authorization': 'Bearer sigmic_your_key_here'},
      params={'path': file_path}
  )

  with open('output.csv', 'wb') as f:
      f.write(response.content)

  print(f'Downloaded {len(response.content)} bytes')
  ```
</CodeGroup>

## Use Cases

<CardGroup cols={2}>
  <Card title="Download Reports" icon="file-export">
    Retrieve generated reports, analysis results, or data exports
  </Card>

  <Card title="Access Uploaded Files" icon="upload">
    Download files that were uploaded with the task for verification
  </Card>

  <Card title="Build File Browsers" icon="folder-open">
    List workspace contents and let users browse generated artifacts
  </Card>

  <Card title="Pipeline Integration" icon="gears">
    Automatically retrieve output files as part of an automation pipeline
  </Card>
</CardGroup>

## Errors

| Code               | Description                                        |
| ------------------ | -------------------------------------------------- |
| `AUTH_REQUIRED`    | No authentication provided                         |
| `INVALID_API_KEY`  | Invalid or expired API key                         |
| `NOT_FOUND`        | Task or file not found                             |
| `VALIDATION_ERROR` | Missing `path` query parameter (download endpoint) |