Add a milestone

Adds work a contractor is to be paid for, checked by the rules of the console's Add milestone form, and recorded in the ledger as create_milestone with via: "api" and the key's id. It is added as the key's issuer's: if the agent holds it on its own judgment, someone other than the issuer must choose Pay now, unless the issuer is the workspace's only approver.

It starts pending, and the API cannot verify it. A GitHub pull request in verificationSource is checked by the agent, which verifies the milestone once the pull request is merged; any other link is evidence for the person who verifies it on Contractors. Once it is verified, the agent decides the payment with every guardrail, and pays only to the contractor's confirmed address. A contractorId the workspace does not hold, or a client's, answers 400.

Send a workspace API key with read and write access as Authorization: Bearer …. A read-only key gets 403.

Parameters#

• Idempotency-Keystringoptionalin: header

  Makes a retry safe: up to 255 printable ASCII characters, unique to the record being added, such as its id in your own system. A repeat with the same key and the same body within 24 hours gets the first answer back, with Idempotent-Replayed: true, and adds nothing. The same key with a different body answers 409.

Request body#

{
  "contractorId": "26d6ffed-356d-474a-8d42-89bc942f6b4e",
  "title": "TypeScript SDK for the API",
  "amount": "0.10",
  "verificationSource": "https://github.com/duongnq2798/vestiarion/pull/176"
}

Try it#

Try it is off for operations that add records: run the sample with your own key.

Code samples#

curl "https://www.vestiarion.xyz/api/v1/milestones" \
  -X POST \
  -H "Authorization: Bearer $VESTIARION_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ci-bounty-pr-176" \
  -d '{"contractorId":"26d6ffed-356d-474a-8d42-89bc942f6b4e","title":"TypeScript SDK for the API","amount":"0.10","verificationSource":"https://github.com/duongnq2798/vestiarion/pull/176"}'

Response#

{
  "data": {
    "id": "354132aa-e7f6-46f8-ae3c-aa6809f9b9b6",
    "title": "TypeScript SDK for the API",
    "amount": 0.1,
    "status": "pending",
    "verificationSource": "https://github.com/duongnq2798/vestiarion/pull/176",
    "verificationMethod": "unverified",
    "verificationStatus": "unverified",
    "verificationCheckedAt": null,
    "verifiedAt": null,
    "verificationDetail": {},
    "verified": false,
    "decidedAt": null,
    "settledAt": null,
    "closedAt": null,
    "closeReason": null,
    "agentReasoning": null,
    "txHash": null,
    "contractor": {
      "id": "26d6ffed-356d-474a-8d42-89bc942f6b4e",
      "name": "API Test Contractor",
      "riskLevel": "clear"
    },
    "createdAt": "2026-10-03T15:43:09.204631+00:00"
  }
}

Errors#