Skip to main content
POST
/
v1
/
agents
/
{agent_id}
/
workspace
/
bash
Workspace: Bash
curl --request POST \
  --url https://api.xpander.ai/v1/agents/{agent_id}/workspace/bash \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "command": "ls -la",
  "timeout": 300,
  "working_dir": ""
}
'
{
  "status": "ok",
  "stdout": "<string>",
  "stderr": "<string>",
  "exit_code": 123,
  "content": "<string>",
  "path": "<string>",
  "matches": [
    {}
  ],
  "url": "<string>",
  "error": "<string>"
}
Run a shell command inside the per-agent workspace.

​
Path Parameters

​
agent_id
string
required
Agent ID (UUID)

​
Request Body

​
command
string
required
Shell command to execute inside the workspace.
​
timeout
integer
default:300
Maximum execution time in seconds before the command is terminated.
​
working_dir
string
Optional working directory for the command. Defaults to the workspace root when empty.

​
Response

​
status
string
Result status of the operation (e.g., ok).
​
stdout
string
Standard output captured from the command.
​
stderr
string
Standard error captured from the command.
​
exit_code
integer
Process exit code.

​
Example Request

curl -X POST "https://api.xpander.ai/v1/agents/<agent-id>/workspace/bash" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "command": "ls -la",
    "timeout": 300,
    "working_dir": ""
  }'

​
Notes

  • The workspace is per-agent and persists between calls, so files created here remain available to subsequent workspace operations for the same agent.
  • Commands are run as an unprivileged user. Avoid commands that require elevated permissions.

​
See Also

Authorizations

​
x-api-key
string
header
required

API Key for authentication

Path Parameters

​
agent_id
string
required

Agent UUID

Body

application/json

Request body for running a bash command inside the agent workspace.

​
command
string
required

Shell command to execute inside the workspace.

Example:

"ls -la"

​
timeout
integer
default:300

Maximum execution time in seconds before the command is terminated.

Required range: x >= 1
​
working_dir
string
default:""

Optional working directory for the command. Defaults to the workspace root when empty.

Response

Successful Response

Generic response wrapper returned by agent workspace endpoints. Not every field is populated for every tool.

​
status
string

Result status of the workspace operation.

Example:

"ok"

​
stdout
string | null

Standard output captured from the workspace command. Present for bash.

​
stderr
string | null

Standard error captured from the workspace command. Present for bash.

​
exit_code
integer | null

Process exit code returned by the workspace. Present for bash.

​
content
string | null

File contents. Present for file_read.

​
path
string | null

File path affected by the operation. Present for file_write, file_edit, multi_edit, file_share.

​
matches
Matches · object[] | null

Match results. Present for glob and grep.

​
url
string<uri> | null

Public CDN URL. Present for file_share.

​
error
string | null

Error message when the operation fails.