---
title: "Atomically redeem one exact action capability"
method: POST
path: "/v1/capabilities/redeem"
tags: ["Capabilities"]
---

# Atomically redeem one exact action capability

`POST /v1/capabilities/redeem`

## Request

- Base URL: `https://api.thrd.email`
- URL: `https://api.thrd.email/v1/capabilities/redeem`
- Auth: HTTP bearer

Verify the compact JWS locally first with the pinned public key, then authenticate with a distinct executor credential. Agent API keys are rejected. Tenant, environment, executor principal, tool and target come from the signed claims plus the server-owned registration, never caller JSON.

## Request body

- object
  - `capability_token` string, required: Compact single-use thrd-cap+jwt JWS.

## Response `200`

The capability transitioned from issued to redeemed exactly once.

- object
  - `redemption_id` string, uuid, required
  - `capability_id` string, uuid, required
  - `status` 'redeemed', required
  - `action` object, required
    - `id` string, required
    - `hash` string, required
    - `type` string, required
  - `decision_id` string, uuid, required
  - `receipt_id` string, uuid, required
  - `redeemed_at` string, date-time, required

## Other responses

- `400`: Strict redemption body invalid
- `401`: Missing or invalid executor credential
- `403`: Capability or executor binding invalid
- `409`: Capability already used or not active
- `410`: Capability expired or revoked
- `429`: Executor redemption rate limit exceeded
- `503`: Capability feature or authority unavailable

---

[API](https://skmtc.dev/thrd/apis/thrd-agent-email-api.md) · [All operations](https://skmtc.dev/thrd/apis/thrd-agent-email-api/llms.txt) · [OpenAPI document](https://skmtc.dev/thrd/apis/thrd-agent-email-api/revisions/d8a88129cd34?raw)