Orgo - Cloud computers for AI agents

POST

files

uploads

Start file upload

curl --request POST \
  --url https://www.orgo.ai/api/files/uploads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "desktopId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
  "filename": "data.csv",
  "size_bytes": 52428800,
  "destPath": "/root/Desktop"
}
'

import requests

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

payload = {
    "desktopId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
    "filename": "data.csv",
    "size_bytes": 52428800,
    "destPath": "/root/Desktop"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    desktopId: 'a3bb189e-8bf9-3888-9912-ace4e6543002',
    filename: 'data.csv',
    size_bytes: 52428800,
    destPath: '/root/Desktop'
  })
};

fetch('https://www.orgo.ai/api/files/uploads', 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/uploads",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'desktopId' => 'a3bb189e-8bf9-3888-9912-ace4e6543002',
    'filename' => 'data.csv',
    'size_bytes' => 52428800,
    'destPath' => '/root/Desktop'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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/uploads"

	payload := strings.NewReader("{\n  \"desktopId\": \"a3bb189e-8bf9-3888-9912-ace4e6543002\",\n  \"filename\": \"data.csv\",\n  \"size_bytes\": 52428800,\n  \"destPath\": \"/root/Desktop\"\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	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/uploads")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"desktopId\": \"a3bb189e-8bf9-3888-9912-ace4e6543002\",\n  \"filename\": \"data.csv\",\n  \"size_bytes\": 52428800,\n  \"destPath\": \"/root/Desktop\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"desktopId\": \"a3bb189e-8bf9-3888-9912-ace4e6543002\",\n  \"filename\": \"data.csv\",\n  \"size_bytes\": 52428800,\n  \"destPath\": \"/root/Desktop\"\n}"

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

{
  "upload_url": "https://objects.example.com/…",
  "method": "PUT",
  "expires_in": 900,
  "upload_token": "eyJ1Ijoi…",
  "next": "PUT exactly 52428800 bytes to upload_url (for example: curl -T <file> '<upload_url>'), then call POST /api/files/uploads/complete with desktopId and upload_token."
}

Step one of the two-step upload, for files up to 2 GB. It returns a signed URL and an upload_token. PUT the file’s bytes to the URL, then call Complete large upload to have the computer pull the file into place. The bytes go straight to storage and never pass through Orgo’s API. The file lands on one computer only. No file record is written, so it does not appear in the list endpoint. For files up to 10 MB that should be stored in the workspace, use Upload file.

Request

Send a JSON body.

string

required

Computer ID (UUID) the file goes to. The computer does not need to be running yet. It must be running when you complete the upload.

string

required

Name the file will have on the computer. A plain name only: no / or \, not . or .., at most 255 characters.

integer

required

Exact size of the file in bytes, from 1 to 2147483648 (2 GB). The signed URL accepts a body of exactly this size and no other.

string

Absolute folder on the computer, such as /root/Documents or, on Windows, C:\Users\Public. Omit it, or send desktop, for the desktop folder of the computer’s user. On Linux, a folder that does not exist is created.

Response

string

Signed URL to PUT the file’s bytes to. Send exactly size_bytes bytes.

string

Always PUT.

integer

Seconds the upload_url stays valid: 900 (15 minutes).

string

Pass it to Complete large upload. It is valid for one hour and only for the same caller and computer.

string

A one-line reminder of the next two steps.

Example

SIZE=$(wc -c < ./dataset.zip | tr -d ' ')

START=$(curl -s -X POST https://www.orgo.ai/api/files/uploads \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"desktopId\": \"$COMPUTER_ID\", \"filename\": \"dataset.zip\", \"size_bytes\": $SIZE, \"destPath\": \"/root/Documents\"}")

curl -T ./dataset.zip "$(echo "$START" | jq -r .upload_url)"

curl -X POST https://www.orgo.ai/api/files/uploads/complete \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"desktopId\": \"$COMPUTER_ID\", \"upload_token\": \"$(echo "$START" | jq -r .upload_token)\"}"

import os
import requests

headers = {"Authorization": f"Bearer {os.environ['ORGO_API_KEY']}"}
computer_id = os.environ["COMPUTER_ID"]

start = requests.post(
    "https://www.orgo.ai/api/files/uploads",
    headers=headers,
    json={
        "desktopId": computer_id,
        "filename": "dataset.zip",
        "size_bytes": os.path.getsize("dataset.zip"),
        "destPath": "/root/Documents",
    },
).json()

with open("dataset.zip", "rb") as f:
    requests.put(start["upload_url"], data=f).raise_for_status()

done = requests.post(
    "https://www.orgo.ai/api/files/uploads/complete",
    headers=headers,
    json={"desktopId": computer_id, "upload_token": start["upload_token"]},
)
print(done.json())

Response

{
  "upload_url": "https://objects.example.com/…",
  "method": "PUT",
  "expires_in": 900,
  "upload_token": "eyJ1Ijoi…",
  "next": "PUT exactly 52428800 bytes to upload_url (for example: curl -T <file> '<upload_url>'), then call POST /api/files/uploads/complete with desktopId and upload_token."
}

Errors

Every error carries the shape {"error": "<message>"}. The scope-mismatch 403 adds code, key_workspace_id, and target_workspace_id. The checks below run in order.

Status	Body	Cause
`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.
`400`	`{"error": "desktopId is required"}`	`desktopId` was absent or empty.
`400`	`{"error": "filename must be a plain file name"}`	`filename` was absent, empty, too long, `.` or `..`, or contained a slash, a backslash or a null byte.
`400`	`{"error": "size_bytes must be the file size in bytes"}`	`size_bytes` was absent or not a positive integer.
`413`	`{"error": "File is 3221225472 bytes; the limit is 2147483648. Split or compress it first."}`	`size_bytes` is above 2 GB.
`400`	`{"error": "destPath must be an absolute folder on the computer"}`	`destPath` is not absolute, contains a null byte, or is longer than 4096 characters. Also returned when the path’s form does not match the computer’s OS.
`404`	`{"error": "Desktop not found"}`	No computer has that ID. A `desktopId` that is not a UUID returns `500` instead.
`403`	`{"error": "Access denied"}`	The caller neither owns the computer’s workspace nor belongs to it, or has view-only access to it.
`402`	`{"error": "Choose a plan to continue."}`	The computer is a free trial computer that can no longer run.
`402`	`{"error": "Manage this computer’s payment in Account → Usage."}`	The computer is paid for by its own subscription or dedicated purchase, and that payment has lapsed.
`403`	`{"error": "…", "code": "workspace_scope_mismatch", "key_workspace_id": "…", "target_workspace_id": "…"}`	A workspace-scoped key named a computer in a different workspace.
`500`	`{"error": "Could not start the upload"}`	Unexpected failure.

Authorizations

Authorization

string

header

required

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

Body

application/json

desktopId

string

required

Computer ID.

filename

string

required

A plain file name, no folders.

size_bytes

integer

required

The file's exact size in bytes. Up to 2 GB.

Required range: 1 <= x <= 2147483648

destPath

string

Absolute folder on the computer to place it in. Omitted or desktop: the desktop folder of the computer's user.

Response

Where to send the bytes, and the token to finish with.

upload_url

string

Signed URL to PUT the bytes to. Works for 15 minutes.

method

enum<string>

Available options:

PUT

expires_in

integer

Seconds upload_url works (900).

upload_token

string

Send it to POST /files/uploads/complete. Works for one hour.

string

What to do next, in words.

Start file upload

curl --request POST \
  --url https://www.orgo.ai/api/files/uploads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "desktopId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
  "filename": "data.csv",
  "size_bytes": 52428800,
  "destPath": "/root/Desktop"
}
'

import requests

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

payload = {
    "desktopId": "a3bb189e-8bf9-3888-9912-ace4e6543002",
    "filename": "data.csv",
    "size_bytes": 52428800,
    "destPath": "/root/Desktop"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    desktopId: 'a3bb189e-8bf9-3888-9912-ace4e6543002',
    filename: 'data.csv',
    size_bytes: 52428800,
    destPath: '/root/Desktop'
  })
};

fetch('https://www.orgo.ai/api/files/uploads', 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/uploads",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'desktopId' => 'a3bb189e-8bf9-3888-9912-ace4e6543002',
    'filename' => 'data.csv',
    'size_bytes' => 52428800,
    'destPath' => '/root/Desktop'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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/uploads"

	payload := strings.NewReader("{\n  \"desktopId\": \"a3bb189e-8bf9-3888-9912-ace4e6543002\",\n  \"filename\": \"data.csv\",\n  \"size_bytes\": 52428800,\n  \"destPath\": \"/root/Desktop\"\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	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/uploads")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"desktopId\": \"a3bb189e-8bf9-3888-9912-ace4e6543002\",\n  \"filename\": \"data.csv\",\n  \"size_bytes\": 52428800,\n  \"destPath\": \"/root/Desktop\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"desktopId\": \"a3bb189e-8bf9-3888-9912-ace4e6543002\",\n  \"filename\": \"data.csv\",\n  \"size_bytes\": 52428800,\n  \"destPath\": \"/root/Desktop\"\n}"

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

{
  "upload_url": "https://objects.example.com/…",
  "method": "PUT",
  "expires_in": 900,
  "upload_token": "eyJ1Ijoi…",
  "next": "PUT exactly 52428800 bytes to upload_url (for example: curl -T <file> '<upload_url>'), then call POST /api/files/uploads/complete with desktopId and upload_token."
}

Overview

Account

Agent accounts

Clients

Computer Use API

Workspaces

Computers

Computer Lifecycle

Computer Actions

Screens

Files

Templates

Start large upload

Request

Response

Example

Response

Errors

Authorizations

Body

Response

​Request

​Response

​Example

​Response

​Errors

Authorizations

Body

Response

Request

Response

Example

Response

Errors