Skip to main content
POST
/
v1
/
agents
/
{agent_id}
/
workspace
/
file_read
Workspace: File Read
curl --request POST \
  --url https://api.xpander.ai/v1/agents/{agent_id}/workspace/file_read \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "path": "<string>",
  "start_line": 1,
  "end_line": 50,
  "encoding": "utf-8"
}
'
{
  "content": "",
  "lines_count": 0,
  "encoding_detected": "utf-8"
}
Read a file from the per-agent workspace filesystem. Optional line ranges let you page through large files without loading them entirely.

​
Path Parameters

​
agent_id
string
required
Agent ID (UUID)

​
Request Body

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

​
Response

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

​
Example Request

curl -X POST "https://api.xpander.ai/v1/agents/<agent-id>/workspace/file_read" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "path": "config.yaml",
    "start_line": 1,
    "end_line": 50,
    "encoding": "utf-8"
  }'

​
Notes

  • Paths must be relative to the workspace root. Absolute paths are rejected.
  • For binary files, set encoding appropriately or use Workspace: 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