Files
Read a file
Read a file from a cloud browser’s machine, base64-encoded.
POST
/
api
/
v2
/
sessions
/
{session_id}
/
files
/
read_file
import base64
from hai_agents import Client
client = Client()
file = client.session_files.read_file(session_id, path="~/Downloads/invoice-2026-09.pdf")
with open("invoice-2026-09.pdf", "wb") as out:
out.write(base64.b64decode(file.content_base64))
import { writeFileSync } from "node:fs";
import { HaiAgentsClient } from "hai-agents";
const client = new HaiAgentsClient();
const file = await client.sessionFiles.readFile({
sessionId,
path: "~/Downloads/invoice-2026-09.pdf",
});
writeFileSync("invoice-2026-09.pdf", Buffer.from(file.contentBase64, "base64"));
curl -X POST https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID/files/read_file \
-H "Authorization: Bearer $HAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"path": "~/Downloads/invoice-2026-09.pdf"}' \
| jq -r .content_base64 | base64 -d > invoice-2026-09.pdf
{
"path": "/home/hai/Downloads/invoice-2026-09.pdf",
"content_base64": "JVBERi0xLjcKJc...",
"size_bytes": 48213,
"modified_at": "2026-09-15T09:41:12Z"
}
Behavior
Files over 8 MiB are rejected. Only~/Downloads is reachable, while the cloud browser runs.
Path parameters
string
required
The agent session ID, or the browser session ID from its
RunnerSessionEvent.Request body
string
required
File to read. Absolute, or relative to the browser’s home (
~/Downloads/report.csv).Response
200 with the file.
string
The file’s resolved path.
string
The file’s bytes, base64-encoded.
integer
Size of the file in bytes.
string
ISO 8601 modification time.
import base64
from hai_agents import Client
client = Client()
file = client.session_files.read_file(session_id, path="~/Downloads/invoice-2026-09.pdf")
with open("invoice-2026-09.pdf", "wb") as out:
out.write(base64.b64decode(file.content_base64))
import { writeFileSync } from "node:fs";
import { HaiAgentsClient } from "hai-agents";
const client = new HaiAgentsClient();
const file = await client.sessionFiles.readFile({
sessionId,
path: "~/Downloads/invoice-2026-09.pdf",
});
writeFileSync("invoice-2026-09.pdf", Buffer.from(file.contentBase64, "base64"));
curl -X POST https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID/files/read_file \
-H "Authorization: Bearer $HAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"path": "~/Downloads/invoice-2026-09.pdf"}' \
| jq -r .content_base64 | base64 -d > invoice-2026-09.pdf
{
"path": "/home/hai/Downloads/invoice-2026-09.pdf",
"content_base64": "JVBERi0xLjcKJc...",
"size_bytes": 48213,
"modified_at": "2026-09-15T09:41:12Z"
}
Errors
| Status | Cause |
|---|---|
403 | Path outside ~/Downloads, or not a file. |
404 | File not found, or no browser session with this id. |
413 | File over 8 MiB. |
Was this page helpful?
⌘I
import base64
from hai_agents import Client
client = Client()
file = client.session_files.read_file(session_id, path="~/Downloads/invoice-2026-09.pdf")
with open("invoice-2026-09.pdf", "wb") as out:
out.write(base64.b64decode(file.content_base64))
import { writeFileSync } from "node:fs";
import { HaiAgentsClient } from "hai-agents";
const client = new HaiAgentsClient();
const file = await client.sessionFiles.readFile({
sessionId,
path: "~/Downloads/invoice-2026-09.pdf",
});
writeFileSync("invoice-2026-09.pdf", Buffer.from(file.contentBase64, "base64"));
curl -X POST https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID/files/read_file \
-H "Authorization: Bearer $HAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"path": "~/Downloads/invoice-2026-09.pdf"}' \
| jq -r .content_base64 | base64 -d > invoice-2026-09.pdf
{
"path": "/home/hai/Downloads/invoice-2026-09.pdf",
"content_base64": "JVBERi0xLjcKJc...",
"size_bytes": 48213,
"modified_at": "2026-09-15T09:41:12Z"
}