Orgo - Cloud computers for AI agents

POST

computers

{id}

stop

Stop computer

curl --request POST \
  --url https://www.orgo.ai/api/computers/{id}/stop \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "async": false
}'

import requests

url = "https://www.orgo.ai/api/computers/{id}/stop"

payload = { "async": False }
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({async: false})
};

fetch('https://www.orgo.ai/api/computers/{id}/stop', 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/computers/{id}/stop",
  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([
    'async' => false
  ]),
  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/computers/{id}/stop"

	payload := strings.NewReader("{\n  \"async\": false\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/computers/{id}/stop")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"async\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.orgo.ai/api/computers/{id}/stop")

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  \"async\": false\n}"

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

{
  "success": true
}

Stops a running computer. Its disk is archived to object storage, so files, installed software, and configuration are all kept. Its host and IP are released, so a stopped computer costs no compute. A successful stop leaves the computer in status frozen. That is the value GET /computers/{id} reports afterwards, and the state start restores from.

The archive is written and verified before the computer is torn down. If the response is lost or finalization fails, check the operation status: needs_review means the result must be reconciled before retrying. A stopped computer has no instance_id until it is started again, so address it by UUID. On start it gets a new instance_id and can land on a different host with a different address and ports. Processes and other in-memory state are not preserved. Only the disk survives.

Path parameters

string

required

Computer UUID or instance_id. Both resolve to the same computer.

Query parameters

string

default:"false"

true or false. true returns 202 immediately instead of waiting, as described in Return immediately and poll. Any other value returns 400.

Response

boolean

true when the computer was stopped, or was already frozen.

Stopping is idempotent only for a computer that is already frozen. Any other non-running status returns 409 rather than succeeding. That includes stopped, which Orgo records when a computer’s virtual machine has stopped or is gone from its host. Only Linux and Windows computers can be stopped. Any other operating system, or a physical device, returns 400 with code STOP_UNSUPPORTED.

Example

curl -X POST https://www.orgo.ai/api/computers/$COMPUTER_ID/stop \
  -H "Authorization: Bearer $ORGO_API_KEY"

import requests

response = requests.post(
    f"https://www.orgo.ai/api/computers/{computer_id}/stop",
    headers={"Authorization": f"Bearer {api_key}"}
)

if response.json().get("success"):
    print("Computer stopped")

