> ## 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.

# Agent signups

> An AI agent gets its own Orgo account and API key in one call, launches a computer, and hands the account to a person later.

An agent can get an Orgo account with no email, no browser, and no person present. One unauthenticated call returns an API key and \$2 of starting credit. The agent launches a computer by the hour, asks its person to add credit when it needs more, and gives a claim link to a person, who takes over the account from their own sign-in.

## The flow at a glance

1. **Sign up.** `POST /v1/agents` returns `api_key`, a workspace, a claim link, and \$2 of starting credit.
2. **Launch a computer by the hour.** `POST /computers` with your workspace id and a name.
3. **Use it.** Run commands, take screenshots, click and type.
4. **Add credit.** Ask for a Checkout link and send it to your person to pay.
5. **Hand over the claim link.** A person opens it, signs in, and claims the account before it expires.

## Step 1: Sign up

```bash theme={null}
IDEMPOTENCY_KEY=$(uuidgen)

curl -s -X POST https://www.orgo.ai/api/v1/agents \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{"name": "my-agent"}' > signup.json

export ORGO_API_KEY=$(jq -r .api_key signup.json)
export WORKSPACE_ID=$(jq -r .account.workspace_id signup.json)
```

No `Authorization` header is needed. Both body fields are optional: `name` (1 to 80 characters, used for the workspace name) and `contact_email`. Send no body at all and the account is still made.

The `201` response has everything the next steps need:

```json theme={null}
{
  "api_key": "sk_live_…",
  "key_id": "3b9e1f0a-…",
  "account": {
    "id": "a1c2e3f4-…",
    "name": "my-agent",
    "workspace_id": "550e8400-…",
    "workspace_name": "my-agent’s workspace",
    "status": "unclaimed",
    "expires_at": "2026-10-11T09:00:00.000Z"
  },
  "claim": {
    "url": "https://www.orgo.ai/claim/…",
    "code": "K7M-QXR-4TP",
    "expires_at": "2026-10-15T09:00:00.000Z"
  },
  "starting_credit_usd": 2,
  "limits": { "computers": 1, "computers_after_adding_credit": 5, "api_keys": 3, "…": "…" },
  "next": { "add_credits": "POST /api/credits/checkout …", "create_computer": "POST /api/computers", "…": "…" },
  "message": "Save api_key now: it is shown once. …"
}
```

> [!WARNING]
>
> `api_key` is shown once. Save it before you do anything else. It is an account-wide key: send it as `Authorization: Bearer $ORGO_API_KEY` on every later call.

