Skip to main content

Documents Commands

See Documents module docs for permissions and data model.

soat list-documents​

List documents

  • Method: GET
  • Path: /api/v1/documents

Usage​

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/
--include-withdrawn​

Include withdrawn documents. A withdrawn document leaves every default read and is not in the knowledge index at all — its chunks are dropped when it is withdrawn — so this shows it in the listing but never in a search.

  • Source: query
  • Required: no
  • Type: boolean
  • Default: false
--related-to​

Only documents related to this one, on either side of the edge: what it points at, and what points at it. An id with no relations narrows the listing to nothing.

  • Source: query
  • Required: no
  • Type: string
  • Example: doc_V1StGXR8Z5jdHi6B

soat create-document​

Create a document

  • Method: POST
  • Path: /api/v1/documents

Usage​

soat create-document --content <string>

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>, or to /<document_id>.txt when neither is given — a document with no path is reachable only by its id, since a prefix filter never matches null.

  • 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: unknown
--tags​

—

  • Source: body
  • Required: no
  • Type: unknown
--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​

soat ingest-document --file-id <string>

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​

—

  • Source: body
  • Required: no
  • Type: unknown
--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
--session-id​

Session the ingest runs for. The converter's generation and the chunk embeddings are metered against the session and its actor.

  • Source: body
  • Required: no
  • Type: string
  • Example: sess_V1StGXR8Z5jdHi6B
--actor-id​

Actor the ingest runs for when there is no session; metered like session_id. Beside session_id it must be that session's actor, else 400 VALIDATION_FAILED.

  • Source: body
  • Required: no
  • Type: string
  • Example: actor_V1StGXR8Z5jdHi6B

soat export-documents​

Export documents as NDJSON

  • Method: GET
  • Path: /api/v1/documents/export

Usage​

soat export-documents --project-id <string>

Options​

--project-id​

Project whose documents are exported

  • Source: query
  • Required: yes
  • Type: string
  • Example: proj_V1StGXR8Z5jdHi6B
--path-prefix​

Only documents filed under this directory. The prefix is a path boundary, not a substring, exactly as on the listing.

  • Source: query
  • Required: no
  • Type: string
  • Example: /reports

soat get-document​

Get a document by ID

  • Method: GET
  • Path: /api/v1/documents/{document_id}

Usage​

soat get-document --document-id <string>

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​

soat delete-document --document-id <string>

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​

soat update-document --document-id <string>

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, replacing the stored bag; null clears it. 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: unknown
--tags​

—

  • Source: body
  • Required: no
  • Type: unknown
--expected-version​

Refuses the write unless the document is at this version.

  • Source: body
  • Required: no
  • Type: unknown

soat list-document-relations​

List a document's relations

  • Method: GET
  • Path: /api/v1/documents/{document_id}/relations

Usage​

soat list-document-relations --document-id <string>

Options​

--document-id​

—

  • Source: path
  • Required: yes
  • Type: string
  • Example: doc_V1StGXR8Z5jdHi6B

soat create-document-relation​

Assert a relation

  • Method: POST
  • Path: /api/v1/documents/{document_id}/relations

Usage​

soat create-document-relation --document-id <string> --type <enum("derived_from", "supersedes", "cites")> --to-document-id <string>

Options​

--document-id​

—

  • Source: path
  • Required: yes
  • Type: string
  • Example: doc_V1StGXR8Z5jdHi6B
--type​

What this document claims about the other

  • Source: body
  • Required: yes
  • Type: enum("derived_from", "supersedes", "cites")
  • Example: cites
--to-document-id​

The document the edge points at. Must be in the same project, and visible to the caller.

  • Source: body
  • Required: yes
  • Type: string
  • Example: doc_9Kp2mQxZ7bT4rN6W

soat delete-document-relation​

Retract a relation

  • Method: DELETE
  • Path: /api/v1/documents/{document_id}/relations/{relation_id}

Usage​

soat delete-document-relation --document-id <string> --relation-id <string>

Options​

--document-id​

—

  • Source: path
  • Required: yes
  • Type: string
  • Example: doc_V1StGXR8Z5jdHi6B
--relation-id​

—

  • Source: path
  • Required: yes
  • Type: string
  • Example: doc_rel_V1StGXR8Z5jdHi6B

soat get-document-status​

Get document ingestion status

  • Method: GET
  • Path: /api/v1/documents/{document_id}/status

Usage​

soat get-document-status --document-id <string>

Options​

--document-id​

Document ID

  • Source: path
  • Required: yes
  • Type: string
  • Example: doc_V1StGXR8Z5jdHi6B

soat withdraw-document​

Withdraw a document

  • Method: POST
  • Path: /api/v1/documents/{document_id}/withdraw

