Create Milestone

Adds a new milestone to an active contract. The milestone is created unfunded (NOT_FUNDED) — no money moves at creation. To put money behind it, request funding afterwards; a signed-in human must confirm that step (see human approvals).

The amount must fit the contract’s payment model: fixed-price contracts require amountUsd; hourly and per-label contracts require volume, and when both amountUsd and volume are given the amount must equal the contract rate × volume.

Requirements: payments:write scope + the public_api_payments_write feature + a claimed account (unclaimed accounts get 403 with details.reason: "account_claim_required" and a claimUrl). The contract must be yours and still active.

Request

contractIdstringpathrequired

The contract to add the milestone to.

descriptionstringbodyrequired

Description of the work to deliver. Must be non-empty.

namestringbody

Optional short milestone name.

amountUsdnumberbody

Milestone amount in USD. Must be positive. Required for fixed-price contracts.

volumenumberbody

Unit volume (e.g. label count or hours). Must be positive. Required for hourly and per-label contracts.

dueDatestringbody

Optional due date (ISO 8601).

Response

Returns 201 with the created milestone.

milestoneobject

milestone

idstring

Milestone ID — pass to POST /milestones/{id}/fund to request escrow funding.

namestring | null

Milestone name.

descriptionstring | null

Work to deliver.

statusstring | null

NOT_FUNDED on creation.

amountUsdnumber | null

Milestone amount in USD.

volumenumber | null

Unit volume.

milestoneNumbernumber | null

Position in the contract’s milestone sequence.

dueDatestring | null

ISO due date.

pendingApprovalboolean

false on creation.

needsReviewboolean

false on creation.

invoiceIdstring | null

null until funded.

createdAtstring

ISO creation timestamp.

Errors

Status	code	Meaning
400	BAD_REQUEST	Invalid JSON, or field errors (details.field names the offender): description missing/empty, amountUsd required for fixed-price contracts, volume required for hourly and per-label contracts, or the amount does not match the contract rate and volume
401	UNAUTHORIZED	Missing or invalid token
403	FORBIDDEN	Missing payments:write scope, public_api_payments_write disabled, or account not claimed (details.reason: "account_claim_required", details.claimUrl)
404	NOT_FOUND	No such contract, or the contract is on another account
409	CONFLICT	details.reason: "contract_ended" (contract already ended) or "contract_rate_missing" (contract has no rate to validate against)

Request examples

curlCLIMCP: opentrain_create_milestone

curl

curl -sS -X POST https://app.opentrain.ai/api/public/v1/contracts/<CONTRACT_ID>/milestones \
  -H "Authorization: Bearer $OT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Second labeling batch",
    "description": "Label the next 5,000 posts per the updated guidelines",
    "amountUsd": 300,
    "dueDate": "2026-07-15"
  }'

CLI

opentrain milestones create --contract-id <CONTRACT_ID> \
  --description "Label the next 5,000 posts per the updated guidelines" \
  --name "Second labeling batch" --amount 300 --due-date 2026-07-15 --json

MCP: opentrain_create_milestone

{
  "contractId": "<CONTRACT_ID>",
  "name": "Second labeling batch",
  "description": "Label the next 5,000 posts per the updated guidelines",
  "amountUsd": 300,
  "dueDate": "2026-07-15"
}

Response examples

201409 (contract ended)

201

{
  "milestone": {
    "id": "<MILESTONE_ID>",
    "name": "Second labeling batch",
    "description": "Label the next 5,000 posts per the updated guidelines",
    "status": "NOT_FUNDED",
    "amountUsd": 300,
    "volume": null,
    "milestoneNumber": 2,
    "dueDate": "2026-07-15T00:00:00.000Z",
    "pendingApproval": false,
    "needsReview": false,
    "invoiceId": null,
    "createdAt": "2026-06-12T10:00:00.000Z"
  }
}

409 (contract ended)

{
  "error": "Contract has ended",
  "code": "CONFLICT",
  "requestId": "<REQUEST_ID>",
  "details": {
    "contractId": "<CONTRACT_ID>",
    "reason": "contract_ended"
  }
}