# Download your project documents

This guide shows how your system gets the validated documents of your packaging projects (for example the final artwork PDFs) from the [Project API](/catalog/project/project/openapispecification), to load them into your own tools.

Base URL: `https://apis.traceone.com/project/v2`

## How it works

The Project API doesn't send files or events yet. Your system **polls** it on a schedule, for example every night:

1. List your projects.
2. For each project, find the task that makes the documents available.
3. If that task finished since your last run, download the documents.


You need a client-credentials token for your company: see [Prerequisites](/getting-started/prerequisites) and [Authentication](/getting-started/authentication). It gives access to your company's projects only.

## Step 1: list your projects

```http
GET https://apis.traceone.com/project/v2/projects?Statuses=InProgress,Completed&Skip=0&Take=100
```

- `Statuses`: comma-separated. Values: `Draft`, `Scheduled`, `InProgress`, `Completed`, `OnHold`, `Cancelled`, `Archived`.
- Pages: increase `Skip` by `Take` until a page returns fewer projects than `Take`.
- Keep each project's `id`.


## Step 2: find the task that makes the documents available

```http
GET https://apis.traceone.com/project/v2/projects/{projectId}/workflow
```

The answer lists the project's tasks in `tasks.rows`. Tasks can be nested in `children`, so read the whole tree. For each task:

| Field | Use |
|  --- | --- |
| `id` | The task ID for step 3 |
| `name` | The task name, as set in your project's workflow |
| `taskStatus` | `Completed` or `Approved` when the documents are ready |
| `endDate` | When the task finished |
| `manufacturedItemId`, `packagingComponentId` | The product and the packaging component the task is about |


Which task makes the documents available depends on your workflow. It is usually the last task of the flow. Ask your Trace One project manager for its name.

**Rule:** download when that task is `Completed` or `Approved` and its `endDate` is after your last run.

## Step 3: download the documents

```http
GET https://apis.traceone.com/project/v2/projects/{projectId}/tasks/{taskId}/download-documents
```

- The answer is a **zip** (`application/zip`) with the project's product and packaging documents.
- One folder per product, `<EAN>_<product name>_<supplier>_<project code>`, with one sub-folder per packaging component. Documents of different components never overwrite each other.
- Each document is in its **latest version**. You don't need to compare versions.
- The task's form must offer the documents for download. If it doesn't, the call is refused (see below).
- Call it at most **once a minute for the same task**.


## Errors

| Answer | Meaning | What to do |
|  --- | --- | --- |
| `401` | Token missing or expired | Get a new token |
| `403` | The project isn't your company's | Skip it |
| `404` | Project or task not found | Skip it |
| `400`, code `TASK_USER_CANNOT_DOWNLOAD_DOCUMENTS` | This task doesn't offer the documents, or hasn't started | Check that it's the right task, and its status |
| `400`, code `TASK_RATE_LIMIT_EXCEEDED_FOR_DOWNLOAD_DOCUMENT` | Same task downloaded less than a minute ago | Wait one minute |


See [Errors](/getting-started/errors) for the error body.

## Planned improvements

These are requested, with no date yet:

- **A modified-date filter** on the project list, so step 1 returns only the projects that changed since your last run.
- **Documents per product**, to download each document on its own instead of the whole project.
- **Events** when documents are available. Keep a scheduled run even then, to catch anything missed.


See the [API roadmap](/getting-started/roadmap).