Usage​

soat withdraw-document --document-id <string>

Options​

--document-id​

—

  • Source: path
  • Required: yes
  • Type: string
--version-label​

Optional tag for the tombstone version this write archives.

  • Source: body
  • Required: no
  • Type: string \| null
  • Example: superseded-by-q2
--expected-version​

Refuses the withdrawal unless the document is at this version.

  • Source: body
  • Required: no
  • Type: unknown

soat list-document-versions​

List a document's content versions

  • Method: GET
  • Path: /api/v1/documents/{document_id}/versions

Usage​

soat list-document-versions --document-id <string>

Options​

--document-id​

—

  • Source: path
  • Required: yes
  • Type: string

soat get-document-version​

Fetch an archived document version

  • Method: GET
  • Path: /api/v1/documents/{document_id}/versions/{version}

Usage​

soat get-document-version --document-id <string> --version <integer>

Options​

--document-id​

—

  • Source: path
  • Required: yes
  • Type: string
--version​

—

  • Source: path
  • Required: yes
  • Type: integer

soat restore-document-version​

Restore an archived document version

  • Method: POST
  • Path: /api/v1/documents/{document_id}/versions/{version}/restore

Usage​

soat restore-document-version --document-id <string> --version <integer>

Options​

--document-id​

—

  • Source: path
  • Required: yes
  • Type: string
--version​

—

  • Source: path
  • Required: yes
  • Type: integer
--label​

Optional tag for the version this restore archives. Defaults to restored from v<version>.

  • Source: body
  • Required: no
  • Type: string \| null
  • Example: reinstated

soat reingest-document​

Re-ingest an existing document

  • Method: POST
  • Path: /api/v1/documents/{document_id}/ingest

Usage​

soat reingest-document --document-id <string>

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
--session-id​

Session the ingest runs for. The converter's generation and the chunk embeddings are metered against the session and its actor.

  • Source: body
  • Required: no
  • Type: string
  • Example: sess_V1StGXR8Z5jdHi6B
--actor-id​

Actor the ingest runs for when there is no session; metered like session_id. Beside session_id it must be that session's actor, else 400 VALIDATION_FAILED.

  • Source: body
  • Required: no
  • Type: string
  • Example: actor_V1StGXR8Z5jdHi6B

soat complete-ingestion-callback​

Deliver an async converter result

  • Method: POST
  • Path: /api/v1/documents/{document_id}/ingestion-callback

Usage​

soat complete-ingestion-callback --document-id <string> --token <string>

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​

soat get-document-tags --document-id <string>

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​

soat replace-document-tags --document-id <string> --tags <object>

Options​

--document-id​

Document ID

  • Source: path
  • Required: yes
  • Type: string
  • Example: doc_V1StGXR8Z5jdHi6B
--tags​

Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with 400 VALIDATION_FAILED, never coerced. Keys are opaque and stored verbatim, so cost_center and costCenter are two different tags. Matched by JSONB containment wherever tags are read: the ?tags= filter, knowledge search, and the IAM soat:ResourceTag/<key> condition. Keys beginning system. are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with 400 RESERVED_TAG_KEY. They are read and filtered like any other tag. The bag is bounded, because every pair reaches the IAM context of every access check on the resource: at most 50 keys, each key at most 128 characters and each value at most 256. A write past a bound — including a merge that would grow the stored bag past the key count — is 400 VALIDATION_FAILED with meta.limit naming the bound it crossed. system.* keys are the platform's and do not count against the 50.

  • Source: body
  • Required: yes
  • Type: object

soat merge-document-tags​

Merge document tags

  • Method: PATCH
  • Path: /api/v1/documents/{document_id}/tags

Usage​

soat merge-document-tags --document-id <string> --tags <object>

Options​

--document-id​

Document ID

  • Source: path
  • Required: yes
  • Type: string
  • Example: doc_V1StGXR8Z5jdHi6B
--tags​

Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with 400 VALIDATION_FAILED, never coerced. Keys are opaque and stored verbatim, so cost_center and costCenter are two different tags. Matched by JSONB containment wherever tags are read: the ?tags= filter, knowledge search, and the IAM soat:ResourceTag/<key> condition. Keys beginning system. are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with 400 RESERVED_TAG_KEY. They are read and filtered like any other tag. The bag is bounded, because every pair reaches the IAM context of every access check on the resource: at most 50 keys, each key at most 128 characters and each value at most 256. A write past a bound — including a merge that would grow the stored bag past the key count — is 400 VALIDATION_FAILED with meta.limit naming the bound it crossed. system.* keys are the platform's and do not count against the 50.

  • Source: body
  • Required: yes
  • Type: object