Files

A File in Orca Agent Engine is a binary asset stored in the registry. Sessions reference files as resources so the agent can read them at runtime - PDFs to summarize, datasets to analyze, images to caption. Files are uploaded once and referenced by ID from any number of sessions.

Get your registry endpoint

Upload a file

Upload a file with a multipart POST to /v1/files. The request takes exactly one part, file, carrying the binary. There is no content-type field in the body: the stored mime_type comes from that part's own Content-Type header, and falls back to application/octet-stream when the client does not set one.

file=$(ork agent files create \
  --file /path/to/report.pdf \
  --content-type application/pdf \
  -o json)

FILE_ID=$(jq -r '.id' <<< "$file")

A successful upload returns 200 OK with the file's metadata:

{
  "id": "file_01H8...",
  "created_at": "2026-05-11T17:24:08Z",
  "filename": "report.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 124378,
  "type": "file",
  "downloadable": false,
  "scope": null
}

$FILE_ID is how you reference the file from a session. downloadable is false on material you upload, and scope is null because the file belongs to the Workspace rather than to a single session.

Mount files in a session

To make a file available to an agent, list it in the session's resources array at create time. Each resource entry sets type: "file" and the file_id you got from upload.

$AGENT_ID is the id of an agent and $ENVIRONMENT_ID the id of an environment; both are required on session create. $SESSION_ID is the id of a session. The additional file IDs below come from repeating the upload above.

curl -fsS "$ORCA_REGISTRY_URL/v1/sessions" \
  -H "Authorization: Bearer $ORCA_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "'"$AGENT_ID"'",
    "environment_id": "'"$ENVIRONMENT_ID"'",
    "resources": [
      { "type": "file", "file_id": "'"$FILE_ID"'" }
    ]
  }'

The runtime mounts the file inside the session's container at a stable path under the session's resource root. The agent reads it as it would any local file.

Multiple files

To mount more than one file, add additional entries to resources.

FRONTEND_FILE_ID=$(curl -fsS -X POST "$ORCA_REGISTRY_URL/v1/files" \
  -H "Authorization: Bearer $ORCA_ACCESS_TOKEN" \
  -F "file=@/path/to/frontend.csv" | jq -r '.id')

BACKEND_FILE_ID=$(curl -fsS -X POST "$ORCA_REGISTRY_URL/v1/files" \
  -H "Authorization: Bearer $ORCA_ACCESS_TOKEN" \
  -F "file=@/path/to/backend.csv" | jq -r '.id')

curl -fsS "$ORCA_REGISTRY_URL/v1/sessions" \
  -H "Authorization: Bearer $ORCA_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "'"$AGENT_ID"'",
    "environment_id": "'"$ENVIRONMENT_ID"'",
    "resources": [
      { "type": "file", "file_id": "'"$FRONTEND_FILE_ID"'" },
      { "type": "file", "file_id": "'"$BACKEND_FILE_ID"'" }
    ]
  }'

Each file gets its own path inside the session. The agent can be told about the mounted files in its system prompt or through a user.message.

Manage files on a running session

Add a resource to a running session:

curl -fsS -X POST "$ORCA_REGISTRY_URL/v1/sessions/$SESSION_ID/resources" \
  -H "Authorization: Bearer $ORCA_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "file",
    "file_id": "'"$FILE_ID"'"
  }'

Every resource on a session has its own id. List them to find the one you want to change:

resources=$(curl -fsS "$ORCA_REGISTRY_URL/v1/sessions/$SESSION_ID/resources?limit=20" \
  -H "Authorization: Bearer $ORCA_ACCESS_TOKEN")

RESOURCE_ID=$(jq -r '.data[0].id' <<< "$resources")

Remove a resource:

curl -fsS -X DELETE "$ORCA_REGISTRY_URL/v1/sessions/$SESSION_ID/resources/$RESOURCE_ID" \
  -H "Authorization: Bearer $ORCA_ACCESS_TOKEN"

A resource cannot be repointed at a different file. The registry does update resources in place - it uses POST (not PUT or PATCH) on the resource ID, mirroring the underlying agent provider's API - but the update body carries resource settings, not a new target. It has no file_id field, so a body of just {"file_id": "..."} is rejected with 400 at least one resource field must be provided.

To swap the file a session reads, detach the resource and add one for the new file ID. $NEW_FILE_ID comes from another upload:

curl -fsS -X DELETE "$ORCA_REGISTRY_URL/v1/sessions/$SESSION_ID/resources/$RESOURCE_ID" \
  -H "Authorization: Bearer $ORCA_ACCESS_TOKEN"

curl -fsS -X POST "$ORCA_REGISTRY_URL/v1/sessions/$SESSION_ID/resources" \
  -H "Authorization: Bearer $ORCA_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "file",
    "file_id": "'"$NEW_FILE_ID"'"
  }'

List and download session files

List all files in the Workspace:

ork agent files list

Retrieve a single file's metadata:

ork agent files get $FILE_ID

Delete a file from the registry. After delete, sessions that reference the file surface an error on next read.

curl -fsS -X DELETE "$ORCA_REGISTRY_URL/v1/files/$FILE_ID" \
  -H "Authorization: Bearer $ORCA_ACCESS_TOKEN"

Limits and file types

The registry does not restrict content types. mime_type is read from the uploaded part's Content-Type header and defaults to application/octet-stream. Set it accurately on the part - -F "file=@report.pdf;type=application/pdf" with curl, or a typed File/Blob through the SDK's toFile. It is what tells the agent whether it is looking at a PDF, a CSV, or an opaque blob, and an agent that has to guess from the extension guesses worse.

File paths

• The session mounts each resource at a stable path under the session's resource root.
• File contents are read-only from the agent's perspective. To replace a file, upload a new file, then detach the old resource and add one for the new file ID.
• Files are scoped to the Workspace - they're visible to any session in the Workspace whose creator has the relevant permissions.
• Uploads are not readable back through the API by default. GET /v1/files/{id}/content serves only files marked downloadable, which covers agent output rather than material you supplied.

Permissions

Treat every Workspace API key as full access to its Workspace's resources, and separate access with Workspaces. See Control registry access.

What's next