Create Admin-Balance Milestone

curl -sS -X POST https://app.opentrain.ai/api/public/v1/contracts/<CONTRACT_ID>/admin-balance-milestones \
  -H "Authorization: Bearer $OT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "later-milestone-2026-09",
    "milestone": {
      "name": "Approved bonus",
      "description": "Complete the approved bonus work",
      "amountUsd": 300,
      "volume": 2.5
    }
  }'

opentrain admin-balance-milestones create \
  --contract-id <CONTRACT_ID> \
  --idempotency-key later-milestone-2026-09 \
  --description "Complete the approved bonus work" \
  --name "Approved bonus" \
  --amount 300 \
  --volume 2.5 \
  --json

{
  "contractId": "<CONTRACT_ID>",
  "idempotencyKey": "later-milestone-2026-09",
  "name": "Approved bonus",
  "description": "Complete the approved bonus work",
  "amountUsd": 300,
  "volume": 2.5
}

POST

api

public

contracts

{contractId}

admin-balance-milestones

curl -sS -X POST https://app.opentrain.ai/api/public/v1/contracts/<CONTRACT_ID>/admin-balance-milestones \
  -H "Authorization: Bearer $OT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "later-milestone-2026-09",
    "milestone": {
      "name": "Approved bonus",
      "description": "Complete the approved bonus work",
      "amountUsd": 300,
      "volume": 2.5
    }
  }'

opentrain admin-balance-milestones create \
  --contract-id <CONTRACT_ID> \
  --idempotency-key later-milestone-2026-09 \
  --description "Complete the approved bonus work" \
  --name "Approved bonus" \
  --amount 300 \
  --volume 2.5 \
  --json

{
  "contractId": "<CONTRACT_ID>",
  "idempotencyKey": "later-milestone-2026-09",
  "name": "Approved bonus",
  "description": "Complete the approved bonus work",
  "amountUsd": 300,
  "volume": 2.5
}

Creates a later milestone and marks it ACTIVE_FUNDED through OpenTrain’s restricted internal-balance workflow. This endpoint is for eligible OpenTrain platform administrators in the canonical admin organization; it is not an alternative funding method for ordinary employers. At the funding step, the operation moves $0 and creates no Stripe charge or PaymentIntent. Releasing the funded milestone later is a separate action that still requires human authorization. For hourly and per-label contracts, send a positive volume or omit it so OpenTrain derives the value from amountUsd and the canonical contract rate. When all three values are present, they must agree.

Authorization

The server independently verifies the restricted scope, claimed account, platform-admin status, canonical admin-organization membership, Admin Pay eligibility, matching token organization, target organization, and the default-off rollout. Possessing the scope alone never grants access.

Request

string

required

Contract that will own the new milestone.

string

required

Stable request key, 1–128 characters. Reuse it only for an identical retry.

string

required

Work covered by the milestone.

number

required

Positive milestone amount in USD.

number

Positive hours or labels for a volume-based contract. Omit to derive it from the amount and canonical rate.

string

Optional short milestone name.

string

Optional ISO 8601 due date.

Response

Returns 201 for a new milestone or 200 for an identical idempotent replay. The result includes the contract and job IDs, the milestone ID and status, fundingSource: "ADMIN_BALANCE", moneyMoved: false, releaseRequiresHumanApproval: true, and idempotentReplay.

TypeScript SDK

@opentrain-ai/sdk 0.22.0 or later exposes the same operation:

import { OpenTrainClient } from '@opentrain-ai/sdk';

const opentrain = new OpenTrainClient({
  apiToken: process.env.OPENTRAIN_API_TOKEN!,
});

const result = await opentrain.createAdminBalanceMilestone('<CONTRACT_ID>', {
  idempotencyKey: 'later-milestone-2026-09',
  milestone: {
    description: 'Complete the approved bonus work',
    amountUsd: 300,
    volume: 2.5,
  },
});

Errors

Status	Meaning
`400`	Invalid key or milestone fields, including an invalid or inconsistent volume
`401`	Missing or invalid token
`403`	One or more restricted platform-admin authorization conditions failed
`404`	Contract not found within the authorized organization boundary
`409`	Conflicting idempotency reuse, an in-progress request, or a milestone sequencing conflict

curl -sS -X POST https://app.opentrain.ai/api/public/v1/contracts/<CONTRACT_ID>/admin-balance-milestones \
  -H "Authorization: Bearer $OT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "later-milestone-2026-09",
    "milestone": {
      "name": "Approved bonus",
      "description": "Complete the approved bonus work",
      "amountUsd": 300,
      "volume": 2.5
    }
  }'

opentrain admin-balance-milestones create \
  --contract-id <CONTRACT_ID> \
  --idempotency-key later-milestone-2026-09 \
  --description "Complete the approved bonus work" \
  --name "Approved bonus" \
  --amount 300 \
  --volume 2.5 \
  --json

{
  "contractId": "<CONTRACT_ID>",
  "idempotencyKey": "later-milestone-2026-09",
  "name": "Approved bonus",
  "description": "Complete the approved bonus work",
  "amountUsd": 300,
  "volume": 2.5
}

⌘I

Getting started

Connect your agent

Core concepts

Guides

API reference

CLI

MCP server

Annotation platforms

Create Admin-Balance Milestone

Authorization

Request

Response

TypeScript SDK

Errors

​Authorization

​Request

​Response

​TypeScript SDK

​Errors

Authorization

Request

Response

TypeScript SDK

Errors