Update Job Draft

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

jobIdstringpathrequired

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:

jobTitlestringbody

Job title.

jobDescriptionstringbody

Full description text.

paymentTypestringbody

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

pricePerHournumberbody

Hourly rate in USD (for PAY_PER_HOUR).

pricePerLabelnumberbody

Per-label rate in USD (for PAY_PER_LABEL).

fixedPricenumberbody

Total fixed price in USD (for FIXED_PRICE).

experienceLevelstringbody

EXPERT, ENTRY_LEVEL, INTERMEDIATE, or ANY_EXPERIENCE_LEVEL.

dataVolumeUnitstringbody

HOURS_OF_RECORDING_AUDIO_VIDEO, NUMBER_OF_FILES, NUMBER_OF_WORDS, or UNKNOWN_NOT_SPECIFIED.

languagesstring[]body

Required languages.

countriesstring[]body

Allowed countries.

labelTypesstring[]body

Label/annotation types.

headcountnumberbody

Number of AI trainers to hire.

dataVolumenumberbody

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

okboolean

true on success.

jobIdstring

The draft job ID.

statusstring

Still DRAFT.

draftUrlstring

In-app URL of the draft editor.

validationobject

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

Request examples

curlCLIMCP: opentrain_update_job_draft_fields

curl

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
  }'

CLI

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

MCP: opentrain_update_job_draft_fields

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

Response examples

200400 (invalid payload)

200

{
  "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": []
  }
}

400 (invalid payload)

{
  "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'"
      ]
    }
  }
}