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

# List matters

> List the matters you can read.

Returns a page of the matters you can read, in the order the Matters list in Wordsmith shows them. A matter groups the tasks of one piece of legal work, such as a deal or a dispute. List the tasks filed in a matter with `matter_id` on [List tasks](https://wordsmithai.mintlify.site/api-reference/tasks/list-tasks.md).

Matters must be enabled for your organisation. Without them, this endpoint answers `404`.

`query` keeps the matters whose own text matches it, and the matters holding a task you can read whose text matches. A matter kept only for its tasks comes back with `matched_through_tasks` set to `true`. Without `query`, `matched_through_tasks` is `null`.

`archived` is `true` for an archived matter, which the list returns only with `include_archived`. A matter's `status` is not returned.

## Authentication

Requires an API key, or an OAuth token with `matters:read`.

## Query parameters

**query** `string`

Only matters whose text, or whose tasks' text, contains this.

**include\_archived** `boolean` (default: false)

Include archived matters.

**cursor** `string`

The `cursor` from the previous page. Leave it out for the first page.

**limit** `integer` (default: 20)

Matters per page, from `1` to `100`. Keep it, and the filters, the same for every page of a walk.

## Response

Returns `200` with a page of matters. `cursor` is `null` on the last page.

`task_counts` counts the matter's tasks you can read: `done` of `total`. It is `null` when the counts could not be computed for this response. On a list with `query`, null counts also mean the search matched matters by their own text only, so matters kept only for their tasks may be missing; try again later. `status_update.author` is `null` when the author's account no longer exists. Times are ISO 8601 in UTC.

Pages are read from the live list, not a snapshot. A matter updated during a walk can move, so a walk can skip or repeat it.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.wordsmith.ai/api/v1/matters?query=supplier" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"
```

```json Response theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "items": [
    {
      "id": "6d1f0a3e-2b4c-4d5e-8f6a-7b8c9d0e1f2a",
      "matter_number": 7,
      "name": "Supplier agreement renewal",
      "matter_type": "procurement",
      "counterparties": ["Northwind Ltd"],
      "owner": {
        "id": "7e9a1c3b-5d7f-4b9d-8e0f-3a5c7e9b1d2f",
        "name": "Jane Doe",
        "email": "jane@example.com"
      },
      "requested_by": null,
      "labels": ["Q4"],
      "summary": "Renewal of the logistics supply agreement, with revised liability caps.",
      "objective": "Sign the renewal before the current term ends.",
      "risk": "medium",
      "value": { "amount": "125000.00", "currency": "GBP" },
      "jurisdiction": "England and Wales",
      "code": "PROC-7",
      "milestones": [
        { "id": "a3f1c2d4-5b6e-4f7a-8b9c-0d1e2f3a4b5c", "label": "Signing", "date": "2026-12-15T00:00:00Z", "done": false }
      ],
      "status_update": {
        "status_line": "Waiting on the counterparty's redlines",
        "latest_news": null,
        "next_action": "Chase the redlines on Friday",
        "author": {
          "id": "7e9a1c3b-5d7f-4b9d-8e0f-3a5c7e9b1d2f",
          "name": "Jane Doe",
          "email": "jane@example.com"
        },
        "written_at": "2026-11-16T09:30:00Z"
      },
      "task_counts": { "done": 2, "total": 5 },
      "matched_through_tasks": false,
      "archived": false,
      "opened_at": "2026-10-01T08:00:00Z",
      "closed_at": null,
      "target_completion_at": "2026-12-31T00:00:00Z",
      "created_at": "2026-10-01T08:00:00Z",
      "updated_at": "2026-11-16T09:30:00Z"
    }
  ],
  "cursor": null
}
```

## Errors

| Status | `error_code` | When |
| - | - | - |
| 400 | `bad_request` | `cursor` is not one this endpoint issued, or `limit` or a filter changed mid-walk. |
| 400 | `bad_request` | `limit` is not an integer from `1` to `100`, `include_archived` is not a boolean, or a query parameter is not one listed above. |
| 404 | | Matters are not enabled for your organisation. |
| 503 | `temporarily_unavailable` | A `query` could not search the matters' tasks. Retry shortly. |


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