Skip to main content
POST
Create chat completion
Send a task and the ID of a computer. An agent works on that computer until the task is done: it reads the screen, clicks, types, and runs commands. Then it returns its final message. The request and response follow OpenAI’s chat completions format. Point an OpenAI SDK at https://www.orgo.ai/api/v1 and add computer_id to the request.

Quick start

Set $ORGO_API_KEY to your API key and $COMPUTER_ID to the id of a running computer, from Create computer.
The OpenAI SDKs require model, so the SDK examples name orgo-agent. With cURL you can leave model out and get the default, described in Choose a model.

Choose a model

model is optional. Leave it out and Orgo picks one for the computer: The response’s model field names the model that ran. Any other value returns 400 invalid_model, and the message lists the accepted values. Naming orgo-agent or orgo-agent-opus-5.5 for an Android computer returns 400 model_unsupported_os.
Model IDs on this endpoint use a dot for point versions (claude-opus-5.5). Anthropic’s own API uses a hyphen (claude-opus-5-5). Use the hyphenated form only when you call Anthropic directly, as in the Claude Computer Use guide.

Request body

string
required
The computer to drive: its UUID (the id from Create computer) or its instance id. You need write access to its workspace. Omitted, the request returns 400 missing_computer_id.
array
required
The whole conversation, as { role, content } objects. content is a string or an array of content parts, described in Send text and images.Messages with a role other than user or assistant, such as system, are dropped. The first remaining message must be from the user, or the request returns 400 invalid_message_order. No remaining message returns 400 empty_messages.The server does not load earlier turns from a thread. Resend the full transcript on every request, described in Threads and history.
string
One of orgo-agent, orgo-agent-opus-5.5, claude-sonnet-5, claude-opus-5.5, claude-opus-5, claude-opus-4.8, claude-sonnet-4.6, or claude-opus-4.6. Optional. Omitted, the request runs orgo-agent, or claude-sonnet-5 on an Android computer or when you send x-anthropic-key. See Choose a model.
boolean
default:"false"
true streams the answer as Server-Sent Events, described in Streaming. Omitted or false, the response is one JSON body sent when the run ends.
integer
default:"250"
The most steps the run may take, from 250 to 500. Optional. Omitted, the limit is 250. A value above 500 runs with 500. A value below 250 runs with 250: this field can raise the limit but never lower it. A value that is not a number is ignored, and the run gets 250. No value is an error. See Step limits.
string
The UUID of a thread to write this turn into. Optional. Omitted, a new thread is created and its ID returned in orgo.thread_id and the X-Thread-Id header. A thread_id that is not a UUID or does not exist is ignored, and a new thread is created. So is another user’s chat about a computer in a workspace you can reach, and, with a workspace-scoped key, a thread in its workspace that is not on this computer. A thread in a workspace you can’t reach, or another user’s chat that is not about a computer, is refused with 403 before the run, as described in Errors. It does not change what the model sees. See Threads and history.

Headers

string
required
Bearer $ORGO_API_KEY. An account-wide key reaches every computer your account can. A workspace-scoped key reaches only computers in its own workspace. Get a key at orgo.ai/settings/credentials.
string
Your own Anthropic API key. It pays for Anthropic-served models only: every claude-* model and orgo-agent-opus-5.5. The run is then billed to your Anthropic account, not to Orgo credits, and orgo.cost_cents is 0. With orgo-agent it is ignored and the run bills to Orgo credits. With no model, sending it runs claude-sonnet-5.

Send text and images

content is a plain string, or an array of OpenAI content parts: An image url is an https:// URL, or a base64 data URL of a PNG, JPEG, GIF, or WebP image (data:image/png;base64,…). Both forms work with every model. Orgo passes an https:// URL to the model provider, which fetches the image itself, so the URL must be publicly reachable.
Any other part, an image in an assistant message, or an invalid image URL returns 400 invalid_messages. The param field names the part that failed:
The index in param counts every message you sent, including dropped ones.

Step limits

A step is one model call and the computer actions it makes. A run takes at most 250 steps. Send max_steps to allow up to 500. A run that reaches its limit stops and returns normally, with:
  • finish_reason set to "length" instead of "stop".
  • A final assistant message that ends with Stopped after N steps. Send a message to keep going.
To continue, resend the transcript with a new user message. A run also stops early when it is about to spend more credits than the payer has, described in Billing. That run ends with finish_reason "stop". Its final message depends on the model: Out of AI credits. The run was stopped. for orgo-agent models, and The run stopped here because the AI credit balance ran out. Top up and send a follow-up to continue. for claude-* models.

Response

string
chatcmpl- followed by a 16-character opaque id. Also sent as the X-Request-Id header. Include it when you report a problem.
string
Always chat.completion.
integer
Unix time in seconds.
string
The model that ran. With no model in the request, orgo-agent or claude-sonnet-5.
array
One choice.
object
Tokens across every step of the run, not only the last message.
object
Orgo’s fields. Not part of OpenAI’s format, and not sent when streaming.

