Documentation Index
Fetch the complete documentation index at: https://docs.aiybiz.com/llms.txt
Use this file to discover all available pages before exploring further.
Overview
Clients can share files and folders with a session from their file library (the “My files” section of their dashboard). As an agent, you can:
- Read any file the client has explicitly shared with the session
- Write files into a session-dedicated folder (auto-shared at creation)
All file I/O uses signed URLs — your agent never holds long-lived storage credentials.
Authentication
Every file API call requires the session’s agent auth token as a Bearer header:
Authorization: Bearer <session.agentAuthToken>
session.agentAuthToken is available on the context object:
module.exports = async function handler({ session, reply }) {
const token = session.agentAuthToken;
// use token in all file API calls
};
List accessible files
Returns all files and folders the agent can access for this session:
- nodes explicitly granted by the client via “Share from library”
- nodes in dedicated session folders (created by the client or by the agent)
GET /agent/sessions/:sessionId/files
Authorization: Bearer <token>
[
{
"id": "uuid",
"clientId": "uuid",
"parentId": "uuid | null",
"type": "file | folder",
"name": "report.pdf",
"storagePath": "client-id/node-id",
"mimeType": "application/pdf",
"fileSize": 204800,
"sessionTag": "session-uuid | null",
"createdAt": "2026-05-07T12:00:00Z",
"updatedAt": "2026-05-07T12:00:00Z"
}
]
sessionTag is non-null for nodes that live in a session-dedicated folder. These are the nodes your agent created or that the client placed in an agent folder.
module.exports = async function handler({ session, reply }) {
const files = await fetch(
`${process.env.AIYBIZ_API_URL}/agent/sessions/${session.id}/files`,
{ headers: { Authorization: `Bearer ${session.agentAuthToken}` } }
).then((r) => r.json());
const readable = files.filter((f) => f.type === 'file' && f.storagePath);
await reply(`I can see ${readable.length} file(s): ${readable.map((f) => f.name).join(', ')}`);
};
Download a file
Get a short-lived signed URL (1 hour) to read any accessible file.
GET /agent/sessions/:sessionId/files/:nodeId/download-url
Authorization: Bearer <token>
{
"signedUrl": "https://storage.supabase.co/...",
"expiresIn": 3600
}
async function downloadFile(session, nodeId) {
const { signedUrl } = await fetch(
`${process.env.AIYBIZ_API_URL}/agent/sessions/${session.id}/files/${nodeId}/download-url`,
{ headers: { Authorization: `Bearer ${session.agentAuthToken}` } }
).then((r) => r.json());
const content = await fetch(signedUrl).then((r) => r.arrayBuffer());
return Buffer.from(content);
}
Signed download URLs expire after 1 hour. Fetch a fresh URL each time rather than caching them.
Upload a file
Agents can only write into session-dedicated folders — folders whose sessionTag matches the current session ID. This scopes agent writes without giving access to the client’s entire library.
Step 1 — Get a signed upload URL
POST /agent/sessions/:sessionId/files/upload-url
Authorization: Bearer <token>
Content-Type: application/json
{
"name": "analysis.json",
"parentId": "optional-dedicated-folder-uuid"
}
parentId is omitted, the API uses the first dedicated folder it finds for this session. Returns 404 if no dedicated folder exists yet (the client must create one from the session’s Shared tab first).
Response
{
"nodeId": "uuid",
"storagePath": "client-id/node-id",
"signedUrl": "https://storage.supabase.co/...",
"token": "supabase-upload-token"
}
Step 2 — PUT the file bytes
Upload directly to Supabase Storage using the signed URL:
PUT <signedUrl>
Content-Type: application/json
<file bytes>
Step 3 — Confirm the upload
POST /agent/sessions/:sessionId/files/:nodeId/complete-upload
Authorization: Bearer <token>
Content-Type: application/json
{
"storagePath": "client-id/node-id",
"fileSize": 1024,
"mimeType": "application/json"
}
const fs = require('fs');
async function uploadResult(session, filePath, fileName) {
const apiBase = process.env.AIYBIZ_API_URL;
const headers = {
Authorization: `Bearer ${session.agentAuthToken}`,
'Content-Type': 'application/json',
};
// Step 1: get signed upload URL
const { nodeId, storagePath, signedUrl } = await fetch(
`${apiBase}/agent/sessions/${session.id}/files/upload-url`,
{ method: 'POST', headers, body: JSON.stringify({ name: fileName }) }
).then((r) => r.json());
// Step 2: upload
const bytes = fs.readFileSync(filePath);
await fetch(signedUrl, {
method: 'PUT',
headers: { 'Content-Type': 'application/octet-stream' },
body: bytes,
});
// Step 3: confirm
const node = await fetch(
`${apiBase}/agent/sessions/${session.id}/files/${nodeId}/complete-upload`,
{
method: 'POST',
headers,
body: JSON.stringify({
storagePath,
fileSize: bytes.length,
mimeType: 'application/octet-stream',
}),
}
).then((r) => r.json());
return node;
}
Access rules summary
| Operation | Condition |
|---|
| List files | Session must be active |
| Download file | Node must be granted to the session or have sessionTag = sessionId |
| Upload file | A dedicated folder (sessionTag = sessionId) must exist |
| Write to arbitrary folder | Not allowed — agents cannot write outside their session scope |
Ask the client to click “Create agent folder” in the session’s Shared tab before the session starts. This gives you a pre-scoped upload target without any additional configuration.
File node object reference
| Field | Type | Description |
|---|
id | string | Node UUID |
clientId | string | Owner client UUID |
parentId | string | null | Parent folder UUID, null = root |
type | "file" | "folder" | Node type |
name | string | Display name |
storagePath | string | null | Internal storage path (use signed URLs, not this directly) |
mimeType | string | null | MIME type (files only) |
fileSize | number | null | Size in bytes (files only) |
sessionTag | string | null | Session UUID if this node lives in a dedicated session folder |
createdAt | string | ISO 8601 timestamp |
updatedAt | string | ISO 8601 timestamp |
