> ## Documentation Index
> Fetch the complete documentation index at: https://opentrain.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Assign and Update Project To-dos

> Reissue the current version to a stated audience, or publish a new immutable version with an optional reissue.

Both actions require `project_todos:write`, a claimed account, and employer access to the job. Both fan out only to an explicit audience, and broad audiences require a fresh `preflightReceipt` for the exact request.

## `assign`

Assigns the item's current version to the stated audience. Recipients who already hold this operation's assignment are skipped, so a same-key retry converges instead of duplicating obligations. A new assignment supersedes that person's stale open copy of the same item; submitted work stays reviewable.

<ParamField body="action" type="string" required>`assign`</ParamField>

<ParamField body="idempotencyKey" type="string" required />

<ParamField body="jobId" type="string" required />

<ParamField body="itemId" type="string" required />

<ParamField body="audience" type="string" required>
  No default. `FUTURE` and `ACTIVE_AND_FUTURE` also turn on future-hire auto-assignment for the item.
</ParamField>

<ParamField body="selectedContractIds" type="string[]">`SELECTED` only; validated strictly.</ParamField>

<ParamField body="preflightReceipt" type="string">
  Required for broad audiences; bound to the item's current version, so a version published between preflight and assign invalidates it.
</ParamField>

The response mirrors `create_item`: audience echo, `fanOut`, and masked `recipients`.

## `update_item`

Publishes a new immutable version of the definition. With `assign`, the new version is issued to the stated audience in the same transaction, superseding stale open assignments; without it, nothing is reissued.

<ParamField body="action" type="string" required>`update_item`</ParamField>

<ParamField body="idempotencyKey" type="string" required />

<ParamField body="jobId" type="string" required />

<ParamField body="itemId" type="string" required />

<ParamField body="version" type="object" required>The complete new definition.</ParamField>

<ParamField body="assign" type="object">
  Optional reissue: `audience`, `selectedContractIds`, and `preflightReceipt` for broad audiences — bound to the item and the exact new definition.
</ParamField>

<Warning>
  Every `update_item` call publishes another version — retries are not convergent. If a call's outcome is uncertain, read the item before sending again instead of blind-retrying.
</Warning>