---
title: "Start a key claim from inside an agent's session"
method: POST
path: "/api/agent/claims"
tags: ["Agent access"]
---

# Start a key claim from inside an agent's session

`POST /api/agent/claims`

## Request

- Base URL: `https://api.prereason.com`
- URL: `https://api.prereason.com/api/agent/claims`
- Auth: none required

Creates a claim and returns two things: a claim_code the human can read
(PR-XXXX-XXXX) and a one time claim_token only the agent holds. Show the
human approve_url; they sign in (or create the account there) and click
Approve. Then poll GET /api/agent/claims/{code} with the claim_token as
a Bearer until status is approved; that response carries the api_key
once. The key is attached to the approving human's account and named
"Agent: <client_name>".

Limits: 5 claims an hour per address, 20 pending per address, 2,000
pending globally (503 with Retry-After). A claim lives 15 minutes; the
approval page can extend it to at most 60 minutes from creation.

## Request body

- object
  - `client_name` string: The app or agent asking. Printable text, no URLs. Becomes the key name.
  - `purpose` string: One line on what the key is for, shown on the approval page.
  - `client_version` string

## Response `201`

Claim created; the token is shown once

- object
  - `claim_code` string
  - `claim_token` string: Bearer for the poll. Shown once, never stored in plaintext.
  - `status` string
  - `approve_url` string
  - `expires_at` string, date-time
  - `expires_in` integer
  - `poll` object
    - `url` string
    - `method` string
    - `header` string
    - `interval_seconds` integer
  - `instructions` string
  - `docs` string

## Other responses

- `400`: VALIDATION_ERROR with the offending field
- `429`: RATE_LIMITED, with Retry-After
- `503`: CLAIM_CAPACITY, with Retry-After

## Changes

- **2026-09-20** `0c21c73770c6`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/prereason/apis/prereason-api/changes/api/agent/claims/post.md)

---

[API](https://skmtc.dev/prereason/apis/prereason-api.md) - [All operations](https://skmtc.dev/prereason/apis/prereason-api/llms.txt) - [OpenAPI document](https://skmtc.dev/prereason/apis/prereason-api/revisions/fe5bacbc7887?raw)