List Contracts

Returns contracts whose job is referenced by at least one project link on the calling token’s install, newest first. This is the pull-side complement to the contract.started / contract.ended webhooks — poll it to reconcile state after downtime, since events are never replayed.

Requirements: contracts:read scope.

Request

projectLinkIdstringquery

Restrict to contracts on the job linked by this project link. Returns 404 if no link with this ID exists on the install.

statusstringquery

Filter by contract status: active or ended.

limitintegerquery

Default: 50

Maximum number of contracts to return (1–200).

Response

contractsobject[]

Array of contracts, newest first.

Contract fields

idstring

Contract ID. Use it with GET /contracts/{contractId}/participants.

statusstring

active or ended.

jobIdstring

The OpenTrain job the contract belongs to.

titlestring | null

Contract title.

startDatestring | null

ISO 8601 start timestamp.

endDatestring | null

ISO 8601 end timestamp — null while the contract is active.

createdAtstring

ISO 8601 creation timestamp.

projectLinkIdsstring[]

Project links on this install referencing the contract job.

Errors

Status	code	Meaning
400	BAD_REQUEST	Invalid status value or limit out of range
401	UNAUTHORIZED	Missing, invalid, or revoked token
403	FORBIDDEN	Token lacks contracts:read
404	NOT_FOUND	projectLinkId does not match a link on this install

Request examples

curl

curl -sS "https://app.opentrain.ai/api/partner/v1/contracts?status=active&limit=50" \
  -H "Authorization: Bearer $OT_PARTNER_TOKEN"

Response examples

200

{
  "contracts": [
    {
      "id": "<CONTRACT_ID>",
      "status": "active",
      "jobId": "<OPENTRAIN_JOB_ID>",
      "title": "Traffic signs batch 3 — annotation",
      "startDate": "2026-06-12T10:00:00.000Z",
      "endDate": null,
      "createdAt": "2026-06-12T10:00:00.000Z",
      "projectLinkIds": ["<LINK_ID>"]
    }
  ]
}