The full response, including `limits` and `next`, is in [Sign up an agent](https://docs.orgo.ai/api-reference/agents/signup.md).

## Step 2: Launch a computer by the hour

An unclaimed account runs Medium Linux computers (2 vCPU, 8 GB RAM, 40 GB disk), billed by the hour from its credit: the \$2 starting credit first, then credit you add. Launching is one call. An agent account's create is hourly by default, and Orgo quotes the Medium at its listed price for you.

```bash theme={null}
LAUNCH_KEY=$(uuidgen)
curl -s -X POST https://www.orgo.ai/api/computers \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $LAUNCH_KEY" \
  -d "{\"workspace_id\": \"$WORKSPACE_ID\", \"name\": \"my-computer\"}" > computer.json

export COMPUTER_ID=$(jq -r .id computer.json)
```

Send a UUID as `Idempotency-Key`. If the launch fails partway, send it again with the same key and the same body: you get the original launch back instead of a second computer.

To have the computer deleted by itself when its time is up, with everything on it, add `"ends_in_hours"` (1 to 720). Its whole run is then prepaid from the credit, and what it does not use comes back. See [Set when a computer ends](https://docs.orgo.ai/guides/computer-ends.md).

When the credit runs out, a launch returns `402` with code `insufficient_credit`. A launch that names another `billing_mode` returns `402` with code `agent_account_prepaid_only`: an unclaimed account has no plan to fund a computer and gets no free trial computer.

## Step 3: Use the computer

`$COMPUTER_ID` is the `id` from the launch response.

```bash theme={null}
curl -X POST https://www.orgo.ai/api/computers/$COMPUTER_ID/bash \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "uname -a"}'

curl https://www.orgo.ai/api/computers/$COMPUTER_ID/screenshot \
  -H "Authorization: Bearer $ORGO_API_KEY"
```

Every action in the API reference works the same way: [Run a command](https://docs.orgo.ai/api-reference/computers/bash.md), [Click](https://docs.orgo.ai/api-reference/computers/click.md), [Type](https://docs.orgo.ai/api-reference/computers/type.md), and the rest.

## Step 4: Add credit

The starting credit runs computers only. Add credit to keep a computer running, to use AI, to unlock more computers and workspaces, and to keep the account from expiring. Ask for a Checkout link and send it to your person to pay:

```bash theme={null}
curl -s -X POST https://www.orgo.ai/api/credits/checkout \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents": 1000}' | jq -r .url
```

`amount_cents` is any whole dollar from $5 to $10,000, in cents (`500` to `1000000`). The answer is `{ "url": "…" }`. The credit lands on the account once the person pays.

Once the account has bought $5 of credit in all, with none of it refunded or disputed, it can run up to 5 computers, hold up to 5 workspaces and use AI. An account that has bought $5 of credit in all does not expire.

## Step 5: Hand the claim link to a person

Give your person `claim.url` from the signup response, and show them `claim.code` so they can check they are claiming the right account. They open the link, sign in to Orgo (or sign up), and accept. A person who has only the code can type it at `https://www.orgo.ai/claim`.

When they accept:

* They become an admin of every workspace the agent owns and manage them from their own account.
* The unclaimed limits and the expiry stop applying.
* The agent's key keeps working, and its credit keeps paying for its computer. Ownership and billing stay with the agent's account.

Claiming adds no credit. One person can claim up to 3 agent accounts. A fourth claim returns `403` with code `claim_limit`.

A claim link works for 7 days and only once. To get a new one, call [Refresh the claim link](https://docs.orgo.ai/api-reference/agents/refresh-claim.md). The previous link and code stop working. To check whether a person has claimed the account yet, call [Get claim status](https://docs.orgo.ai/api-reference/agents/get-claim.md).

```bash theme={null}
curl -X POST https://www.orgo.ai/api/v1/agents/claim \
  -H "Authorization: Bearer $ORGO_API_KEY"
```

## Limits on an unclaimed account

Until a person claims it, the account is held to these limits:

| Area | Unclaimed account |
| - | - |
| Computers | Medium Linux (2 vCPU, 8 GB RAM, 40 GB disk), 1 computer, running or stopped. Up to 5 once the account has bought \$5 of credit in all, with no refund or dispute. |
| Billing | By the hour, from credit: \$2 of starting credit, then credit the account buys. No plan, no free trial computer. |
| AI | Needs \$5 of credit bought in all. The starting credit runs computers only. |
| Workspaces | One. Up to 5 once the account has bought \$5 of credit. |
| API keys | 3, the signup key included |
| Invites | Not available |
| Client accounts and invoicing | Not available |
| Public URLs, deploys from GitHub, custom domains, the residential proxy, hardware and monthly GPU computers | Not available |

A refused action answers with a `code` that says why:

| Status | `code` | Meaning |
| - | - | - |
| `402` | `insufficient_credit` | Add credit to launch this computer. |
| `402` | `agent_account_prepaid_only` | Only an hourly computer paid from credit is allowed. |
| `403` | `HOURLY_LIMIT` | The account already holds its computers, for example `This account can have 1 computer. Delete one to make another.` |
| `403` | `agent_workspace_limit` | The account already holds its workspaces: one, or 5 once it has bought credit. |
| `403` | `agent_key_limit` | The account already holds 3 keys. Delete one first. |
| `403` | `agent_account_unclaimed` | Invites, public URLs, deploys, custom domains, the residential proxy, hardware and monthly GPU computers wait for a claim. |
| `403` | `agent_account_expired` | The account expired before anyone claimed it. |

## Expiry

An unclaimed account expires 72 hours after signup unless a person claims it or it buys $5 of credit in all. An account that has bought $5 of credit in all, net of refunds and disputes, does not expire. `account.expires_at` in the signup response gives the exact time.

1. **At expiry**, every API key of the account is deleted, so the agent's key stops working. Its running computer is stopped.
2. **For 2 days after expiry**, a person can still claim the account with a claim link that has not expired. They get the stopped computer and can make the agent a new key.
3. **After those 2 days**, the account's computers are deleted.

Because the key stops working at expiry, refresh the claim link before then if your person needs a new one.

## Retry signup safely with an Idempotency-Key

Send an `Idempotency-Key` header (8 to 255 printable characters, such as a UUID) so a dropped connection never makes a second account. Retry with the same key and the same body, and you get the first `201` back with `Idempotent-Replayed: true`. A replay does not count against the rate limits. Stored answers last 24 hours and are only replayed to the address that made the first request.

| Status | `code` | Meaning |
| - | - | - |
| `400` | `invalid_idempotency_key` | The key is not 8 to 255 printable characters. |
| `409` | `idempotency_in_progress` | The first request 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. |
| `422` | `idempotency_key_reused` | The key was used for a different body. Use a new key. |

## Rate limits

Signup is limited per address and network, and across everyone:

| Limit | Default |
| - | - |
| Per address (an IPv6 address counts as its /64) | 3 an hour, 10 a day |
| Per network (an IPv4 /24 or an IPv6 /48) | 20 a day |
| All signups | 500 a day |

A refused request counts against none of them. Over a limit, the answer is `429`:

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 1800
Content-Type: application/json

{ "error": "Too many signups from this network. Try again later.", "code": "rate_limited", "retry_after": 1800 }
```

Wait the number of seconds in `Retry-After`, then try again. If the limit cannot be checked, the answer is `503` with code `unavailable` and a `Retry-After` header. Retry after it.

Refreshing a claim link is limited to 20 an hour per account. It answers `429` with `Retry-After` the same way.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.