---
title: "Claim an External-mode decision task"
method: POST
path: "/v1/decision-tasks/{id}/claim"
tags: ["Apps"]
---

# Claim an External-mode decision task

`POST /v1/decision-tasks/{id}/claim`

## Request

- Base URL: `https://api.talonic.com`
- URL: `https://api.talonic.com/v1/decision-tasks/{id}/claim`
- Auth: HTTP bearer

Takes the exclusive lease, bumps `execution_epoch`, and returns the decision bundle: task metadata, the output contract, the run's precedent block, and a package DESCRIPTOR. The package itself is read in pages through `GET /v1/decision-tasks/{id}/package`.

## Path parameters

- `id` string, uuid, required

## Response `200`

The decision bundle for the claimed task.

- DecisionTaskBundle
  - `task` DecisionTaskMetadata, required
    - `id` string, uuid, required
    - `customer_id` string, uuid, required
    - `run_id` string, uuid, required
    - `app_id` string, uuid, required
    - `status` 'available' | 'claimed' | 'submitted' | 'released' | 'failed' | 'timed_out' | 'cancelled', required
    - `execution_epoch` integer, required
    - `input_package_ref` string: Where the frozen package lives; `run` in v1.
    - `lease_seconds` integer
    - `claimed_by` string, nullable: The claimant: an API key id, or `oauth:<client_id>:<user_id>` for an OAuth session.
    - `claimed_at` string, date-time, nullable
    - `lease_expires_at` string, date-time, nullable
    - `heartbeat_at` string, date-time, nullable
    - `sla_deadline_at` string, date-time, required: Hard decision deadline; heartbeats never extend the lease past it.
    - `submitted_at` string, date-time, nullable
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
  - `output_contract` object, required: For a `single` contract, the bare JSON Schema the submitted `outcome` must validate against (unchanged wire shape). For `verdict_matrix` and `record_set` contracts, the wrapped form `{ kind, schema }`: the client submits the envelope that kind defines (see DecisionTaskSubmit) and the platform validates it against the app version's declaration.
  - `precedents` object[], required: Precedent references injected into this run's context.
  - `package` DecisionTaskPackageDescriptor, required
    - `package_kind` 'records' | 'mining_round': `records` for a frozen input package; `mining_round` when the task stands for a mining round driven from outside, whose package is one record carrying the prompts the hosted model would have seen (record_count 1).
    - `record_count` integer, required: Total records across every binding of the frozen package; 1 for a mining round.
    - `page_size` integer, required: Default page size for GET /v1/decision-tasks/{id}/package.
    - `first_cursor` string, nullable, required: Cursor for the first page; null when the package holds no records.
    - `documents` DecisionTaskPackageDocument[]: Source documents the package's cells cite, unique, first-seen order; empty on runs assembled before enrichment. Bytes are served by `GET /v1/documents/{id}/file`, which applies Sources IAM as the key's minting user.
      - `document_id` string, uuid, required
      - `filename` string, nullable, required
      - `mime_type` string
      - `file_url` string, required: Relative API path, `/v1/documents/{id}/file`.

## Other responses

- `401`: Missing or invalid API key.
- `403`: The API key does not have the required scope.
- `404`: The requested resource was not found.
- `409`: The request conflicts with the current resource state.
- `429`: Daily rate limit exceeded.

---

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