# Agents

Reference for POST /agent/signup (self-service trial keys) and the claim endpoints a signed-in human uses to approve a trial key and its spend limit.

Guide: [Agent self-signup](/docs/agent-signup).

## POST /agent/signup

`POST https://api.primaryapi.com/agent/signup`

Auth: None (rate limited per network)

Creates a trial key for an agent: an account with no person behind it, a `trial` key with `run` access, a trial budget in credits and an expiry. No email or card.

### Body

Optional JSON object:

| Field | Type | Description |
|---|---|---|
| `label` | string | Up to 80 characters, shown to the human on the claim page. Control characters are removed. |

### Response

**201 Created**:

| Field | Type | Description |
|---|---|---|
| `secret` | string | The API key (`pa_live_…`). Returned once. |
| `keyId` | string | `key_…` |
| `capCredits` | number | The trial budget, in credits. |
| `expiresAt` | string | When the key expires unless claimed (currently 7 days). |
| `upgrade` | object | `{ claimUrl, authorizationServer, scope }`. `claimUrl` is where a human approves the key. |
| `notice` | string | A sentence for the human, to relay word for word. |

### Errors

| Status | Code | When |
|---|---|---|
| 400 | `invalid_input` | The body is not a JSON object, or `label` is longer than 80 characters. |
| 429 | `rate_limited` | 3 trial keys were already created from this network in the last 24 hours, or the daily signup budget across all agents is spent. `retryAfterSeconds` says when to try again. |

## GET /v1/agent/claim/\{token\}

`GET https://api.primaryapi.com/v1/agent/claim/{token}`

Auth: Dashboard session only

The receipt shown on the claim page. The token is the `claim` parameter of `claimUrl`.

| Field | Type | Description |
|---|---|---|
| `label` | string or null | The agent's label. |
| `keyPrefix` | string | First 12 characters of the key. |
| `createdAt`, `expiresAt` | string | When the trial key was created and when it expires. |
| `spentCredits`, `capCredits` | number | Credits spent on the trial so far, and the budget. |
| `requests` | integer | Calls made with the key. |
| `recent` | object[] | The latest calls: `{ sku, credits, status, at }`. |
| `alreadyClaimed` | boolean | Whether the key was already approved. |

Errors: `404 not_found` when the link is invalid or expired (claim links stay valid until 7 days after the trial key expires).

## POST /v1/agent/claim/\{token\}/approve

`POST https://api.primaryapi.com/v1/agent/claim/{token}/approve`

Auth: Dashboard session only

Moves the trial key into the signed-in user's account, removes the trial cap and applies the chosen spend limit. The agent keeps using the same secret.

| Field | Type | Description |
|---|---|---|
| `limitCredits` | number or null | Spend limit for the key, in credits; `null` for no limit beyond the workspace's balance. |
| `limitInterval` | string or null | `daily`, `weekly` or `monthly` (default `monthly`). Ignored when `limitCredits` is `null`. |
| `workspaceId` | string | Optional: the workspace that adopts the key (default: the active one). You must be its owner, an admin or a developer. |

The body is strict: unknown fields are rejected, so a misspelled limit can never mean "no limit".

**200 OK**: `{ "claimed": true, "alreadyClaimed": false, "key": <key object> }` ([key object](/docs/api-reference/keys#the-key-object)). Approving again as the same user returns `alreadyClaimed: true` and keeps the first approval's limit; change it afterwards with `PATCH /v1/api-keys/{id}`.
