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.
Last updated
On this page
Guide: Agent self-signup.
POST /agent/signup
api.primaryapi.com/ agent/ signupAuth: 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}
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
api.primaryapi.com/ v1/ agent/ claim/ {token}/ approveAuth: 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). 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}.