Orgo - Cloud computers for AI agents

POST

files

upload

Upload file

curl --request POST \
  --url https://www.orgo.ai/api/files/upload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file' \
  --form 'workspaceId=<string>' \
  --form 'desktopId=<string>' \
  --form destPath=/root/Desktop

import requests

url = "https://www.orgo.ai/api/files/upload"

files = { "file": ("example-file", open("example-file", "rb")) }
payload = {
    "workspaceId": "<string>",
    "desktopId": "<string>",
    "destPath": "/root/Desktop"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('file', '<string>');
form.append('workspaceId', '<string>');
form.append('desktopId', '<string>');
form.append('destPath', '/root/Desktop');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://www.orgo.ai/api/files/upload', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.orgo.ai/api/files/upload",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"workspaceId\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"desktopId\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"destPath\"\r\n\r\n/root/Desktop\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.orgo.ai/api/files/upload"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"workspaceId\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"desktopId\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"destPath\"\r\n\r\n/root/Desktop\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://www.orgo.ai/api/files/upload")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"workspaceId\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"desktopId\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"destPath\"\r\n\r\n/root/Desktop\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.orgo.ai/api/files/upload")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"workspaceId\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"desktopId\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"destPath\"\r\n\r\n/root/Desktop\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "file": {
    "id": "f1a2b3c4-0000-4000-8000-000000000001",
    "filename": "report.csv",
    "size_bytes": 20481,
    "content_type": "text/csv",
    "created_at": "2026-04-07T10:40:00Z"
  }
}

Uploads a file to a workspace and pushes it to the computers that are running at that moment. Passing destPath switches the endpoint to a second mode. That mode drops the file into one exact folder on one computer and records nothing. The two modes return different bodies. See Folder-targeted upload.

Request

Send a multipart/form-data request.

file

required

The file to upload. Maximum 10MB. A larger file returns 400. The name is preserved as filename. The copy in object storage is keyed under a sanitised form of it.

string

required

Workspace ID to upload into. Omitting it returns 400.

string

Computer ID to associate the file with. When omitted, the file is recorded against the workspace with a desktop_id of null. Association does not change where the file is pushed. Every running computer in the workspace receives it either way. Required when destPath is set.

string

Absolute folder path on the computer. Must begin with /. When set, the file is placed at <destPath>/<file name> on the computer named by desktopId, and nothing else happens: no file record is written, no other computer receives it, and the response body is different. When omitted, the file is stored in the workspace and pushed to running computers.

Response

Without destPath, the whole stored row is returned under file.

object

The stored file record.

string

File ID. Pass it as id to the download and delete endpoints.

string

Workspace the file belongs to.

string | null

The desktopId you supplied, or null.

string

ID of the account that uploaded the file.

string

Original file name.

string

Internal object-storage key. It is not a URL and cannot be fetched directly. Use the download endpoint to get a signed URL.

integer

Size in bytes.

string

MIME type reported by the client, or application/octet-stream when the client sent none.

string

ISO 8601 creation timestamp.

string

Always upload for this endpoint.

Example

curl -X POST https://www.orgo.ai/api/files/upload \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -F "file=@./document.pdf" \
  -F "workspaceId=$WORKSPACE_ID" \
  -F "desktopId=$COMPUTER_ID"

import os
import requests

with open("document.pdf", "rb") as f:
    response = requests.post(
        "https://www.orgo.ai/api/files/upload",
        headers={"Authorization": f"Bearer {os.environ['ORGO_API_KEY']}"},
        files={"file": f},
        data={
            "workspaceId": os.environ["WORKSPACE_ID"],
            "desktopId": os.environ["COMPUTER_ID"],  # optional
        },
    )

file_info = response.json()["file"]
print(f"Uploaded: {file_info['filename']} ({file_info['id']})")

const formData = new FormData();
formData.append('file', fileBlob, 'document.pdf');
formData.append('workspaceId', process.env.WORKSPACE_ID);
formData.append('desktopId', process.env.COMPUTER_ID); // optional

