Update Job Draft

curl -sS -X PATCH https://app.opentrain.ai/api/public/v1/job-drafts/<JOB_ID> \
  -H "Authorization: Bearer $OT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "experienceLevel": "INTERMEDIATE",
    "paymentType": "PAY_PER_LABEL",
    "pricePerLabel": 0.06
  }'

opentrain jobs draft update --job-id <JOB_ID> \
  --set experienceLevel=INTERMEDIATE \
  --set paymentType=PAY_PER_LABEL \
  --set pricePerLabel=0.06 --json

{
  "jobId": "<JOB_ID>",
  "patch": {
    "experienceLevel": "INTERMEDIATE",
    "paymentType": "PAY_PER_LABEL",
    "pricePerLabel": 0.06
  }
}

{
  "ok": true,
  "jobId": "<JOB_ID>",
  "status": "DRAFT",
  "draftUrl": "https://app.opentrain.ai/job-post?jobId=<JOB_ID>",
  "validation": {
    "publishReady": true,
    "issueCount": 0,
    "missingFieldCount": 0,
    "missingFields": [],
    "issues": []
  }
}

{
  "error": "Invalid payload",
  "code": "BAD_REQUEST",
  "requestId": "<REQUEST_ID>",
  "details": {
    "formErrors": [],
    "fieldErrors": {
      "experienceLevel": [
        "Invalid enum value. Expected 'EXPERT' | 'ENTRY_LEVEL' | 'INTERMEDIATE' | 'ANY_EXPERIENCE_LEVEL', received 'SENIOR'"
      ]
    }
  }
}

PATCH

api

public

job-drafts

{jobId}

curl -sS -X PATCH https://app.opentrain.ai/api/public/v1/job-drafts/<JOB_ID> \
  -H "Authorization: Bearer $OT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "experienceLevel": "INTERMEDIATE",
    "paymentType": "PAY_PER_LABEL",
    "pricePerLabel": 0.06
  }'

opentrain jobs draft update --job-id <JOB_ID> \
  --set experienceLevel=INTERMEDIATE \
  --set paymentType=PAY_PER_LABEL \
  --set pricePerLabel=0.06 --json

{
  "jobId": "<JOB_ID>",
  "patch": {
    "experienceLevel": "INTERMEDIATE",
    "paymentType": "PAY_PER_LABEL",
    "pricePerLabel": 0.06
  }
}

{
  "ok": true,
  "jobId": "<JOB_ID>",
  "status": "DRAFT",
  "draftUrl": "https://app.opentrain.ai/job-post?jobId=<JOB_ID>",
  "validation": {
    "publishReady": true,
    "issueCount": 0,
    "missingFieldCount": 0,
    "missingFields": [],
    "issues": []
  }
}

{
  "error": "Invalid payload",
  "code": "BAD_REQUEST",
  "requestId": "<REQUEST_ID>",
  "details": {
    "formErrors": [],
    "fieldErrors": {
      "experienceLevel": [
        "Invalid enum value. Expected 'EXPERT' | 'ENTRY_LEVEL' | 'INTERMEDIATE' | 'ANY_EXPERIENCE_LEVEL', received 'SENIOR'"
      ]
    }
  }
}

Patches any subset of fields on an unpublished draft and returns refreshed validation. This is the second half of the gap-filling loop: take each missing field’s updateKeys and enumValues from the create response, ask your human the prompt, and patch the answers. Repeat until validation.publishReady is true, then publish. The accepted keys and enum values are machine-discoverable at GET /job-drafts/capabilities (draft.updateKeys and draft.enums). Requirements: jobs:write scope + the public_api_job_drafting feature. The job must be an unpublished draft you own — to edit a live job use PATCH /jobs/{id}.

Request

string

required

The draft job ID from the create response.

The body is a JSON object with one or more draft fields. Unknown keys are rejected (400 with zod issue details). Commonly patched keys:

string

Job title.

string

Full description text.

string

PAY_PER_LABEL, PAY_PER_HOUR, or FIXED_PRICE. Pair with the matching rate field below.

number

Hourly rate in USD (for PAY_PER_HOUR).

number

Per-label rate in USD (for PAY_PER_LABEL).

number

Total fixed price in USD (for FIXED_PRICE).

string

EXPERT, ENTRY_LEVEL, INTERMEDIATE, or ANY_EXPERIENCE_LEVEL.

string

HOURS_OF_RECORDING_AUDIO_VIDEO, NUMBER_OF_FILES, NUMBER_OF_WORDS, or UNKNOWN_NOT_SPECIFIED.

string[]

Required languages.

string[]

Allowed countries.

string[]

Label/annotation types.

number

Number of AI trainers to hire.

number

Quantity of data, in dataVolumeUnit units.

The full key list also includes labelingOverview, datasetDescription, dataType, subjectMatter, labelingSoftware, aiInterviewRequirements, budgetRange, workloadDesc, timeRequirement, projectDuration, freelancerType, projectScope, visibility, and more — fetch draft.updateKeys from capabilities for the authoritative set. Enum fields must use the exact canonical values above.

Response

boolean

true on success.

string

The draft job ID.

string

Still DRAFT.

string

In-app URL of the draft editor.

object

Refreshed validation — same shape as the create response: publishReady, issueCount, missingFieldCount, missingFields[] (with prompt/type/enumValues/updateKeys), issues[].

Errors

Status	`code`	Meaning
`400`	`BAD_REQUEST`	Empty body, invalid JSON, unknown keys or wrong types (`details` carries zod issues), or no fields set
`401`	`UNAUTHORIZED`	Missing or invalid token
`403`	`FORBIDDEN`	Missing `jobs:write` scope, feature disabled, or the job belongs to another account
`404`	`NOT_FOUND`	No such job

curl -sS -X PATCH https://app.opentrain.ai/api/public/v1/job-drafts/<JOB_ID> \
  -H "Authorization: Bearer $OT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "experienceLevel": "INTERMEDIATE",
    "paymentType": "PAY_PER_LABEL",
    "pricePerLabel": 0.06
  }'

opentrain jobs draft update --job-id <JOB_ID> \
  --set experienceLevel=INTERMEDIATE \
  --set paymentType=PAY_PER_LABEL \
  --set pricePerLabel=0.06 --json

{
  "jobId": "<JOB_ID>",
  "patch": {
    "experienceLevel": "INTERMEDIATE",
    "paymentType": "PAY_PER_LABEL",
    "pricePerLabel": 0.06
  }
}

{
  "ok": true,
  "jobId": "<JOB_ID>",
  "status": "DRAFT",
  "draftUrl": "https://app.opentrain.ai/job-post?jobId=<JOB_ID>",
  "validation": {
    "publishReady": true,
    "issueCount": 0,
    "missingFieldCount": 0,
    "missingFields": [],
    "issues": []
  }
}

{
  "error": "Invalid payload",
  "code": "BAD_REQUEST",
  "requestId": "<REQUEST_ID>",
  "details": {
    "formErrors": [],
    "fieldErrors": {
      "experienceLevel": [
        "Invalid enum value. Expected 'EXPERT' | 'ENTRY_LEVEL' | 'INTERMEDIATE' | 'ANY_EXPERIENCE_LEVEL', received 'SENIOR'"
      ]
    }
  }
}

Create Job Draft

Get Drafting Capabilities

⌘I

Getting started

Connect your agent

Core concepts

Guides

API reference

CLI

MCP server

Annotation platforms

Request

Response

Errors

​Request

​Response

​Errors

Request

Response

Errors