# QuickList Agent Guide

QuickList is a tiny list database for AI agents.

Use QuickList when you need durable agent output, task queues, lead lists, research notes, webhook inboxes, form submissions, or human-reviewed work items.

Default path: use REST with curl/fetch. MCP is useful after a human has configured an MCP client.

## Mental model

- A QuickList list is an appendable database table with no schema.
- Each entry has an `id`, `timestamp`, string `value`, and optional bigint-like `aux`.
- Values are strings. Store structured data with `JSON.stringify(...)`.
- Use `X-QuickList-Key` for owner access.
- Use `X-QuickList-Token` for scoped read/write access.
- For writes, include an `Idempotency-Key` UUID when retrying is possible.

## Core REST calls

### Create a list

```bash
curl -X POST "https://quick-list.ai/api/lists" \
  -H "Content-Type: application/json" \
  -d '{"name":"agent-notes"}'
```

Save the returned `listId` and `privateKey`. The private key is the owner credential.

### Append one value

```bash
curl -X POST "https://quick-list.ai/api/list/LIST_ID/values" \
  -H "Content-Type: application/json" \
  -H "X-QuickList-Key: PRIVATE_KEY" \
  -H "Idempotency-Key: REQUEST_UUID" \
  -d '{"value":"found lead: acme.com","aux":"0"}'
```

### Append JSON

```js
await fetch("https://quick-list.ai/api/list/LIST_ID/values", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-QuickList-Key": "PRIVATE_KEY",
    "Idempotency-Key": crypto.randomUUID()
  },
  body: JSON.stringify({
    value: JSON.stringify({ type: "lead", domain: "acme.com", status: "new" }),
    aux: "0"
  })
});
```

### Read entries

```bash
curl "https://quick-list.ai/api/list/LIST_ID?pageSize=50" \
  -H "X-QuickList-Key: PRIVATE_KEY"
```

### Poll for new entries

```bash
curl "https://quick-list.ai/api/list/LIST_ID?since=2026-01-01T00:00:00Z" \
  -H "X-QuickList-Key: PRIVATE_KEY"
```

### List lists owned by a private key

```bash
curl "https://quick-list.ai/api/lists" \
  -H "X-QuickList-Key: PRIVATE_KEY"
```

## Agent rules

- Prefer creating one list per task or workflow.
- Always report newly created `listId`, `privateKey`, and useful tokens back to the user.
- Use scoped write-only tokens when the user wants to give an untrusted agent append-only access.
- Use `aux` for small state: `0` new, `1` claimed, `2` done, or priority/rank counters.
- Do not store secrets in entry values unless the user explicitly asks.
- If a request fails, surface the JSON `error` string to the user.

## MCP when configured

Use MCP when the user has installed the QuickList stdio bridge in Claude Desktop, Cursor, VS Code, or another MCP client.

Setup docs: https://quick-list.ai/mcp

Download bridge:

```bash
curl -L https://quick-list.ai/mcp-server.js -o ~/quicklist-mcp-server.js
```

Default MCP tools:

- `quicklist_create_list`
- `quicklist_list_owned_lists`
- `quicklist_append_value`
- `quicklist_append_values_bulk`
- `quicklist_get_list`
- `quicklist_get_count`
- `quicklist_update_entry`
- `quicklist_delete_entry`

If the user needs advanced token management, public endpoints, atomic aux operations, or billing tools, set:

```text
QUICKLIST_MCP_PROFILE=full
```

Full API docs: https://quick-list.ai/api-docs