# Documents Commands > See [Documents module docs](../../modules/documents) for permissions and data model. # Documents Commands See [Documents module docs](../../modules/documents) for permissions and data model. ### `soat list-documents` List documents - Method: `GET` - Path: `/api/v1/documents` #### Usage ```bash soat list-documents ``` #### Options ##### `--project-id` Project ID (optional) - Source: `query` - Required: no - Type: `string` - Example: `proj_V1StGXR8Z5jdHi6B` ##### `--path-prefix` Only documents filed under this directory. The prefix is a path boundary, not a substring: `/reports` returns `/reports/q1.txt` and never `/reports-archive/q1.txt`, and `/` selects the whole project. A leading slash is optional and a trailing one is ignored, so `reports`, `/reports` and `/reports/` are the same filter. `%` and `_` are literal characters, not wildcards. - Source: `query` - Required: no - Type: `string` - Example: `/reports/` ##### `--limit` Maximum number of results to return - Source: `query` - Required: no - Type: `integer` - Default: `50` ##### `--offset` Number of results to skip - Source: `query` - Required: no - Type: `integer` - Default: `0` ### `soat create-document` Create a document - Method: `POST` - Path: `/api/v1/documents` #### Usage ```bash soat create-document --content ``` #### Options ##### `--project-id` Project ID. Required for JWT auth; omit when using an project key. - Source: `body` - Required: no - Type: `string` - Example: `proj_V1StGXR8Z5jdHi6B` ##### `--content` — - Source: `body` - Required: yes - Type: `string` - Example: `The quick brown fox jumps over the lazy dog.` ##### `--path` Logical path within the project (e.g. /reports/q1.txt). Defaults to /filename if omitted. - Source: `body` - Required: no - Type: `string` - Example: `/reports/q1.txt` ##### `--filename` — - Source: `body` - Required: no - Type: `string` - Example: `my-doc.txt` ##### `--title` Document title - Source: `body` - Required: no - Type: `string` ##### `--metadata` Arbitrary metadata object. Unlike other body fields, keys are stored and returned verbatim in the casing supplied — they are not converted between snake_case and camelCase. - Source: `body` - Required: no - Type: `object` ##### `--tags` Key-value tags - Source: `body` - Required: no - Type: `object` ##### `--chunk-strategy` How to split the content into embeddable chunks. `whole` (default) stores the content as a single chunk; `size` splits into fixed-size character windows with overlap. `page` is equivalent to `whole` for plain text. - Source: `body` - Required: no - Type: `enum("page", "whole", "size")` - Default: `whole` ##### `--chunk-size` Window size in characters when `chunk_strategy=size`. Defaults to 1000. - Source: `body` - Required: no - Type: `integer` - Example: `1000` ##### `--chunk-overlap` Overlap in characters between consecutive windows when `chunk_strategy=size`. Defaults to 200. - Source: `body` - Required: no - Type: `integer` - Example: `200` ### `soat ingest-document` Ingest a file into a chunked document - Method: `POST` - Path: `/api/v1/documents/ingest` #### Usage ```bash soat ingest-document --file-id ``` #### Options ##### `--wait` When omitted or `false` (default), processing runs in the background and `202 Accepted` is returned immediately with `status=pending`. Pass `true` to block until processing completes and receive `201 Created` with `status=ready`. - Source: `query` - Required: no - Type: `boolean` - Default: `false` ##### `--file-id` ID of the uploaded file. Must be one of application/pdf, text/plain, text/markdown. - Source: `body` - Required: yes - Type: `string` - Example: `file_V1StGXR8Z5jdHi6B` ##### `--project-id` Project ID. Required for JWT auth; omit when using a project key. - Source: `body` - Required: no - Type: `string` - Example: `proj_V1StGXR8Z5jdHi6B` ##### `--path-prefix` Path prefix under which to store the document (e.g. /docs/). The filename is appended automatically. - Source: `body` - Required: no - Type: `string` - Example: `/docs/` ##### `--tags` Key-value tags to attach to the document. - Source: `body` - Required: no - Type: `object` ##### `--chunk-strategy` How to split the source into chunks. `page` (default) creates one chunk per non-empty page (PDF); for non-paged sources it yields a single chunk. `whole` joins everything into one chunk. `size` splits into fixed-size character windows with overlap. - Source: `body` - Required: no - Type: `enum("page", "whole", "size")` - Default: `page` ##### `--chunk-size` Window size in characters when `chunk_strategy=size`. Defaults to 1000. - Source: `body` - Required: no - Type: `integer` - Example: `1000` ##### `--chunk-overlap` Overlap in characters between consecutive windows when `chunk_strategy=size`. Defaults to 200. - Source: `body` - Required: no - Type: `integer` - Example: `200` ### `soat get-document` Get a document by ID - Method: `GET` - Path: `/api/v1/documents/{document_id}` #### Usage ```bash soat get-document --document-id ``` #### Options ##### `--document-id` Document ID - Source: `path` - Required: yes - Type: `string` - Example: `doc_V1StGXR8Z5jdHi6B` ### `soat delete-document` Delete a document - Method: `DELETE` - Path: `/api/v1/documents/{document_id}` #### Usage ```bash soat delete-document --document-id ``` #### Options ##### `--document-id` Document ID - Source: `path` - Required: yes - Type: `string` - Example: `doc_V1StGXR8Z5jdHi6B` ### `soat update-document` Update a document - Method: `PATCH` - Path: `/api/v1/documents/{document_id}` #### Usage ```bash soat update-document --document-id ``` #### Options ##### `--document-id` Document ID - Source: `path` - Required: yes - Type: `string` - Example: `doc_V1StGXR8Z5jdHi6B` ##### `--content` New text content - Source: `body` - Required: no - Type: `string` ##### `--title` New title - Source: `body` - Required: no - Type: `string` ##### `--path` Logical path within the project (e.g. /reports/q1.txt). Pass null to clear. - Source: `body` - Required: no - Type: `string \| null` - Example: `/reports/q1.txt` ##### `--metadata` Arbitrary metadata object. Unlike other body fields, keys are stored and returned verbatim in the casing supplied — they are not converted between snake_case and camelCase. - Source: `body` - Required: no - Type: `object` ##### `--tags` Key-value tags - Source: `body` - Required: no - Type: `object` ### `soat get-document-status` Get document ingestion status - Method: `GET` - Path: `/api/v1/documents/{document_id}/status` #### Usage ```bash soat get-document-status --document-id ``` #### Options ##### `--document-id` Document ID - Source: `path` - Required: yes - Type: `string` - Example: `doc_V1StGXR8Z5jdHi6B` ### `soat reingest-document` Re-ingest an existing document - Method: `POST` - Path: `/api/v1/documents/{document_id}/ingest` #### Usage ```bash soat reingest-document --document-id ``` #### Options ##### `--document-id` Document ID - Source: `path` - Required: yes - Type: `string` - Example: `doc_V1StGXR8Z5jdHi6B` ##### `--wait` When omitted or `false` (default), processing runs in the background and `202 Accepted` is returned immediately with `status=pending`. Pass `true` to block until processing completes and receive `201 Created` with `status=ready`. - Source: `query` - Required: no - Type: `boolean` - Default: `false` ##### `--chunk-strategy` How to split the source into chunks. Defaults to `page`. - Source: `body` - Required: no - Type: `enum("page", "whole", "size")` - Default: `page` ##### `--chunk-size` Window size in characters when `chunk_strategy=size`. Defaults to 1000. - Source: `body` - Required: no - Type: `integer` - Example: `1000` ##### `--chunk-overlap` Overlap in characters between consecutive windows when `chunk_strategy=size`. Defaults to 200. - Source: `body` - Required: no - Type: `integer` - Example: `200` ### `soat complete-ingestion-callback` Deliver an async converter result - Method: `POST` - Path: `/api/v1/documents/{document_id}/ingestion-callback` #### Usage ```bash soat complete-ingestion-callback --document-id --token ``` #### Options ##### `--document-id` Document ID - Source: `path` - Required: yes - Type: `string` - Example: `doc_V1StGXR8Z5jdHi6B` ##### `--token` Single-use signed token from the original `callback.token` - Source: `query` - Required: yes - Type: `string` ### `soat get-document-tags` Get document tags - Method: `GET` - Path: `/api/v1/documents/{document_id}/tags` #### Usage ```bash soat get-document-tags --document-id ``` #### Options ##### `--document-id` Document ID - Source: `path` - Required: yes - Type: `string` - Example: `doc_V1StGXR8Z5jdHi6B` ### `soat replace-document-tags` Replace document tags - Method: `PUT` - Path: `/api/v1/documents/{document_id}/tags` #### Usage ```bash soat replace-document-tags --document-id ``` #### Options ##### `--document-id` Document ID - Source: `path` - Required: yes - Type: `string` - Example: `doc_V1StGXR8Z5jdHi6B` ### `soat merge-document-tags` Merge document tags - Method: `PATCH` - Path: `/api/v1/documents/{document_id}/tags` #### Usage ```bash soat merge-document-tags --document-id ``` #### Options ##### `--document-id` Document ID - Source: `path` - Required: yes - Type: `string` - Example: `doc_V1StGXR8Z5jdHi6B`