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

Project To-dos API

HTTP reference for reading, previewing, and mutating the required job actions assigned to hired AI trainers.

Use with AI
View as MarkdownOpen in ChatGPTOpen in ClaudeOpen in PerplexityAdd to CursorAdd to VS Code

The Project To-dos API reads and edits the same continuous list shown in a job’s employer Project To-dos tab and in each AI trainer’s manage-job view.

Base path: /api/public/v1/project-todos

Endpoints

Section titled “Endpoints”
MethodPathPurpose
GET/project-todosList the catalog, roster, assignments, and summary for a job or one contract.
POST/project-todos/manageOne discriminated action union for every preview and mutation.
GET/project-todos/export-csvDownload per-person statuses as CSV (emails redacted).
GET/project-todos/quizzes/…Quiz reads — see the quiz surface.
POST/project-todos/quizzes/manageQuiz authoring, assignment, grading, release, and retakes.

Manage actions

Section titled “Manage actions”

POST /project-todos/manage dispatches on action:

ActionPurpose
preflightNo-write preview and receipt mint for create_item, update_item, assign, or archive_item.
set_enabledTurn the job’s Project To-dos surface on or off. Disabling requires active time-tracking integrations to be off first.
create_categoryCreate a grouping category (idempotent per key).
create_itemCreate one item and its initial assignments atomically.
update_itemPublish a new immutable version, optionally reissuing it.
archive_itemRetire an item; open assignments close with an audited reason.
assignRe-run assignment of the current version to a stated audience.
worker_transitionAI trainer actions: VIEW, START, COMPLETE, SUBMIT.
reviewEmployer decisions: APPROVE, RETURN, WAIVE, CLOSE.

Authorization

Section titled “Authorization”

List, export, and quiz reads require project_todos:read. Every manage action requires project_todos:write and a claimed account, plus employer access to the job (or, for worker_transition, ownership of the contract). The account must also have the default-off project_todos_integrations agent-surface family enabled. Scope failures return 403 with the missing resource named in details; a disabled family returns 403 with details.reason = "AGENT_SURFACE_DISABLED".

Write safety

Section titled “Write safety”
  • audience is required on every fan-out — omission is a 400, never a broadcast. See the concept page for audience semantics.
  • Broad audiences require a preflightReceipt from a matching preflight call.
  • Every mutating action requires idempotencyKey (8–200 characters). Creation keys are bound to the complete request.
  • Item creation, version publication, and assignment fan-out commit in one transaction.

Common errors

Section titled “Common errors”
Statusdetails.reasonMeaning
400—Validation failure; SELECTED offenders are listed in details.invalidContractIds with per-ID reasons (UNKNOWN_CONTRACT, DIFFERENT_JOB, CONTRACT_ENDED, NO_ACTIVE_WORKER) and duplicates in details.duplicateContractIds.
409PROJECT_TODOS_DISABLEDEnable Project To-dos in Job Settings first.
409PREFLIGHT_RECEIPT_REQUIRED / PREFLIGHT_RECEIPT_INVALID / PREFLIGHT_RECEIPT_EXPIRED / PREFLIGHT_RECEIPT_STALEThe broad-audience receipt is missing, unverifiable, past its ~15-minute life, or no longer matches the live roster or exact request (details.changed names what moved). Run preflight again.
409RECIPIENTS_CHANGEDThe roster changed between confirmation and the write; details lists added and removed contract IDs. Preflight again.
409LIKELY_DUPLICATEAn active item with this exact request already exists (details.duplicates); pass allowDuplicate: true to create anyway.
409—An idempotency key was reused with a different request.

Use the machine-readable OpenAPI document for complete schemas.