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
--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-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
  • Example: 1024
--metadata​

JSON string with additional metadata

  • Source: body
  • Required: no
  • Type: string
  • Example: \{"author":"John"\}

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​

Additional metadata as a JSON string

  • Source: body
  • Required: no
  • Type: string
  • Example: \{"author":"John"\}

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​

JSON string with additional metadata

  • Source: body
  • Required: no
  • Type: string
  • Example: \{"author":"John"\}

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​

JSON string with additional metadata

  • Source: body
  • Required: no
  • Type: string
  • Example: \{"author":"John"\}

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

New metadata as a JSON string

  • Source: body
  • Required: no
  • Type: string
  • Example: \{"author":"Jane","tags":["report"]\}
--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

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>

Options​

--file-id​

File ID

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

soat merge-file-tags​

Merge file tags

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

Usage​

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

Options​

--file-id​

File ID

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