Skip to main content
POST
Workspace: File Read
Read a file from the per-agent workspace filesystem. Optional line ranges let you page through large files without loading them entirely.

Path Parameters

string
required
Agent ID (UUID)

Request Body

string
required
Path to the file relative to the workspace root.
integer
1-based line number to start reading from. Optional; reads from the beginning when omitted.
integer
1-based line number to stop reading at (inclusive). Optional; reads to the end when omitted.
string
default:"utf-8"
Text encoding used to decode the file contents.

Response

string
Result status (e.g., ok).
string
File contents within the requested range.
string
The file path that was read.

Example Request

Notes

  • Paths must be relative to the workspace root. Absolute paths are rejected.
  • For binary files, set encoding appropriately or use File Share to retrieve the file via a public URL.

See Also

Authorizations

x-api-key
string
header
required

API Key for authentication

Path Parameters

agent_id
string
required

Body

application/json
path
string
required

Relative path to the file to read from the workspace filesystem.

Example:

"config.yaml"

start_line
integer | null

1-indexed starting line number for partial reads. Omit to read from the beginning.

Required range: x >= 1
Example:

1

end_line
integer | null

1-indexed ending line number (inclusive) for partial reads. Omit to read to the end.

Required range: x >= 1
Example:

50

encoding
string
default:utf-8

File encoding to use when reading. Falls back to detected encoding if decoding fails.

Example:

"utf-8"

Response

Successful Response

content
string
default:""

File content (full or partial based on line range)

lines_count
integer
default:0

Total number of lines in the returned content

encoding_detected
string
default:utf-8

The encoding used to decode the file