const response = await fetch('https://www.orgo.ai/api/files/upload', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.ORGO_API_KEY}` },
  body: formData,
});

const { file } = await response.json();
console.log(`Uploaded: ${file.filename} (${file.id})`);

Response

{
  "file": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
    "desktop_id": "a3bb189e-8bf9-3888-9912-ace4e6543002",
    "user_id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
    "filename": "document.pdf",
    "storage_key": "550e8400-e29b-41d4-a716-446655440000/uploads/1705314600000-document.pdf",
    "size_bytes": 102400,
    "content_type": "application/pdf",
    "created_at": "2024-01-15T10:30:00Z",
    "source": "upload"
  }
}

How the file reaches a computer

The file is stored in the workspace and pushed to /root/Desktop on every computer that is running at the time of upload. Computers that are stopped, or created afterwards, do not receive it. Upload again to reach them. The push is best-effort and runs after the response is sent, so it does not affect the status you get back.

Each push sends the workspace’s full set of uploaded files. A computer skips any file whose name already exists in /root/Desktop rather than overwriting it.

Folder-targeted upload

Setting destPath places the file at one exact path on one computer. The response is a different shape and no file record is created. The file does not appear in the list endpoint, and it cannot be downloaded or deleted through this API.

boolean

true when the file was placed on the computer.

string

Full path the file was written to, formed as <destPath>/<file name>.

cURL

curl -X POST https://www.orgo.ai/api/files/upload \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -F "file=@./document.pdf" \
  -F "workspaceId=$WORKSPACE_ID" \
  -F "desktopId=$COMPUTER_ID" \
  -F "destPath=/root/Documents"

{
  "ok": true,
  "path": "/root/Documents/document.pdf"
}

Errors

Every error carries the shape {"error": "<message>"}.

Status	Body	Cause
`400`	`{"error": "No file provided"}`	The `file` part was absent.
`400`	`{"error": "workspaceId is required"}`	The `workspaceId` field was absent.
`400`	`{"error": "File too large (max 10MB)"}`	The file exceeded 10MB.
`400`	`{"error": "destPath requires desktopId"}`	`destPath` was set without `desktopId`.
`400`	`{"error": "Invalid destination folder"}`	`destPath` did not begin with `/`, or contained a null byte.
`400`	`{"error": "Invalid file name"}`	The file name resolved to nothing, `.`, or `..`.
`401`	`{"error": "Invalid API key"}`	The Bearer token starts with `sk_` but is not a known Orgo key.
`401`	`{"error": "Authentication required"}`	No `Authorization` header, or a Bearer token that is not an `sk_` key.
`403`	`{"error": "Access denied"}`	The caller neither owns the workspace nor belongs to it. A workspace ID that does not exist also returns 403. This endpoint never returns 404.
`500`	`{"error": "Failed to save file"}`	The upload reached storage but no file record came back.
`500`	`{"error": "Upload failed"}`	The upload failed. The message may instead carry the underlying error.
`502`	`{"error": "Could not place document.pdf in /root/Documents."}`	`destPath` mode only. The computer was reached but did not confirm it had written the file.
`503`	`{"error": "Computer could not be reached."}`	`destPath` mode only. The computer is not addressable: it has no connection details, or `desktopId` names no computer in this workspace.

Authorizations

Authorization

string

header

required

API key authentication. Get your key at orgo.ai/workspaces

Body

multipart/form-data

file

required

File to upload (max 10MB)

workspaceId

string

required

Workspace ID. Required; omitting it is a 400.

desktopId

string

Computer to associate the file with. Omitted, the file belongs to the workspace and is synced to every running computer in it. Required when you send destPath.

destPath

string

Absolute folder on the computer to place the file in. Sending it changes what the endpoint does: no file record is written, nothing is synced, and the bytes are pulled straight into that folder on the computer named by desktopId. Must start with /. Omitted, the file is stored against the workspace and synced to its running computers.

Example:

"/root/Desktop"

Response

File uploaded. destPath requests answer with the placement result instead of a file record.

Option 1
Option 2

file

object

Show child attributes

Upload file

curl --request POST \
  --url https://www.orgo.ai/api/files/upload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file' \
  --form 'workspaceId=<string>' \
  --form 'desktopId=<string>' \
  --form destPath=/root/Desktop

import requests

url = "https://www.orgo.ai/api/files/upload"

files = { "file": ("example-file", open("example-file", "rb")) }
payload = {
    "workspaceId": "<string>",
    "desktopId": "<string>",
    "destPath": "/root/Desktop"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('file', '<string>');
form.append('workspaceId', '<string>');
form.append('desktopId', '<string>');
form.append('destPath', '/root/Desktop');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://www.orgo.ai/api/files/upload', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.orgo.ai/api/files/upload",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"workspaceId\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"desktopId\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"destPath\"\r\n\r\n/root/Desktop\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.orgo.ai/api/files/upload"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"workspaceId\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"desktopId\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"destPath\"\r\n\r\n/root/Desktop\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://www.orgo.ai/api/files/upload")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"workspaceId\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"desktopId\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"destPath\"\r\n\r\n/root/Desktop\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.orgo.ai/api/files/upload")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"workspaceId\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"desktopId\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"destPath\"\r\n\r\n/root/Desktop\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "file": {
    "id": "f1a2b3c4-0000-4000-8000-000000000001",
    "filename": "report.csv",
    "size_bytes": 20481,
    "content_type": "text/csv",
    "created_at": "2026-04-07T10:40:00Z"
  }
}

Overview

Computer Use API

Workspaces

Computers

Computer Lifecycle

Computer Actions

Screens

Files

Templates

Upload file

Request

Response

Example

Response

How the file reaches a computer

Folder-targeted upload

Errors

Authorizations

Body

Response

​Request

​Response

​Example

​Response

​How the file reaches a computer

​Folder-targeted upload

​Errors

Authorizations

Body

Response

Request

Response

Example

Response

How the file reaches a computer

Folder-targeted upload

Errors