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 and the key you send: The response’s model field names the model that ran, and orgo.own_key names the key that paid. Which key pays for which model, and every error a key can get, are in Bring your own model key. 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. Both are checked before any key. Every claude-* model and orgo-agent-opus-5.5 are Anthropic models, which X-Anthropic-Key pays for.
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 only 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/api-keys.
string
Your own OpenAI API key. It pays for orgo-agent, an OpenAI model. The run then uses no Orgo credits, orgo.cost_cents is 0, and orgo.own_key is "openai". With no model it runs orgo-agent, also when you send X-Anthropic-Key. On Android, where orgo-agent doesn’t run, X-Anthropic-Key pays for claude-sonnet-5 instead. Sent without X-Anthropic-Key for an Anthropic model, the request returns 400 own_key_model_mismatch. Sent alone with no model on an Android computer, it returns 400 own_key_unsupported. Used for this request only and never stored. An empty value counts as not sent. See Bring your own model key.
string
Your own Anthropic API key. It pays for Anthropic models: every claude-* model and orgo-agent-opus-5.5. The run then uses no Orgo credits, orgo.cost_cents is 0, and orgo.own_key is "anthropic". With no model and no X-OpenAI-Key, it runs claude-sonnet-5. Sent without X-OpenAI-Key for orgo-agent, the request returns 400 own_key_model_mismatch. Used for this request only and never stored. An empty value counts as not sent. See Bring your own model key.

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, as described in Continue a run that hit its step limit. 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.

Continue a run that hit its step limit

thread_id loads no history: the agent sees only the messages you send. To pick up where a run stopped:
  1. Add the run’s reply, choices[0].message.content, to your transcript as an assistant message.
  2. Add a new user message, such as Keep going.
  3. Send the whole transcript again, with the same computer_id and the same thread_id.
The new request is a new run with a fresh step limit, counted from 0. The computer’s screen and files are where the last run left them, but its tool calls and screenshots are not returned, so they can’t be sent back. The saved thread is replaced with the messages you send plus the new reply, so sending thread_id with only Keep going. erases the earlier turns from it, as described in Threads and history. Each new run also counts against your plan’s agent runs a minute, described in Plan rate limits.
Set $COMPUTER_ID to the computer’s UUID. A streamed run carries its thread ID only in the X-Thread-Id header.

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, picked as described in Choose a model.
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. When streaming, only own_key is sent, on the last chunk.

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"), usage, and orgo.own_key.
  • No other orgo fields. 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:
When the provider refuses your own key, the event carries that error’s type and code, such as authentication_error and invalid_own_key, described in Bring your own model key. 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.

Pay with your own model key

Send X-OpenAI-Key to pay for orgo-agent with your OpenAI account, or X-Anthropic-Key to pay for a claude-* model or orgo-agent-opus-5.5 with your Anthropic account. No Orgo credits are held or spent, orgo.cost_cents is 0, and orgo.own_key names the key that paid.
Set $OPENAI_API_KEY to your OpenAI key. With no model, the key picks it: X-OpenAI-Key runs orgo-agent, and X-Anthropic-Key alone runs claude-sonnet-5. A key that can’t pay for the model you name is refused with 400 own_key_model_mismatch, never ignored. The full table, every error message, and what Orgo still bills are in Bring your own model key.

Billing

Runs draw on the AI credits of the computer’s workspace owner, not the caller, unless your own key pays, described in Pay with your own model key.
  • Rates. A run costs the model provider’s list price for the tokens it used, plus a markup. 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.
  • Markup. The markup is the payer’s: the account whose credits pay for the run, the workspace owner, never the caller. It is 10% by default. Orgo can set an account its own percent, for every model, for one model, or both, and the one for a model comes first. A member’s run in a workspace bills at that workspace owner’s markup. orgo.cost_cents includes it.
  • Computer Use. orgo-agent runs GPT-6.1 Terra on its fast tier, which bills at twice Terra’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 your own key pays (X-OpenAI-Key or X-Anthropic-Key), 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, rate_limit_error, insufficient_credits, computer_locked, permission_error, not_found, server_error, or api_error. A refusal made before the run, such as a 404 for a computer_id an API key can’t find, carries not_found_error instead. Branch on code, not type. invalid_messages adds param, credits_exhausted and account_ai_limit add balance_cents, rate_limited adds limit and retry_after, and computer_locked can add lock. 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-OpenAI-Key
string

Your own OpenAI API key. Pays for OpenAI models (orgo-agent), which then use no Orgo credits. With no model, runs orgo-agent, also when X-Anthropic-Key is sent, except on Android, where X-Anthropic-Key then runs claude-sonnet-5. Sent without X-Anthropic-Key for an Anthropic model: 400 own_key_model_mismatch. Sent alone with no model on an Android computer: 400 own_key_unsupported. Used for this request only, never stored. An empty value counts as not sent. The MCP server does not send this header. Through MCP, the run bills Orgo credits, so don't pass your key there.

X-Anthropic-Key
string

Your own Anthropic API key. Pays for Anthropic models (claude-* and orgo-agent-opus-5.5), which then use no Orgo credits. With no model and no X-OpenAI-Key, runs claude-sonnet-5. Sent without X-OpenAI-Key for orgo-agent: 400 own_key_model_mismatch. Used for this request only, never stored. An empty value counts as not sent. The MCP server does not send this header. Through MCP, the run bills Orgo credits, so don't pass your key there.

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 with no key or with X-OpenAI-Key, claude-sonnet-5 with only X-Anthropic-Key, and claude-sonnet-5 on Android computers with no key or both keys (X-OpenAI-Key alone there is 400 own_key_unsupported). A named model always runs that model, and a key you send must be able to pay for it. 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, picked by the computer and the key you sent.

choices
object[]
usage
object
orgo
object