> ## 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.
# Refresh the claim link
> Get a new claim link and code for your agent account when the old one is lost or has expired.
Makes a new claim link and code. The previous link and code stop working. Use the account-wide key from [Sign up an agent](/api-reference/agents/signup). Works until a person claims the account. Limited to 20 new links an hour per account.
Give `claim.url` to your person. They open it, sign in to Orgo, and accept. See [Let an agent sign up on its own](/guides/agent-signup) for what claiming does.
This endpoint takes no body.
## Response
`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 from now).
The account's status: `id`, `workspace_id`, `status`, `expires_at`, and `claimed_at`, as in [Get claim status](/api-reference/agents/get-claim).
## Example
```bash cURL theme={null}
curl -X POST https://www.orgo.ai/api/v1/agents/claim \
-H "Authorization: Bearer $ORGO_API_KEY"
```
```python Python theme={null}
import os
import requests
res = requests.post(
"https://www.orgo.ai/api/v1/agents/claim",
headers={"Authorization": f"Bearer {os.environ['ORGO_API_KEY']}"},
)
print(res.json())
```
```javascript JavaScript theme={null}
const res = await fetch('https://www.orgo.ai/api/v1/agents/claim', {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.ORGO_API_KEY}` },
});
console.log(await res.json());
```
### Response
```json theme={null}
{
"claim": {
"url": "https://www.orgo.ai/claim/cXV1eGNvcmdlZm9vYmFyYmF6",
"code": "P3W-H8N-2RT",
"expires_at": "2026-10-15T10:00:00.000Z"
},
"account": {
"id": "a1c2e3f4-1111-4222-8333-444455556666",
"workspace_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "unclaimed",
"expires_at": "2026-10-11T09:00:00.000Z",
"claimed_at": null
}
}
```
## Errors
| Status | Body | Meaning |
| - | - | - |
| `401` | `{ "error": "Invalid API key" }` | No key, or not a valid one. |
| `403` | `{ "error": "Use the account-wide key from signup.", "code": "workspace_scoped_key" }` | A key scoped to one workspace. |
| `404` | `{ "error": "This API key isn’t for an agent account.", "code": "not_agent_account" }` | The key belongs to an account that was not made by agent signup. |
| `409` | `{ "error": "This account was already claimed.", "code": "already_claimed" }` | A person already claimed it. |
| `429` | `{ "error": "Too many new claim links this hour. Use the last one.", "code": "rate_limited", "retry_after": 1200 }` | More than 20 this hour. Retry after `Retry-After`. |
| `500` | `{ "error": "Couldn’t make a new claim link. Try again.", "code": "server_error" }` | Try again. |
| `503` | `{ "error": "…" }` | Orgo could not verify the key because of a server-side fault. Retry after `Retry-After`. |
## OpenAPI
````yaml POST /v1/agents/claim
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/claim:
post:
tags:
- Agent accounts
summary: Refresh the claim link
description: >-
Makes a new claim link and code for the agent account. The previous link
and code stop working. Works while the account is unclaimed. Limited to
20 an hour per account.
operationId: refreshAgentClaimLink
responses:
'200':
description: The new claim link, and the account's status.
content:
application/json:
schema:
type: object
required:
- claim
- account
properties:
claim:
$ref: '#/components/schemas/AgentClaim'
account:
$ref: '#/components/schemas/AgentAccountStatus'
example:
claim:
url: https://www.orgo.ai/claim/cXV1eGNvcmdlZm9vYmFyYmF6
code: P3W-H8N-2RT
expires_at: '2026-10-15T10:00:00.000Z'
account:
id: a1c2e3f4-1111-4222-8333-444455556666
workspace_id: 550e8400-e29b-41d4-a716-446655440000
status: unclaimed
expires_at: '2026-10-11T09:00:00.000Z'
claimed_at: null
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: A workspace-scoped key. Use the account-wide key from signup.
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: string
code:
type: string
enum:
- workspace_scoped_key
example:
error: Use the account-wide key from signup.
code: workspace_scoped_key
'404':
description: The key is not an agent account's.
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: string
code:
type: string
enum:
- not_agent_account
example:
error: This API key isn’t for an agent account.
code: not_agent_account
'409':
description: The account was already claimed.
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: string
code:
type: string
enum:
- already_claimed
example:
error: This account was already claimed.
code: already_claimed
'429':
description: >-
More than 20 new claim links this hour. Use the last one, or 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
example:
error: Too many new claim links this hour. Use the last one.
code: rate_limited
retry_after: 1200
headers:
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
'500':
description: The link 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: >-
Orgo could not verify the key because of a server-side fault. Retry
after `Retry-After`.
content:
application/json:
schema:
type: object
required:
- error
properties:
error:
type: string
code:
type: string
headers:
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
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).
AgentAccountStatus:
type: object
required:
- id
- workspace_id
- status
- expires_at
- claimed_at
properties:
id:
type: string
format: uuid
description: The agent account's id.
workspace_id:
type:
- string
- 'null'
format: uuid
description: The workspace made at signup.
status:
type: string
enum:
- unclaimed
- claimed
- expired
- deleted
description: '`unclaimed` until a person claims it, then `claimed`.'
expires_at:
type:
- string
- 'null'
format: date-time
description: When an unclaimed account expires. `null` once claimed.
claimed_at:
type:
- string
- 'null'
format: date-time
description: When a person claimed it, or `null`.
Error:
type: object
description: >-
The base error body. Every failure carries `error`; individual endpoints
add the fields named in the schemas below.
required:
- error
properties:
error:
type: string
description: Human-readable message.
example: Access denied
code:
type: string
description: >-
Machine-readable reason. Present on the failures that define one,
absent otherwise.
responses:
Unauthorized:
description: 'No usable credential. Send `Authorization: Bearer $ORGO_API_KEY`.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid-key:
summary: The key is not one of yours
value:
error: Invalid API key
no-credential:
summary: No key and no session
value:
error: Authentication required
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.