Create Project Link

Creates a project link mapping one of your projects to an OpenTrain job. Contract lifecycle events are emitted only for linked jobs, so this is the routing step of the integration. Emits a project_link.created event.

Requirements: project-links:write scope.

Request

externalProjectIdstringbodyrequired

Your project’s identifier (max 200 chars). Unique per install — reusing one returns 409.

externalProjectNamestringbody

Human-readable project name (max 300 chars).

externalProjectUrlstringbody

Deep link to the project in your platform (max 2048 chars).

jobIdstringbody

The OpenTrain job to link. Must be a job owned by the installing employer — anything else returns 404. A link without a job receives no contract events until it points at one.

provisioningModestringbody

Default: PARTNER_WEBHOOK

PARTNER_WEBHOOK (you provision workspace members from webhook events — recommended) or MANAGED_ADAPTER (the OpenTrain managed-credential path). See provisioning modes.

Response

projectLinkobject

The created link: {id, jobId, externalProjectId, externalProjectName, externalProjectUrl, provisioningMode, createdAt}.

Errors

Status	code	Meaning
400	BAD_REQUEST	Body not valid JSON, externalProjectId missing, or a field exceeds its length limit
401	UNAUTHORIZED	Missing, invalid, or revoked token
403	FORBIDDEN	Token lacks project-links:write
404	NOT_FOUND	jobId does not reference a job owned by the installing employer
409	CONFLICT	Duplicate externalProjectId for this install, or the install’s link limit is reached

Request examples

curl

curl -sS -X POST https://app.opentrain.ai/api/partner/v1/project-links \
  -H "Authorization: Bearer $OT_PARTNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "externalProjectId": "42",
    "externalProjectName": "Traffic signs batch 3",
    "externalProjectUrl": "https://your-platform.example.com/projects/42",
    "jobId": "<OPENTRAIN_JOB_ID>",
    "provisioningMode": "PARTNER_WEBHOOK"
  }'

Response examples

201409 (duplicate)

201

{
  "projectLink": {
    "id": "<LINK_ID>",
    "jobId": "<OPENTRAIN_JOB_ID>",
    "externalProjectId": "42",
    "externalProjectName": "Traffic signs batch 3",
    "externalProjectUrl": "https://your-platform.example.com/projects/42",
    "provisioningMode": "PARTNER_WEBHOOK",
    "createdAt": "2026-06-12T10:00:00.000Z"
  }
}

409 (duplicate)

{
  "error": "A project link with this externalProjectId already exists for this install.",
  "code": "CONFLICT",
  "requestId": "<REQUEST_ID>"
}