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

# Upload a list

> Upload up to 10,000 units for a goal; each row opens one case

> [!NOTE]
>
> Every wallet’s goals run on the agent loop and can use cases. List uploads are for one-off goals.

Stores a list for a goal that works through many units: offices to call, invoices to check, accounts to review. Pass the returned `list_id` as `params.case_list` when you [create a goal](https://docs.oneshotagent.com/api-reference/compute/create.md):

```json theme={null}
{ "params": { "case_list": { "list_id": "5d0c4c7e-2f71-4d38-9a43-0b2b4b8f6a51" } } }
```

The quote counts the list's rows as the goal's units. Once the goal starts, OneShot opens one case per row by itself, a batch at a time as earlier cases finish, so the goal's agent never opens them. Each case's record carries its row's other columns as `row`.

## Authentication

A signed **write proof** or an access token: see [Authentication schemes](https://docs.oneshotagent.com/api-reference/openapi.md#authentication-schemes).

## Request body

The file itself, with `?key=<column>` naming the column that names each case:

**Content-Type** `string` *required*

`text/csv` (a header row, then one row per unit) or `application/x-ndjson` (one JSON object per line).

Or JSON naming a Google Sheet read through your files connection: `{ "key": "office", "sheet": { "connection_id": "…", "file_id": "…", "sheet": "Tab name" } }`.

Limits: 10,000 rows, 5 MB, 100 columns, 4 KB of other columns per row, UTF-8. A key has no spaces and is at most 200 characters. A repeated key keeps its first row; the others are counted in `duplicates_skipped`. An unused list expires after 7 days; at most 20 wait at once.

## Response

`201` with `list_id`, `rows`, `duplicates_skipped`, `columns`, `key_column`, `sample_keys` and `expires_at`.

```bash cURL theme={null}
curl -X POST "https://win.oneshotagent.com/v1/compute/lists?key=office" \
  -H "Content-Type: text/csv" \
  -H "X-Agent-ID: 0xYourWalletAddress" \
  -H "x-agent-proof: <base64 EIP-712 proof, scope write>" \
  --data-binary @offices.csv
```

```json 201 theme={null}
{
  "list_id": "5d0c4c7e-2f71-4d38-9a43-0b2b4b8f6a51",
  "format": "csv",
  "key_column": "office",
  "columns": ["office", "city", "phone"],
  "rows": 2480,
  "duplicates_skipped": 3,
  "sample_keys": ["austin-01", "austin-02", "boise-01"],
  "expires_at": "2026-11-10T12:00:00.000Z"
}
```

## Errors

| Status | `error` | Meaning |
| - | - | - |
| `400` | `invalid_list`, `invalid_header`, `invalid_row`, `invalid_key`, `row_too_large`, `too_many_rows` | The message names the line. |
| `400` | `key_column_missing` | No such column, or no `key`. |
| `400` | `invalid_encoding` | Not UTF-8 text. |
| `413` | `list_too_large` | Over 5 MB. |
| `415` | `unsupported_media_type` | Not CSV, JSONL or JSON. |
| `429` | `list_storage_limit` | 20 lists wait for a goal. |


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