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

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 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<string, string>
--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​

--async​

When omitted or true (default), processing runs in the background and 202 Accepted is returned immediately with status=pending. Pass false to run synchronously and receive 201 Created with status=ready.

  • Source: query
  • Required: no
  • Type: boolean
  • Default: true
--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<string, string>
--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​

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. 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<string, string>

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 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
--async​

When omitted or true (default), processing runs in the background and 202 Accepted is returned immediately with status=pending. Pass false to run synchronously and receive 201 Created with status=ready.

  • Source: query
  • Required: no
  • Type: boolean
  • Default: true
--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​

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>

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​

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

Options​

--document-id​

Document ID

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