Skip to content
OpenTrain AIOpenTrain AIOpenTrain AIDocs

Ask OpenTrain

Answers from the documentation, with sources.

What would you like to do with OpenTrain?

AI answers can be mistaken. Check the linked sources. Don’t include private account information.

Open app

DEVELOPER DOCUMENTATION

Create a Project To-do

Create one item and its initial assignments atomically, with an explicit audience and a request-bound idempotency key.

Use with AI
View as MarkdownOpen in ChatGPTOpen in ClaudeOpen in PerplexityAdd to CursorAdd to VS Code
POST/api/public/v1/project-todos/manage

Creates one to-do item, its first immutable version, and every initial assignment in a single transaction. Requires project_todos:write, a claimed account, and employer access to the job.

actionstringbodyrequired
create_item
idempotencyKeystringbodyrequired

8–200 characters, bound to the complete request. Reuse the same key only to retry the identical request.

jobIdstringbodyrequired
audiencestringbodyrequired

ACTIVE, FUTURE, ACTIVE_AND_FUTURE, or SELECTED. There is no default — omission fails with 400.

selectedContractIdsstring[]body

SELECTED only: a non-empty, duplicate-free list of active contracts on this exact job (up to 500). Invalid IDs reject the whole request with per-ID reasons.

preflightReceiptstringbody

Required for ACTIVE, FUTURE, and ACTIVE_AND_FUTURE. Mint it with preflight.

versionobjectbodyrequired

The worker-facing definition: title, type, optional description, content, ownerRole, required, priority (NORMAL | HIGH | URGENT), blockingMode (NONE | IMMEDIATE | AFTER_DUE), blockingScope, dueOffsetMinutes, reminderPolicy, and completionConfig.

categoryIdstringbody
Optional category; omitting uses the job’s General category.
keystringbody
Optional stable item key.
autoAssignNewHiresbooleanbody

Adds future-hire auto-assignment to ACTIVE. Not allowed with SELECTED.

allowDuplicatebooleanbody

Overrides the 409 LIKELY_DUPLICATE refusal when an active item already carries this exact request.

Response

Section titled “Response”
{
  "ok": true,
  "action": "create_item",
  "itemId": "…",
  "versionId": "…",
  "audience": "SELECTED",
  "includesFutureHires": false,
  "fanOut": { "matchedContracts": 1, "createdAssignments": 1, "assignmentIds": ["…"] },
  "recipients": [{ "contractId": "…", "workerUserId": "…", "displayName": "Alex B." }],
  "replayed": false,
  "warnings": []
}

recipients are the masked people this exact request was verified against. On an identical-request retry, replayed is true, createdAssignments is 0, and the roster is not re-resolved — a person hired after the original create is never silently added.

Failure modes

Section titled “Failure modes”

Beyond the common errors: the reserved time-tracking setup to-do cannot be authored here, and integration-type items require the matching configured provider on the job.