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": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
    "project_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"
  }
}

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, such as /root/Documents or, on Windows, C:\Users\Public. The literal value desktop means the desktop folder of the computer’s user, which the computer resolves itself. 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. On Linux, a folder that does not exist is created. 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

The same value as workspace_id, under the workspace’s older name. Read workspace_id in new code.

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.

string

Size in bytes as a decimal string, such as "102400". The value is a 64-bit integer, so it is serialized as a string.

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']})")

import { openAsBlob } from 'node:fs';

const formData = new FormData();
formData.append('file', await openAsBlob('document.pdf'), '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",
    "project_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 the desktop folder (/root/Desktop on Linux) of 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 in the background without being awaited, 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 that folder 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

The folder the file was placed in: your destPath with surrounding whitespace trimmed, or the desktop when you sent desktop. The file name is not appended.

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,
  "placedIn": "/root/Documents"
}

Errors

Every error carries an error message. The scope-mismatch 403 adds code, key_workspace_id, and target_workspace_id.

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` was neither `desktop` nor an absolute path (starting with `/`, or with a drive letter such as `C:\`), or it 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.
`401`	`{"error": "Service temporarily unavailable. …"}`	Orgo could not verify the credential because of a server-side fault. Retry.
`403`	`{"error": "…", "code": "workspace_scope_mismatch", "key_workspace_id": "…", "target_workspace_id": "…"}`	A workspace-scoped key named a different workspace.
`403`	`{"error": "Access denied"}`	The caller neither owns the workspace nor has write access to it. A view-only member gets this too, and so does a workspace ID that does not exist. 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 did not confirm it had written the file, or the request to it failed or ran past 130 seconds.
`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

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. It must be an absolute path, starting with / or with a drive letter such as C:\ or C:/ (for example C:\Users\Public on Windows), or the literal desktop, which places the file in the desktop folder of the computer's user. Anything else returns 400. 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

The stored file record: every column of the row, plus workspace_id.

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": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
    "project_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"
  }
}

Overview

Account

Clients

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