Skip to main content

Files Commands

See Files module docs for permissions and data model.

soat list-files​

List all files

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

Usage​

soat list-files

Options​

--project-id​

Filter files by project ID

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

Only files 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. Naming a directory under /.system/ is what includes platform-written files, which a list without this parameter leaves out.

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

soat create-file​

Create a file

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

Usage​

soat create-file

Options​

--project-id​

Public ID of the project. Optional when authenticating with a project-scoped API key, which defaults to the key's project; required otherwise.

  • Source: body
  • Required: no
  • Type: string
  • Example: proj_V1StGXR8Z5jdHi6B
--prefix​

Directory within the project (e.g. /images). Optional; defaults to / (root). Combined with filename to form the file's key (path).

  • Source: body
  • Required: no
  • Type: string
  • Example: /images
--filename​

Original / download name and the key's leaf segment (e.g. logo.png).

  • Source: body
  • Required: no
  • Type: string
  • Example: logo.png
--content-type​

MIME type of the file

  • Source: body
  • Required: no
  • Type: string
  • Example: application/pdf
--size​

File size in bytes

  • Source: body
  • Required: no
  • Type: integer \| null
  • Example: 1024
--metadata​

—

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

soat upload-file​

Upload a file

  • Method: POST
  • Path: /api/v1/files/upload

Usage​

soat upload-file --file <string>

Options​

--file​

File content

  • Source: body
  • Required: yes
  • Type: string
--project-id​

Project ID to associate the file with. Optional when authenticating with a project-scoped API key, which defaults to the key's project; required otherwise.

  • Source: body
  • Required: no
  • Type: string
  • Example: proj_V1StGXR8Z5jdHi6B
--prefix​

Directory within the project (e.g. /images). Optional; defaults to / (root).

  • Source: body
  • Required: no
  • Type: string
  • Example: /images
--filename​

Original / download name. Optional; defaults to the uploaded file's name.

  • Source: body
  • Required: no
  • Type: string
  • Example: logo.png
--metadata​

—

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

soat upload-file-base64​

Upload a file using base64 encoding

  • Method: POST
  • Path: /api/v1/files/upload/base64

Usage​

soat upload-file-base64 --content <string>

Options​

--project-id​

Public ID of the project

  • Source: body
  • Required: no
  • Type: string
  • Example: proj_V1StGXR8Z5jdHi6B
--content​

Base64-encoded file content

  • Source: body
  • Required: yes
  • Type: string
  • Example: SGVsbG8gV29ybGQ=
--prefix​

Directory within the project (e.g. /documents). Optional; defaults to / (root).

  • Source: body
  • Required: no
  • Type: string
  • Example: /documents
--filename​

Original / download name and the key's leaf segment.

  • Source: body
  • Required: no
  • Type: string
  • Example: document.txt
--content-type​

MIME type of the file

  • Source: body
  • Required: no
  • Type: string
  • Example: text/plain
--metadata​

—

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

soat create-presigned-url​

Create a presigned upload URL

  • Method: POST
  • Path: /api/v1/files/presigned-url

Usage​

soat create-presigned-url --project-id <string>

Options​

--project-id​

Public ID of the project

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

Directory within the project (e.g. /documents). Optional; defaults to / (root).

  • Source: body
  • Required: no
  • Type: string
  • Example: /documents
--filename​

Original / download name and the key's leaf segment.

  • Source: body
  • Required: no
  • Type: string
  • Example: report.pdf
--content-type​

MIME type of the file to be uploaded

  • Source: body
  • Required: no
  • Type: string
  • Example: application/pdf

soat upload-file-with-token​

Upload a file using an upload token

  • Method: POST
  • Path: /api/v1/files/upload/{token}

Usage​

soat upload-file-with-token --token <string>

Options​

--token​

The single-use upload token (e.g. upt_...)

  • Source: path
  • Required: yes
  • Type: string
  • Example: upt_V1StGXR8Z5jdHi6B
--content​

Base64-encoded file content (alternative to multipart file)

  • Source: body
  • Required: no
  • Type: string
  • Example: SGVsbG8gV29ybGQ=
--filename​

Original / download name (overrides the token's filename)

  • Source: body
  • Required: no
  • Type: string
  • Example: document.txt
--content-type​

MIME type of the file (overrides the token's content type)

  • Source: body
  • Required: no
  • Type: string
  • Example: text/plain
--metadata​

—

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

soat get-file​

Get a file by ID

  • Method: GET
  • Path: /api/v1/files/{file_id}

Usage​

soat get-file --file-id <string>

Options​

--file-id​

File ID

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

soat delete-file​

Delete a file

  • Method: DELETE
  • Path: /api/v1/files/{file_id}

Usage​

soat delete-file --file-id <string>

Options​

--file-id​

ID of the file to delete

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

soat download-file​

Download a file

  • Method: GET
  • Path: /api/v1/files/{file_id}/download

Usage​

soat download-file --file-id <string>

Options​

--file-id​

File ID

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

Signed single-file download token, an alternative to a bearer credential (issued for ingestion-rule converters).

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

soat update-file-metadata​

Update file metadata

  • Method: PATCH
  • Path: /api/v1/files/{file_id}/metadata

Usage​

soat update-file-metadata --file-id <string>

Options​

--file-id​

File ID

  • Source: path
  • Required: yes
  • Type: string
  • Example: file_abc123
--metadata​

Replaces the stored bag; null clears it.

  • Source: body
  • Required: no
  • Type: unknown
--prefix​

New directory — moves the file. The resulting path (prefix + filename) must be unique within the project.

  • Source: body
  • Required: no
  • Type: string
  • Example: /reports
--filename​

New filename — renames the key's leaf and the download name.

  • Source: body
  • Required: no
  • Type: string
  • Example: renamed-file.txt

soat download-file-base64​

Download file as base64

  • Method: GET
  • Path: /api/v1/files/{file_id}/download/base64

Usage​

soat download-file-base64 --file-id <string>

Options​

--file-id​

File ID

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

Signed single-file download token, an alternative to a bearer credential (issued for ingestion-rule converters).

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

soat get-file-tags​

Get file tags

  • Method: GET
  • Path: /api/v1/files/{file_id}/tags

Usage​

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

Options​

--file-id​

File ID

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

soat replace-file-tags​

Replace file tags

  • Method: PUT
  • Path: /api/v1/files/{file_id}/tags

Usage​

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

Options​

--file-id​

File ID

  • Source: path
  • Required: yes
  • Type: string
--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-file-tags​

Merge file tags

  • Method: PATCH
  • Path: /api/v1/files/{file_id}/tags

Usage​

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

Options​

--file-id​

File ID

  • Source: path
  • Required: yes
  • Type: string
--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