<!--
  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/api/documents/get-documents

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


# List existing proofs with pagination and filters

`GET /documents`

**Required scope:** `documents:read`

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `workspace` | query | no | workspace id |
| `folder` | query | no | folder id |
| `category` | query | no | document category |
| `blockchainStatus` | query | no | proof status |
| `uploadChannel` | query | no | web \| api \| agent. Use agent to see only what the agent protected |
| `docType` | query | no | agent classification doc type |
| `docState` | query | no | agent classification doc state |
| `runId` | query | no | only documents protected by this sweep |
| `objective` | query | no | the objective the agent was working to |
| `folderKey` | query | no | the folder key the agent chose |
| `servesObjective` | query | no | true \| false |
| `needsFolder` | query | no | true returns agent-protected files still sitting at the workspace root |
| `minConfidence` | query | no | 0 to 1 |
| `maxConfidence` | query | no | 0 to 1 |
| `minFolderConfidence` | query | no | 0 to 1, the filing confidence rather than the classification confidence |
| `maxFolderConfidence` | query | no | 0 to 1 |
| `from` | query | no | ISO 8601, filters on when the document was protected |
| `to` | query | no | ISO 8601, filters on when the document was protected |
| `search` | query | no | matches file name, title and the agent reason |
| `page` | query | no | default 1 |
| `limit` | query | no | default 20, max 100 |

## Responses

| Status | Meaning |
|---|---|
| `200` | Paginated proof list with meta { page, limit, total } Returns: each row is the document including its full agentClassification: docType, docState, servesObjective, folderKey, confidence, folderConfidence, reason, objective, runId. meta carries page, limit, total, totalPages. |

## Example

```bash
curl -X GET "https://backend.immut.io/api/v1/documents" \
  -H "Authorization: Bearer $IMMUT_API_KEY"
```

## OpenAPI fragment

```json
{
  "/documents": {
    "get": {
      "operationId": "listProofs",
      "summary": "List existing proofs with pagination and filters",
      "description": "Requires scope documents:read.",
      "parameters": [
        {
          "name": "workspace",
          "in": "query",
          "required": false,
          "schema": {
            "type": "string"
          },
          "description": "workspace id"
        },
        {
          "name": "folder",
          "in": "query",
          "required": false,
          "schema": {
            "type": "string"
          },
          "description": "folder id"
        },
        {
          "name": "category",
          "in": "query",
          "required": false,
          "schema": {
            "type": "string"
          },
          "description": "document category"
        },
        {
          "name": "blockchainStatus",
          "in": "query",
          "required": false,
          "schema": {
            "type": "string"
          },
          "description": "proof status"
        },
        {
          "name": "uploadChannel",
          "in": "query",
          "required": false,
          "schema": {
            "type": "string"
          },
          "description": "web | api | agent. Use agent to see only what the agent protected"
        },
        {
          "name": "docType",
          "in": "query",
          "required": false,
          "schema": {
            "type": "string"
          },
          "description": "agent classification doc type"
        },
        {
          "name": "docState",
          "in": "query",
          "required": false,
          "schema": {
            "type": "string"
          },
          "description": "agent classification doc state"
        },
        {
          "name": "runId",
          "in": "query",
          "required": false,
          "schema": {
            "type": "string"
          },
          "description": "only documents protected by this sweep"
        },
        {
          "name": "objective",
          "in": "query",
          "required": false,
          "schema": {
            "type": "string"
          },
          "description": "the objective the agent was working to"
        },
        {
          "name": "folderKey",
          "in": "query",
          "required": false,
          "schema": {
            "type": "string"
          },
          "description": "the folder key the agent chose"
        },
        {
          "name": "servesObjective",
          "in": "query",
          "required": false,
          "schema": {
            "type": "string"
          },
          "description": "true | false"
        },
        {
          "name": "needsFolder",
          "in": "query",
          "required": false,
          "schema": {
            "type": "string"
          },
          "description": "true returns agent-protected files still sitting at the workspace root"
        },
        {
          "name": "minConfidence",
          "in": "query",
          "required": false,
          "schema": {
            "type": "number"
          },
          "description": "0 to 1"
        },
        {
          "name": "maxConfidence",
          "in": "query",
          "required": false,
          "schema": {
            "type": "number"
          },
          "description": "0 to 1"
        },
        {
          "name": "minFolderConfidence",
          "in": "query",
          "required": false,
          "schema": {
            "type": "number"
          },
          "description": "0 to 1, the filing confidence rather than the classification confidence"
        },
        {
          "name": "maxFolderConfidence",
          "in": "query",
          "required": false,
          "schema": {
            "type": "number"
          },
          "description": "0 to 1"
        },
        {
          "name": "from",
          "in": "query",
          "required": false,
          "schema": {
            "type": "string",
            "format": "date-time"
          },
          "description": "ISO 8601, filters on when the document was protected"
        },
        {
          "name": "to",
          "in": "query",
          "required": false,
          "schema": {
            "type": "string",
            "format": "date-time"
          },
          "description": "ISO 8601, filters on when the document was protected"
        },
        {
          "name": "search",
          "in": "query",
          "required": false,
          "schema": {
            "type": "string"
          },
          "description": "matches file name, title and the agent reason"
        },
        {
          "name": "page",
          "in": "query",
          "required": false,
          "schema": {
            "type": "integer"
          },
          "description": "default 1"
        },
        {
          "name": "limit",
          "in": "query",
          "required": false,
          "schema": {
            "type": "integer"
          },
          "description": "default 20, max 100"
        }
      ],
      "responses": {
        "200": {
          "description": "Paginated proof list with meta { page, limit, total } Returns: each row is the document including its full agentClassification: docType, docState, servesObjective, folderKey, confidence, folderConfidence, reason, objective, runId. meta carries page, limit, total, totalPages."
        }
      },
      "tags": [
        "Documents"
      ],
      "x-required-scope": "documents:read"
    }
  }
}
```