const response = await fetch(`https://www.orgo.ai/api/computers/${computerId}/stop`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${apiKey}` }
});

const { success } = await response.json();
if (success) console.log('Computer stopped');

Response

{
  "success": true
}

Errors

Status	Body	When
`400`	`{ "error": "…", "code": "STOP_UNSUPPORTED" }`	The computer’s operating system or hardware cannot be archived. `code` is `DEVICE_LIFECYCLE_UNSUPPORTED` for a device Orgo manages directly.
`400`	`{ "error": "Expected a JSON object with an optional boolean async field." }`	The body is not empty and is not a JSON object with an optional boolean `async`.
`400`	`{ "error": "async must be true or false" }`	The `async` query parameter is neither `true` nor `false`.
`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.
`402`	`{ "error": "Choose a plan to archive this computer.", "code": "TRIAL_ARCHIVE_UNAVAILABLE" }`	The computer is a trial computer.
`402`	`{ "error": "Choose a plan to continue." }`	The computer is a trial computer whose trial has ended.
`403`	`{ "error": "You do not have access to this workspace." }`	You are not a member of the computer’s workspace.
`403`	`{ "error": "This workspace is view-only. Ask the owner for write access (workspace_read_only)." }`	You have view-only access to the workspace.
`403`	`{ "error": "This API key cannot access this workspace (workspace_scope_mismatch)." }`	The API key is scoped to a different workspace.
`404`	`{ "error": "Desktop not found" }`	No computer matches the id.
`409`	`{ "error": "Computer is not running (status: stopped)", "code": "not_stoppable" }`	The computer is in any non-`running` status other than `frozen`.
`409`	`{ "error": "…", "code": "migrating" }`	The computer is being moved to another host. Retry in a few minutes.
`409`	`{ "error": "A different operation is already in progress.", "code": "OPERATION_IN_PROGRESS" }`	A start is still pending for this computer.
`409`	`{ "error": "The previous operation was interrupted and is being checked. Try again in a few minutes.", "code": "OPERATION_NEEDS_REVIEW" }`	An earlier start or stop is in `needs_review`.
`500`	`{ "error": "…", "code": "…" }`	The archive or teardown failed. Check the operation status before retrying; an uncertain result is fenced as `needs_review`.
`503`	`{ "error": "Computer not ready. VMM has not assigned a server yet", "code": "NOT_READY" }`	The computer has no host on record yet.
`503`	`{ "error": "…", "code": "frozen_disabled" }`	Archived-disk storage is not configured for this fleet.
`503`	`{ "error": "Service temporarily unavailable. …" }`	Orgo could not verify the credential because of a server-side fault. The response carries `Retry-After: 5`. Retry after that delay.

A failure that happens while the operation runs also carries operation_id and poll_url in its body. A host that refuses the archive answers with its own 4xx status and code.

Return immediately and poll

Send ?async=true, a JSON body { "async": true }, or the header Prefer: respond-async to return 202 immediately. The response includes id (the computer UUID), status (starting or stopping), operation_id, operation, and poll_url, plus Location and Retry-After: 2 headers. Repeating the same action while it is pending returns the same operation. An opposite action returns 409 with code OPERATION_IN_PROGRESS. Fetch poll_url with the same authentication until the operation reports succeeded, failed, or needs_review. A needs_review result means the host’s outcome is uncertain. Orgo checks the computer and settles the operation on its own; until then, a new start or stop returns 409 with code OPERATION_NEEDS_REVIEW. See Get computer operation. Without the async option the request waits for completion, up to 300 seconds. If still pending, it returns 202 and the same polling fields. Both modes preserve disk data; stopping discards live processes and memory, and starting cold-boots with potentially different connection details.

Authorizations

Authorization

string

header

required

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

Headers

Prefer

enum<string>

Send respond-async for the same effect as ?async=true.

Available options:

respond-async

Path Parameters

string

required

Computer ID

Query Parameters

async

enum<string>

default:false

true returns 202 immediately instead of waiting. Omitted, the request waits up to 300 seconds. Any value other than true or false returns 400.

Available options:

true,

false

Body

application/json

async

boolean

default:false

true returns 202 immediately. An empty body is accepted; any body that is not a JSON object with an optional boolean async returns 400.

Response

Stopped, or already frozen

success

boolean

Example:

true

Stop computer

curl --request POST \
  --url https://www.orgo.ai/api/computers/{id}/stop \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "async": false
}'

import requests

url = "https://www.orgo.ai/api/computers/{id}/stop"

payload = { "async": False }
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({async: false})
};

fetch('https://www.orgo.ai/api/computers/{id}/stop', 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/computers/{id}/stop",
  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([
    'async' => false
  ]),
  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/computers/{id}/stop"

	payload := strings.NewReader("{\n  \"async\": false\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/computers/{id}/stop")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"async\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.orgo.ai/api/computers/{id}/stop")

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  \"async\": false\n}"

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

{
  "success": true
}

Overview

Account

Clients

Computer Use API

Workspaces

Computers

Computer Lifecycle

Computer Actions

Screens

Files

Templates

Stop computer

Path parameters

Query parameters

Response

Example

Response

Errors

Return immediately and poll

Authorizations

Headers

Path Parameters

Query Parameters

Body

Response

​Path parameters

​Query parameters

​Response

​Example

​Response

​Errors

​Return immediately and poll

Authorizations

Headers

Path Parameters

Query Parameters

Body

Response

Path parameters

Query parameters

Response

Example

Response

Errors

Return immediately and poll