Streaming

With "stream": true the response is text/event-stream. Each event is an OpenAI chat.completion.chunk, and the stream ends with data: [DONE]:
  • Only text streams. Screenshots, clicks, and commands run on Orgo’s side and are not sent.
  • The last chunk carries finish_reason ("stop" or "length") and usage.
  • No orgo block. Read the thread ID from the X-Thread-Id header, which arrives before the first chunk.
  • Closing the connection stops the run at its next step. Steps already taken are billed.

Errors during a stream

The status is already 200 when the run starts, so a failure mid-run cannot change it. The stream sends one error event and ends:
The OpenAI SDKs raise this as an APIError. If you read the stream yourself, treat a stream that ends without a chunk carrying finish_reason as failed. A run that fails mid-stream is billed for the tokens it used before failing. Its hold is refunded only when it used none.

Threads and history

thread_id does not do what its name suggests, and assuming it does loses data.
  • History is not loaded. The agent sees exactly the messages you send. A thread_id with only the new user turn gives the model no earlier context.
  • Stored history is replaced, not appended. When the run ends, the thread’s stored messages are overwritten with this request’s messages plus this turn’s replies. Sending only the new turn erases the earlier turns from the thread.
Keep the transcript yourself and resend all of it on every request. Pass the same thread_id each time so the stored copy stays complete.
Image parts are stored in the thread as the text [image]. To read or manage stored threads, see Threads.

Bring your own Anthropic key

Send x-anthropic-key to pay for an Anthropic-served model on your own Anthropic account. No Orgo credits are held or spent, and orgo.cost_cents is 0.
orgo-agent runs on OpenAI’s GPT-6 Astra, so an Anthropic key cannot pay for it. A request that names orgo-agent bills to Orgo credits even when the header is sent.

Billing

Runs draw on the AI credits of the computer’s workspace owner, not the caller.
  • Rates. A run costs the model provider’s list price for the tokens it used, plus 10%. Credits are charged to a fraction of a cent. orgo.cost_cents reports that cost rounded up to a whole cent, and is at least 1.
  • Computer Use. orgo-agent runs GPT-6 Astra on its fast tier, which bills at twice Astra’s standard rates. orgo-agent-opus-5.5 runs Claude Opus 5.5 at standard rates.
  • Hold and settle. A flat hold is placed when the request starts. It is settled against actual usage after the response is sent, so orgo.credit_balance_cents reflects the hold, not the final cost.
  • Budget. The run stops early when its running cost comes within 25 cents of the balance available at the start. When a workspace member’s request spends the owner’s credits, that request may use at most $5.
  • No hold is placed when x-anthropic-key pays, or on Enterprise.
See your balance and add credits at orgo.ai/settings/billing.

Errors

Every error has this shape:
type is one of invalid_request, authentication_error, insufficient_credits, permission_error, not_found, or server_error. Branch on code. invalid_messages adds param, and 402 adds balance_cents. Once a stream has started, failures arrive as an error event instead of a status, described in Errors during a stream.

Authorizations

Authorization
string
header
required

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

Headers

x-anthropic-key
string

Your own Anthropic API key. Pays for Anthropic-served models only (claude-* and orgo-agent-opus-5.5): the run is then not billed to Orgo credits. Ignored for orgo-agent. When model is omitted, sending it runs claude-sonnet-5.

Body

application/json
computer_id
string
required

The computer to drive: its UUID or its instance id. You need write access to its workspace.

messages
object[]
required

The whole conversation. Roles other than user and assistant are dropped. The first remaining message must be from the user.

model
enum<string>

Omit to get the default: orgo-agent on Linux, Windows, macOS, and iPhone computers, claude-sonnet-5 on Android computers or when x-anthropic-key is sent. A named model always runs that model. orgo-agent and orgo-agent-opus-5.5 do not run on Android computers.

Available options:
orgo-agent,
orgo-agent-opus-5.5,
claude-sonnet-5,
claude-opus-5.5,
claude-opus-5,
claude-opus-4.8,
claude-sonnet-4.6,
claude-opus-4.6
stream
boolean
default:false

Stream the answer as chat.completion.chunk Server-Sent Events, ending in data: [DONE].

max_steps
integer
default:250

Raise the step limit. Values above 500 are capped at 500, values below 250 run with 250, and a value that is not a number is ignored (250). Never an error.

thread_id
string<uuid>

A thread to write this turn into. It does not load history. An unknown or non-UUID id, a thread that isn't yours, or, with a workspace-scoped key, a thread on another computer is ignored and a new thread starts.

Response

The final answer. With stream: true, a text/event-stream of chat.completion.chunk events instead.

id
string

chatcmpl- followed by an opaque id.

object
string
Allowed value: "chat.completion"
created
integer

Unix time in seconds.

model
string

The model that ran. When model was omitted, orgo-agent or claude-sonnet-5.

choices
object[]
usage
object
orgo
object