---
title: "Claim Action"
method: POST
path: "/chats/{chat_id}/actions/{action_id}/claim"
tags: ["Chat actions"]
---

# Claim Action

`POST /chats/{chat_id}/actions/{action_id}/claim`

## Request

- Base URL: `https://api.excellence-ai.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.excellence-ai.com/chats/{chat_id}/actions/{action_id}/claim`
- Auth: OAuth 2 (password, token URL `api/login`)

Before the browser runs an action it applies itself: only the
response carrying a `claim_token` may run it.

## Path parameters

- `chat_id` string, required
- `action_id` string, required

## Request body

- ChatActionApply
  - `arguments` object, nullable

## Response `200`

Successful Response

- ChatActionClaimResponse: The claim of an action the browser applies. `claim_token` is set only for the request that won the claim: run the applier then, and only then, and report with it. Without it, show `action` as it is (another tab or an earlier click holds it, or it is already decided).
  - `action` PendingActionResponse, required
    - `id` string, required
    - `chat_id` string, required
    - `tool` string, required
    - `label` string, required
    - `danger` 'safe' | 'destructive', required
    - `applied_by` 'server' | 'client', required
    - `auto_open` boolean
    - `arguments` object, required
    - `preview` ActionPreview, required: What the card shows before the user decides, built by the tool's `preview` hook from the validated arguments. Readable names only, never raw ids: this is what the user confirms.
      - `lines` string[]
      - `losses` string[]
      - `title` string, nullable
      - `apply_label` string, nullable
      - `data` object
      - `danger` 'safe' | 'destructive', nullable
      - `pin` string, nullable
      - `outdated_message` string, nullable
    - `status` 'pending' | 'applying' | 'applied' | 'failed' | 'dismissed' | 'undoing' | 'undone', required
    - `outcome_unknown` boolean
    - `dismissed_unknown` boolean
    - `undoable` boolean, required
    - `can_undo` boolean, required
    - `result_summary` object, required
    - `error` ActionError
      - `code` 'not_found' | 'rejected' | 'partial' | 'error', required
      - `message` string
    - `undo_error` ActionError
      - `code` 'not_found' | 'rejected' | 'partial' | 'error', required
      - `message` string
  - `claim_token` string, nullable

## Other responses

- `404`: Resource not found
- `409`: The action's tool or state does not allow this request
- `422`: Edited arguments fail the tool's schema; the action stays pending

## Changes

> 55 revisions in range; 1 not diffed.

- **2026-10-23** `aa42640c0a6b`: 1 info
  - added the optional property `action/preview/outdated_message` to the response with the `200` status
- **2026-10-21** `1d6009058248`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/excellence-ai/apis/excellence-learning/changes/chats/:chat_id/actions/:action_id/claim/post.md)

---

[API](https://skmtc.dev/excellence-ai/apis/excellence-learning.md) - [All operations](https://skmtc.dev/excellence-ai/apis/excellence-learning/llms.txt) - [OpenAPI document](https://skmtc.dev/excellence-ai/apis/excellence-learning/revisions/379e4a57dee8?raw)