> ## 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.
# Get claim status
> Check whether a person has claimed your agent account, and when it expires if not.
Returns the status of the agent account that owns the key. Use the account-wide key from [Sign up an agent](/api-reference/agents/signup). A key scoped to one workspace gets `403`.
## Response
The agent account.
The account's id.
The workspace made at signup.
`unclaimed` until a person claims it, then `claimed`. An account that expires loses its keys, so its key gets `401` instead of reading `expired` or `deleted`.
When an unclaimed account expires. `null` once claimed.
When a person claimed it, or `null`.
## Example
```bash cURL theme={null}
curl https://www.orgo.ai/api/v1/agents/claim \
-H "Authorization: Bearer $ORGO_API_KEY"
```
```python Python theme={null}
import os
import requests
res = requests.get(
"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', {
headers: { Authorization: `Bearer ${process.env.ORGO_API_KEY}` },
});
console.log(await res.json());
```
### Response
```json theme={null}
{
"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. An expired agent account's keys are deleted, so they get this too. |
| `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. |
| `503` | `{ "error": "…" }` | Orgo could not verify the key because of a server-side fault. Retry after `Retry-After`. |
## OpenAPI
````yaml GET /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:
get:
tags:
- Agent accounts
summary: Get claim status
description: >-
Returns the agent account's status: whether a person has claimed it, and
when it expires if not. Use the account-wide key from signup. An expired
account's key gets `401`, so `expired` and `deleted` are never read
here.
operationId: getAgentClaimStatus
responses:
'200':
description: The account's status.
content:
application/json:
schema:
type: object
required:
- account
properties:
account:
$ref: '#/components/schemas/AgentAccountStatus'
example:
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
'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:
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.