> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orgo.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Sign up an agent
> Get a new Orgo account and API key in one unauthenticated call, with no email or person present.
Makes an unclaimed account with one workspace and an account-wide API key. No `Authorization` header is needed. The account starts with \$5 of credit, which runs a Medium Linux computer by the hour (not AI). Add credit to keep it running, to use AI, and to unlock more computers and workspaces. The account expires 72 hours after signup unless a person claims it with `claim.url`. The whole flow is in [Let an agent sign up on its own](/guides/agent-signup).
Agent signup can be turned off per environment. Where it is off, this returns `404` with code `agent_signup_disabled`.
## Headers
A unique value per signup, such as a UUID (8 to 255 printable characters). A retry with the same key and body from the same address returns the first answer with `Idempotent-Replayed: true`, and makes no second account. Keys last 24 hours. Omitted: every request makes a new account.
## Body
The body is optional. Send no body, or a JSON object with either field.
The agent's name, 1 to 80 characters. The workspace is named after it (`my-agent’s workspace`). Omitted: the workspace is named `Agent workspace`.
An address for the agent's operator, up to 320 characters. Stored with the account. Nothing is sent to it.
## Response
An account-wide API key (`sk_live_…`). Shown once.
The key's id.
`id`, `name`, `workspace_id`, `workspace_name`, `status` (always `unclaimed`), and `expires_at`, when the account expires unless a person claims it.
`url`, the link a person opens to claim the account; `code`, a short `XXX-XXX-XXX` code to show them; and `expires_at`, when the link stops working (7 days after it was made).
The credit the account starts with, in US dollars (`5`). It runs computers by the hour, not AI.
What the account may do until it is claimed: `computers` (`1`), `computers_after_adding_credit` (`5`), `workspaces` (`1`), `workspaces_after_adding_credit` (`5`), `computer` (`os`, `size`, `cpu`, `ram_gb`, `disk_gb`), `billing`, `ai`, `api_keys`, and `not_until_claimed`.
The calls to make next, with your workspace id filled in: `add_credits`, `create_computer`, `create_computer_body`, `use_computer`, `refresh_claim_link`, and `docs`.
A plain-language summary of what to do next.
## Example
```bash cURL theme={null}
curl -X POST https://www.orgo.ai/api/v1/agents \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"name": "my-agent"}'
```
```python Python theme={null}
import uuid
import requests
res = requests.post(
"https://www.orgo.ai/api/v1/agents",
headers={"Idempotency-Key": str(uuid.uuid4())},
json={"name": "my-agent"},
)
print(res.json())
```
```javascript JavaScript theme={null}
const res = await fetch('https://www.orgo.ai/api/v1/agents', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'Idempotency-Key': crypto.randomUUID() },
body: JSON.stringify({ name: 'my-agent' }),
});
console.log(await res.json());
```
### Response
```json theme={null}
{
"api_key": "sk_live_3f9c…",
"key_id": "0b7d2c1e-5a4f-4e3b-9c8d-1a2b3c4d5e6f",
"account": {
"id": "a1c2e3f4-1111-4222-8333-444455556666",
"name": "my-agent",
"workspace_id": "550e8400-e29b-41d4-a716-446655440000",
"workspace_name": "my-agent’s workspace",
"status": "unclaimed",
"expires_at": "2026-10-11T09:00:00.000Z"
},
"claim": {
"url": "https://www.orgo.ai/claim/Zm9vYmFyYmF6cXV4cXV1eGNvcmdl",
"code": "K7M-QXR-4TP",
"expires_at": "2026-10-15T09:00:00.000Z"
},
"starting_credit_usd": 5,
"limits": {
"computers": 1,
"computers_after_adding_credit": 5,
"workspaces": 1,
"workspaces_after_adding_credit": 5,
"computer": { "os": "linux", "size": "medium", "cpu": 2, "ram_gb": 8, "disk_gb": 40 },
"billing": "hourly, from credit: the starting credit first, then credit you add.",
"ai": "needs credit you add (the starting credit runs computers only)",
"api_keys": 3,
"not_until_claimed": ["invites", "public URLs", "custom domains", "client accounts", "invoicing"]
},
"next": {
"add_credits": "POST /api/credits/checkout {\"amount_cents\": 1000} (answers a Checkout url; send it to your person to pay)",
"create_computer": "POST /api/computers",
"create_computer_body": {
"workspace_id": "550e8400-e29b-41d4-a716-446655440000",
"name": "my-computer"
},
"use_computer": "POST /api/computers//bash {\"command\": \"uname -a\"}",
"refresh_claim_link": "POST /api/v1/agents/claim",
"docs": "https://www.orgo.ai/orgo.md"
},
"message": "Save api_key now: it is shown once. Send it as \"Authorization: Bearer \". It has $5.00 of starting credit: launch a computer now. Add credit to keep it running and to unlock more computers and workspaces. An account that never adds credit expires at 2026-10-11T09:00:00.000Z unless your person claims it (claim.url)."
}
```
## Errors
Every error body is `{ "error": "…", "code": "…" }`.
| Status | `code` | Meaning |
| - | - | - |
| `400` | `invalid_request` | The body is not a JSON object, or a field is invalid, for example `name must be 1 to 80 characters.` |
| `400` | `invalid_idempotency_key` | The Idempotency-Key is not 8 to 255 printable characters. |
| `404` | `agent_signup_disabled` | Agent signup is off in this environment. |
| `409` | `idempotency_in_progress` | The first request with this key is still running. Retry after `Retry-After` (5 seconds). |
| `409` | `idempotency_unfinished` | The first request with this key did not finish, or can't be replayed. Use a new key. |
| `413` | `invalid_request` | The body is larger than 4 KB. |
| `422` | `idempotency_key_reused` | The key was used for a different body. |
| `429` | `rate_limited` | Too many signups from this address or network, or for everyone today. The body adds `retry_after`. Retry after `Retry-After`. |
| `500` | `server_error` | The account could not be made. Try again. |
| `503` | `unavailable` | Signup is unavailable right now. Retry after `Retry-After`. |
The rate limits are 3 signups an hour and 10 a day per address (an IPv6 address counts as its /64), 20 a day per network (an IPv4 /24 or an IPv6 /48), and 500 a day for everyone. A refused request counts against none of them, and an idempotent replay counts against none of them.
## OpenAPI
````yaml POST /v1/agents
openapi: 3.1.0
info:
title: Orgo API
description: >-
Launch cloud computers that AI agents can control and interact with. Create
workspaces, provision computers, and control them programmatically.
version: 2.0.0
contact:
name: Orgo Support
email: spencer@orgo.ai
url: https://orgo.ai
servers:
- url: https://www.orgo.ai/api
description: Production
security:
- bearerAuth: []
tags:
- name: Account
description: >-
Account capacity: how many computers an account may run, and adding or
giving back more.
- name: Agent accounts
description: >-
Accounts an AI agent makes for itself, and the claim link a person uses to
take one over.
- name: Clients
description: >-
Run Orgo for your clients from your own app: a workspace and scoped key
each, billed to you or to them.
- name: Workspaces
description: Organize computers into named workspaces
- name: Computers
description: Provision and manage virtual computers
- name: Computer Lifecycle
description: Start, stop, and restart computers
- name: Computer Actions
description: Control mouse, keyboard, and execute commands
- name: Screens
description: >-
More than one desktop on a single computer. Each screen is its own X
server with its own cursor and window manager, so an agent working on one
cannot disturb another.
- name: Files
description: Upload and download files
- name: Templates
description: Author, build, and launch reproducible computers from templates
- name: Chat
description: Run an agent on a computer through OpenAI-compatible chat completions.
paths:
/v1/agents:
post:
tags:
- Agent accounts
summary: Sign up an agent
description: >-
Makes a new, unclaimed Orgo account with one workspace and an
account-wide API key, with no authentication, email, or person present.
The account starts with $5 of credit, which runs a Medium Linux computer
by the hour (not AI). Add credit to keep it running, to use AI, and to
unlock more computers and workspaces: `POST /api/credits/checkout` with
`{"amount_cents": 1000}` answers a Checkout `url` to send to your
person. An account that never adds credit expires 72 hours after signup
unless a person opens `claim.url` and claims it. Send an
`Idempotency-Key` header so a retry returns the same account. Returns
`404` (`agent_signup_disabled`) where agent signup is turned off.
operationId: agentSignup
parameters:
- name: Idempotency-Key
in: header
required: false
description: >-
A unique value per signup, such as a UUID (8 to 255 printable
characters). A retry with the same key and body from the same
address returns the first answer with `Idempotent-Replayed: true`.
Keys last 24 hours.
schema:
type: string
minLength: 8
maxLength: 255
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
name:
type: string
minLength: 1
maxLength: 80
description: >-
The agent's name, used for the workspace name. Whitespace
runs collapse to one space. Omitted: the workspace is named
`Agent workspace`.
contact_email:
type: string
format: email
maxLength: 320
description: >-
An address to reach the agent's operator. Stored with the
account; nothing is sent to it.
example:
name: my-agent
responses:
'201':
description: The account, its key (shown once), and its claim link.
headers:
Idempotent-Replayed:
description: >-
`true` when this is the stored answer to an earlier request with
the same Idempotency-Key.
schema:
type: string
content:
application/json:
schema:
type: object
required:
- api_key
- key_id
- account
- claim
- starting_credit_usd
- limits
- next
- message
properties:
api_key:
type: string
description: An account-wide API key (`sk_live_…`). Shown once.
key_id:
type: string
format: uuid
description: The key's id.
account:
type: object
required:
- id
- name
- workspace_id
- workspace_name
- status
- expires_at
properties:
id:
type: string
format: uuid
name:
type:
- string
- 'null'
description: The `name` you sent, or `null`.
workspace_id:
type: string
format: uuid
workspace_name:
type: string
description: >-
`{name}’s workspace`, or `Agent workspace` with no
name.
status:
type: string
enum:
- unclaimed
expires_at:
type: string
format: date-time
description: >-
When the account expires unless a person claims it (72
hours after signup).
claim:
$ref: '#/components/schemas/AgentClaim'
starting_credit_usd:
type: number
description: >-
Credit the account starts with, in dollars. It runs
computers only; AI needs credit you add.
example: 5
limits:
type: object
description: What the account may do until it is claimed.
properties:
computers:
type: integer
description: Computers it may run before adding credit.
example: 1
computers_after_adding_credit:
type: integer
description: Computers it may run once it has added credit.
example: 5
workspaces:
type: integer
description: Workspaces it may have before adding credit.
example: 1
workspaces_after_adding_credit:
type: integer
description: Workspaces it may have once it has added credit.
example: 5
computer:
type: object
description: The computer it runs by the hour.
properties:
os:
type: string
example: linux
size:
type: string
example: medium
cpu:
type: number
example: 2
ram_gb:
type: number
example: 8
disk_gb:
type: number
example: 40
billing:
type: string
description: How its computers are paid for.
ai:
type: string
description: How its AI use is paid for.
api_keys:
type: integer
description: API keys it may hold.
example: 3
not_until_claimed:
type: array
items:
type: string
description: What only a claimed account can do.
next:
type: object
description: >-
The calls to make next, as strings, with your workspace id
filled in: `add_credits`, `create_computer`,
`create_computer_body`, `use_computer`,
`refresh_claim_link` and `docs`.
additionalProperties: true
message:
type: string
description: A plain-language summary of what to do next.
example:
api_key: sk_live_3f9c…
key_id: 0b7d2c1e-5a4f-4e3b-9c8d-1a2b3c4d5e6f
account:
id: a1c2e3f4-1111-4222-8333-444455556666
name: my-agent
workspace_id: 550e8400-e29b-41d4-a716-446655440000
workspace_name: my-agent’s workspace
status: unclaimed
expires_at: '2026-10-11T09:00:00.000Z'
claim:
url: https://www.orgo.ai/claim/Zm9vYmFyYmF6cXV4cXV1eGNvcmdl
code: K7M-QXR-4TP
expires_at: '2026-10-15T09:00:00.000Z'
starting_credit_usd: 5
limits:
computers: 1
computers_after_adding_credit: 5
workspaces: 1
workspaces_after_adding_credit: 5
computer:
os: linux
size: medium
cpu: 2
ram_gb: 8
disk_gb: 40
billing: >-
hourly, from credit: the starting credit first, then credit
you add.
ai: >-
needs credit you add (the starting credit runs computers
only)
api_keys: 3
not_until_claimed:
- invites
- public URLs
- custom domains
- client accounts
- invoicing
next:
add_credits: 'POST /api/credits/checkout {"amount_cents": 1000}'
create_computer: POST /api/computers
create_computer_body:
workspace_id: 550e8400-e29b-41d4-a716-446655440000
name: my-computer
use_computer: 'POST /api/computers//bash {"command": "uname -a"}'
refresh_claim_link: POST /api/v1/agents/claim
docs: https://www.orgo.ai/orgo.md
message: >-
Save api_key now: it is shown once. Send it as "Authorization:
Bearer ". It has $5.00 of starting credit: launch a
computer now. Add credit to keep it running and to unlock more
computers and workspaces. An account that never adds credit
expires at 2026-10-11T09:00:00.000Z unless your person claims
it (claim.url).
'400':
description: >-
The body is not a JSON object or a field is invalid
(`invalid_request`), or the Idempotency-Key is malformed
(`invalid_idempotency_key`).
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: string
code:
type: string
enum:
- invalid_request
- invalid_idempotency_key
example:
error: name must be 1 to 80 characters.
code: invalid_request
'404':
description: Agent signup is turned off in this environment.
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: string
code:
type: string
enum:
- agent_signup_disabled
example:
error: >-
Agent signup isn’t available here. Use device sign-in: POST
/api/cli/auth/start.
code: agent_signup_disabled
'409':
description: >-
A request with this Idempotency-Key is still running
(`idempotency_in_progress`, with `Retry-After: 5`), or
`idempotency_unfinished`: The first request with this key did not
finish, or can't be replayed. Use a new key.
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: string
code:
type: string
enum:
- idempotency_in_progress
- idempotency_unfinished
headers:
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
'413':
description: The body is larger than 4 KB.
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: string
code:
type: string
enum:
- invalid_request
example:
error: The request is too large.
code: invalid_request
'422':
description: This Idempotency-Key was used for a different body.
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: string
code:
type: string
enum:
- idempotency_key_reused
'429':
description: >-
Rate limited: per address (3 an hour, 10 a day), per network (20 a
day, an IPv4 /24 or IPv6 /48), or the daily cap for everyone. Retry
after `Retry-After`.
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: string
code:
type: string
enum:
- rate_limited
retry_after:
type: integer
description: Seconds until a retry can succeed.
example:
error: Too many signups from this network. Try again later.
code: rate_limited
retry_after: 1800
headers:
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
'500':
description: The account could not be made. Try again.
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: string
code:
type: string
enum:
- server_error
'503':
description: >-
Signup is unavailable right now (for example, the rate limit could
not be checked). Retry after `Retry-After`.
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: string
code:
type: string
enum:
- unavailable
headers:
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
security: []
components:
schemas:
AgentClaim:
type: object
required:
- url
- code
- expires_at
properties:
url:
type: string
format: uri
description: >-
The link a person opens to claim the account:
`https://www.orgo.ai/claim/{token}`. Works once.
code:
type: string
description: >-
A short code in the form `XXX-XXX-XXX`. Show it to your person so
they can check they are claiming the right account, or have them
type it at `https://www.orgo.ai/claim`.
expires_at:
type: string
format: date-time
description: When the link and code stop working (7 days after they were made).
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: API key authentication. Get your key at orgo.ai/workspaces
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.