<!--
  immut documentation, machine-readable.

  Everything in one file:  https://www.immut.io/llms-full.txt
    What immut is, which integration path to choose, authentication and scopes, and the COMPLETE
    API reference: every endpoint with parameters, responses and a runnable curl. Fetch this first
    if you intend to call the API.

  Index of all pages:      https://www.immut.io/llms.txt
  OpenAPI contract:        https://www.immut.io/docs/openapi.json
  This page as HTML:       https://www.immut.io/docs/mcp/list_documents

  Any page on this site is available as raw markdown by appending .md to its URL.
-->


# list_documents

**List / count protected documents**

List and COUNT the protected documents (files) in a workspace, optionally filtered by folder or a name search. Use this to answer "how many files do I have" or to show what has been protected. Returns the total count plus a page of documents (name, folder, proof tx, network, date). Read-only.

- Access: read-only
- Calls: `/api/v1/documents`

## Arguments

| Name | Type | Required | Description |
|---|---|---|---|
| `workspace` | string | **yes** | Workspace id |
| `folder` | string | no | Folder id to count/list within (omit for the whole workspace) |
| `search` | string | no | Filter by file name, title, or the agent reason |
| `uploadChannel` | `web` \| `api` \| `agent` | no | agent = only what the AI agent protected |
| `docType` | string | no | Agent classification doc type |
| `docState` | string | no | Agent classification doc state |
| `objective` | string | no | The objective the agent was working to |
| `runId` | string | no | Only documents protected by this sweep |
| `needsFolder` | boolean | no | true = agent-protected files still at the workspace root |
| `party` | string | no | Exact counterparty name, e.g. "Acme Corp". Not a substring: Acme will not match Acme Holdings |
| `hasClassification` | boolean | no | false = documents nobody has described yet. The backfill starting point |
| `documentDateFrom` | string | no | ISO 8601, on the date read OFF the document (unproven) |
| `documentDateTo` | string | no | ISO 8601, on the date read OFF the document (unproven) |
| `sort` | `createdAt` \| `documentDate` | no | createdAt = when immut proved it. documentDate = the date on the page, unproven |
| `order` | `asc` \| `desc` | no | Default desc. Use asc for a chronological story |
| `minConfidence` | number | no | Lowest classification confidence to include |
| `maxConfidence` | number | no | Highest classification confidence to include |
| `from` | string | no | ISO 8601. Only documents protected on or after this |
| `to` | string | no | ISO 8601. Only documents protected on or before this |
| `page` | number | no | Page number (default 1) |
| `limit` | number | no | Page size, max 100 (default 20) |

## Tool contract

```json
{
  "name": "list_documents",
  "title": "List / count protected documents",
  "description": "List and COUNT the protected documents (files) in a workspace, optionally filtered by folder or a name search. Use this to answer \"how many files do I have\" or to show what has been protected. Returns the total count plus a page of documents (name, folder, proof tx, network, date). Read-only.",
  "access": "read",
  "destructive": false,
  "hostedOnProduction": true,
  "restEndpoint": "/api/v1/documents",
  "arguments": {
    "workspace": {
      "type": "string",
      "required": true,
      "description": "Workspace id"
    },
    "folder": {
      "type": "string",
      "required": false,
      "description": "Folder id to count/list within (omit for the whole workspace)"
    },
    "search": {
      "type": "string",
      "required": false,
      "description": "Filter by file name, title, or the agent reason"
    },
    "uploadChannel": {
      "type": "enum",
      "required": false,
      "description": "agent = only what the AI agent protected",
      "values": [
        "web",
        "api",
        "agent"
      ]
    },
    "docType": {
      "type": "string",
      "required": false,
      "description": "Agent classification doc type"
    },
    "docState": {
      "type": "string",
      "required": false,
      "description": "Agent classification doc state"
    },
    "objective": {
      "type": "string",
      "required": false,
      "description": "The objective the agent was working to"
    },
    "runId": {
      "type": "string",
      "required": false,
      "description": "Only documents protected by this sweep"
    },
    "needsFolder": {
      "type": "boolean",
      "required": false,
      "description": "true = agent-protected files still at the workspace root"
    },
    "party": {
      "type": "string",
      "required": false,
      "description": "Exact counterparty name, e.g. \"Acme Corp\". Not a substring: Acme will not match Acme Holdings"
    },
    "hasClassification": {
      "type": "boolean",
      "required": false,
      "description": "false = documents nobody has described yet. The backfill starting point"
    },
    "documentDateFrom": {
      "type": "string",
      "required": false,
      "description": "ISO 8601, on the date read OFF the document (unproven)"
    },
    "documentDateTo": {
      "type": "string",
      "required": false,
      "description": "ISO 8601, on the date read OFF the document (unproven)"
    },
    "sort": {
      "type": "enum",
      "required": false,
      "description": "createdAt = when immut proved it. documentDate = the date on the page, unproven",
      "values": [
        "createdAt",
        "documentDate"
      ]
    },
    "order": {
      "type": "enum",
      "required": false,
      "description": "Default desc. Use asc for a chronological story",
      "values": [
        "asc",
        "desc"
      ]
    },
    "minConfidence": {
      "type": "number",
      "required": false,
      "description": "Lowest classification confidence to include"
    },
    "maxConfidence": {
      "type": "number",
      "required": false,
      "description": "Highest classification confidence to include"
    },
    "from": {
      "type": "string",
      "required": false,
      "description": "ISO 8601. Only documents protected on or after this"
    },
    "to": {
      "type": "string",
      "required": false,
      "description": "ISO 8601. Only documents protected on or before this"
    },
    "page": {
      "type": "number",
      "required": false,
      "description": "Page number (default 1)"
    },
    "limit": {
      "type": "number",
      "required": false,
      "description": "Page size, max 100 (default 20)"
    }
  }
}
```