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

# Deliveries

> The task sets your organization holds: list them, read one, download its lock, its checksums and each task's files.

A delivery is a versioned set of tasks, named `<name>@<version>`, for example `acme-swe@0.1.0`. A version never changes. A fix is a new version, and the one it replaces names it as `newer`.

The calls need a key with access to deliveries. From a terminal, the `kennet` CLI makes the same calls: `kennet delivery list`, `kennet delivery show <id>`, `kennet delivery pull <id>`, `kennet delivery verify` and `kennet delivery diff`.

## The delivery object

| Field | Type | Description |
| - | - | - |
| `id` | string | `<name>@<version>` |
| `object` | string | `delivery` |
| `name`, `version` | string | The set's name and this version |
| `delivered` | string or null | The date it was sent, `YYYY-MM-DD` |
| `task_count` | integer | How many tasks it holds |
| `image_count` | integer | Distinct images across the tasks |
| `bytes` | integer | The size of every task's content together |
| `lock` | integer | The lock's format. `1`: a task's tree is the SHA-256 of its `<sha256>  <path>` lines. `2`: of `<sha256>  <mode>  <path>`, the mode as git gives it |
| `registry` | string or null | The image repository the tasks' images are pulled from. See [Registry tokens](https://docs.metaphi.ai/kennet/api/registry.md) |
| `newer` | string or null | The id of the newest version of this set your organization holds, when that is not this one |
| `tasks` | array | On a retrieved delivery only: its tasks, in the lock's order |

Each task:

| Field | Type | Description |
| - | - | - |
| `name` | string | The task's name |
| `tree` | string | `sha256:` and the SHA-256 over one line per file of the task, in path order, as the delivery's `lock` says |
| `files`, `bytes` | integer | How many files the task holds, and the size of its tar |
| `images` | array | Every image the task names, as a path under the delivery's `registry`, pinned by digest |
| `grader_images` | array or null | The images that grade. A change in one is a change in the task's grading |
| `cpus`, `memory_mb`, `storage_mb` | number or null | What the task's environment asks for |
| `agent_timeout_s`, `verifier_timeout_s` | number or null | The longest the agent runs, and the longest grading runs |
| `category`, `difficulty` | string or null | As the task declares them |

## List deliveries

`GET /v1/kennet/deliveries` returns every delivery your organization holds, newest sent first, without their tasks.

```sh theme={"dark"}
curl https://api.metaphi.ai/v1/kennet/deliveries -H "Authorization: Bearer $API_KEY"
```

## Retrieve a delivery

`GET /v1/kennet/deliveries/{delivery_id}` returns the delivery with every task, its tree hash, its images by digest, and what a run of it asks for. Another organization's delivery, or an id that does not exist, answers `404 resource_missing`.

## Download the lock and the checksums

* `GET /v1/kennet/deliveries/{delivery_id}/lock` is the delivery's record. Keep it beside the tasks: they are checked against it with no further call (`kennet delivery verify`).
* `GET /v1/kennet/deliveries/{delivery_id}/sums` is every file's SHA-256, in the format `sha256sum -c` reads.

## Download a task's files

`GET /v1/kennet/deliveries/{delivery_id}/tasks/{task}/content` is one task's tree as a tar. Unpacked, its tree hash is the one the lock gives.

```sh theme={"dark"}
curl https://api.metaphi.ai/v1/kennet/deliveries/acme-swe@0.1.0/tasks/fix-rounding/content \
  -H "Authorization: Bearer $API_KEY" -o fix-rounding.tar
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.