Create Job Draft

curl -sS -X POST https://app.opentrain.ai/api/public/v1/job-drafts \
  -H "Authorization: Bearer $OT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rawJobDescription": "We need 5 fluent Spanish speakers to label sentiment in ~20,000 social media posts. Pay per label. Annotators should have prior text-classification experience.",
    "idempotencyKey": "sentiment-es-2026-001"
  }'

opentrain jobs draft create \
  --description "We need 5 fluent Spanish speakers to label sentiment in ~20,000 social media posts. Pay per label." \
  --idempotency-key sentiment-es-2026-001 --json

{
  "jobDescription": "We need 5 fluent Spanish speakers to label sentiment in ~20,000 social media posts. Pay per label.",
  "idempotencyKey": "sentiment-es-2026-001"
}

{
  "ok": true,
  "jobId": "<JOB_ID>",
  "status": "DRAFT",
  "draftUrl": "https://app.opentrain.ai/job-post?jobId=<JOB_ID>",
  "reviewUrl": "https://app.opentrain.ai/job-post?jobId=<JOB_ID>",
  "validation": {
    "publishReady": false,
    "issueCount": 0,
    "missingFieldCount": 2,
    "missingFields": [],
    "issues": []
  },
  "missingFields": [
    {
      "field": "experienceLevel",
      "label": "Experience level",
      "message": "Experience level is required before publishing.",
      "code": "missing_required_field",
      "prompt": "ask: What experience level should AI trainers have? (EXPERT, ENTRY_LEVEL, INTERMEDIATE, ANY_EXPERIENCE_LEVEL)",
      "type": "enum",
      "enumValues": ["EXPERT", "ENTRY_LEVEL", "INTERMEDIATE", "ANY_EXPERIENCE_LEVEL"],
      "updateKeys": ["experienceLevel"],
      "example": "INTERMEDIATE",
      "hint": "Pick the minimum level the work realistically needs."
    },
    {
      "field": "pricePerLabel",
      "label": "Price per label",
      "message": "A pay rate is required before publishing.",
      "code": "missing_required_field",
      "prompt": "ask: How much will you pay per label (USD)?",
      "type": "number",
      "enumValues": null,
      "updateKeys": ["pricePerLabel"],
      "example": "0.05",
      "hint": null
    }
  ],
  "normalizedFields": {
    "jobTitle": "Spanish Sentiment Labeling — Social Media Posts",
    "paymentType": "PAY_PER_LABEL",
    "languages": ["Spanish"],
    "headcount": 5,
    "dataVolume": 20000,
    "dataVolumeUnit": "NUMBER_OF_FILES"
  },
  "warnings": [],
  "unmappedFields": [],
  "lowConfidenceFields": [
    { "path": "dataVolumeUnit", "reason": "Inferred NUMBER_OF_FILES from \"posts\"." }
  ],
  "import": {
    "format": "text",
    "externalId": null,
    "idempotencyKey": "sentiment-es-2026-001",
    "rawSourcePreserved": true,
    "autoPublished": false
  },
  "parser": {
    "source": "llm",
    "warnings": [],
    "parsedFields": 6
  }
}

{
  "error": "Unsupported job import format",
  "code": "BAD_REQUEST",
  "requestId": "<REQUEST_ID>",
  "details": {
    "supportedFormats": [
      "text",
      "opentrain_canonical",
      "schema_org_job_posting",
      "indeed_xml",
      "hr_xml"
    ]
  }
}

POST

api

public

job-drafts

curl -sS -X POST https://app.opentrain.ai/api/public/v1/job-drafts \
  -H "Authorization: Bearer $OT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rawJobDescription": "We need 5 fluent Spanish speakers to label sentiment in ~20,000 social media posts. Pay per label. Annotators should have prior text-classification experience.",
    "idempotencyKey": "sentiment-es-2026-001"
  }'

opentrain jobs draft create \
  --description "We need 5 fluent Spanish speakers to label sentiment in ~20,000 social media posts. Pay per label." \
  --idempotency-key sentiment-es-2026-001 --json

{
  "jobDescription": "We need 5 fluent Spanish speakers to label sentiment in ~20,000 social media posts. Pay per label.",
  "idempotencyKey": "sentiment-es-2026-001"
}

{
  "ok": true,
  "jobId": "<JOB_ID>",
  "status": "DRAFT",
  "draftUrl": "https://app.opentrain.ai/job-post?jobId=<JOB_ID>",
  "reviewUrl": "https://app.opentrain.ai/job-post?jobId=<JOB_ID>",
  "validation": {
    "publishReady": false,
    "issueCount": 0,
    "missingFieldCount": 2,
    "missingFields": [],
    "issues": []
  },
  "missingFields": [
    {
      "field": "experienceLevel",
      "label": "Experience level",
      "message": "Experience level is required before publishing.",
      "code": "missing_required_field",
      "prompt": "ask: What experience level should AI trainers have? (EXPERT, ENTRY_LEVEL, INTERMEDIATE, ANY_EXPERIENCE_LEVEL)",
      "type": "enum",
      "enumValues": ["EXPERT", "ENTRY_LEVEL", "INTERMEDIATE", "ANY_EXPERIENCE_LEVEL"],
      "updateKeys": ["experienceLevel"],
      "example": "INTERMEDIATE",
      "hint": "Pick the minimum level the work realistically needs."
    },
    {
      "field": "pricePerLabel",
      "label": "Price per label",
      "message": "A pay rate is required before publishing.",
      "code": "missing_required_field",
      "prompt": "ask: How much will you pay per label (USD)?",
      "type": "number",
      "enumValues": null,
      "updateKeys": ["pricePerLabel"],
      "example": "0.05",
      "hint": null
    }
  ],
  "normalizedFields": {
    "jobTitle": "Spanish Sentiment Labeling — Social Media Posts",
    "paymentType": "PAY_PER_LABEL",
    "languages": ["Spanish"],
    "headcount": 5,
    "dataVolume": 20000,
    "dataVolumeUnit": "NUMBER_OF_FILES"
  },
  "warnings": [],
  "unmappedFields": [],
  "lowConfidenceFields": [
    { "path": "dataVolumeUnit", "reason": "Inferred NUMBER_OF_FILES from \"posts\"." }
  ],
  "import": {
    "format": "text",
    "externalId": null,
    "idempotencyKey": "sentiment-es-2026-001",
    "rawSourcePreserved": true,
    "autoPublished": false
  },
  "parser": {
    "source": "llm",
    "warnings": [],
    "parsedFields": 6
  }
}

{
  "error": "Unsupported job import format",
  "code": "BAD_REQUEST",
  "requestId": "<REQUEST_ID>",
  "details": {
    "supportedFormats": [
      "text",
      "opentrain_canonical",
      "schema_org_job_posting",
      "indeed_xml",
      "hr_xml"
    ]
  }
}

Creates an unpublished job draft. The description-first workflow: send a plain-text job description, OpenTrain parses it into structured fields server-side, and the response tells you exactly what is still missing — each missing field carries a ready-to-ask prompt, its type, allowed enumValues, and the updateKeys to patch via PATCH /job-drafts/{jobId}. Loop until validation.publishReady is true, then publish. Structured imports (schema.org JSON-LD, Indeed-style XML, HR-XML, or OpenTrain’s canonical job object) are also accepted. See the posting guide for the full loop. Requirements: jobs:write scope + the public_api_job_drafting feature (check capabilities).

Request

Send one of the body shapes below. All are JSON objects.

string

Plain-text job description or project brief (max 60,000 characters). The simplest and recommended input — OpenTrain parses it into structured fields. Equivalent shorthand for source: {type: "text", text: ...}.

object

Structured import source.

Show source fields

string

Import format: text, opentrain_canonical, schema_org_job_posting, indeed_xml, or hr_xml. Unsupported values return 400 with details.supportedFormats.

string

The text or serialized payload for the chosen format.

string

Source-system identifier for audit (max 256 characters).

string

Reuse the same key on retries to avoid duplicate drafts (max 256 characters).

string

Top-level alternative to source.type — same supported values. Pair with job (canonical), jsonLd (schema.org), or xml (feeds).

object

OpenTrain canonical job object when format is opentrain_canonical — keys like title, description, paymentType, rateAmount, languages, countries, labelTypes, tools, experienceLevel.

string

Top-level equivalent of source.externalId.

string

Top-level equivalent of source.idempotencyKey.

Response

boolean

true on success.

string

The new draft’s job ID — use it for every subsequent PATCH and the publish call.

string

Always DRAFT (this endpoint never auto-publishes).

string

In-app URL of the draft editor.

string

In-app URL where a human can review the draft.

object

Publish-readiness summary.

Show validation fields

boolean

true when the draft can be published as-is.

number

Number of blocking issues.

number

Number of required fields still missing.

object[]

Same entries as the top-level missingFields.

object[]

Non-field-specific validation issues.

object[]

The gap-filling work list. Relay each prompt to your human, then patch the answer.

Show missingFields entry

string

Internal field identifier.

string

Human-readable field name.

string

Why the field is required.

string

Machine-readable issue code.

string

A ready-to-ask question (e.g. "ask: What experience level should AI trainers have?").

string

Expected answer type — string, number, enum, string[], etc.

string[] | null

Allowed values when type is enum. Patch with one of these exact values.

string[]

The key(s) to set in the PATCH body (e.g. ["paymentType", "pricePerHour"]).

string | null

Example value.

string | null

Extra guidance for answering.

object

The structured fields OpenTrain extracted from your input.

string[]

Non-blocking warnings.

object[]

Input keys that could not be mapped — {path, reason, valuePreview}.

object[]

Parsed fields worth double-checking with your human — {path, reason}.

object

Audit echo: {format, externalId, idempotencyKey, rawSourcePreserved, autoPublished: false}.

object

Parser metadata: {source, warnings, parsedFields}.

Errors

Status	`code`	Meaning
`400`	`BAD_REQUEST`	Empty body, invalid JSON, unsupported format (`details.supportedFormats`), or description over 60,000 characters
`401`	`UNAUTHORIZED`	Missing or invalid token
`403`	`FORBIDDEN`	Missing `jobs:write` scope (`details.requiredScopes`) or `public_api_job_drafting` disabled (`details.featureKey`)

curl -sS -X POST https://app.opentrain.ai/api/public/v1/job-drafts \
  -H "Authorization: Bearer $OT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rawJobDescription": "We need 5 fluent Spanish speakers to label sentiment in ~20,000 social media posts. Pay per label. Annotators should have prior text-classification experience.",
    "idempotencyKey": "sentiment-es-2026-001"
  }'

opentrain jobs draft create \
  --description "We need 5 fluent Spanish speakers to label sentiment in ~20,000 social media posts. Pay per label." \
  --idempotency-key sentiment-es-2026-001 --json

{
  "jobDescription": "We need 5 fluent Spanish speakers to label sentiment in ~20,000 social media posts. Pay per label.",
  "idempotencyKey": "sentiment-es-2026-001"
}

{
  "ok": true,
  "jobId": "<JOB_ID>",
  "status": "DRAFT",
  "draftUrl": "https://app.opentrain.ai/job-post?jobId=<JOB_ID>",
  "reviewUrl": "https://app.opentrain.ai/job-post?jobId=<JOB_ID>",
  "validation": {
    "publishReady": false,
    "issueCount": 0,
    "missingFieldCount": 2,
    "missingFields": [],
    "issues": []
  },
  "missingFields": [
    {
      "field": "experienceLevel",
      "label": "Experience level",
      "message": "Experience level is required before publishing.",
      "code": "missing_required_field",
      "prompt": "ask: What experience level should AI trainers have? (EXPERT, ENTRY_LEVEL, INTERMEDIATE, ANY_EXPERIENCE_LEVEL)",
      "type": "enum",
      "enumValues": ["EXPERT", "ENTRY_LEVEL", "INTERMEDIATE", "ANY_EXPERIENCE_LEVEL"],
      "updateKeys": ["experienceLevel"],
      "example": "INTERMEDIATE",
      "hint": "Pick the minimum level the work realistically needs."
    },
    {
      "field": "pricePerLabel",
      "label": "Price per label",
      "message": "A pay rate is required before publishing.",
      "code": "missing_required_field",
      "prompt": "ask: How much will you pay per label (USD)?",
      "type": "number",
      "enumValues": null,
      "updateKeys": ["pricePerLabel"],
      "example": "0.05",
      "hint": null
    }
  ],
  "normalizedFields": {
    "jobTitle": "Spanish Sentiment Labeling — Social Media Posts",
    "paymentType": "PAY_PER_LABEL",
    "languages": ["Spanish"],
    "headcount": 5,
    "dataVolume": 20000,
    "dataVolumeUnit": "NUMBER_OF_FILES"
  },
  "warnings": [],
  "unmappedFields": [],
  "lowConfidenceFields": [
    { "path": "dataVolumeUnit", "reason": "Inferred NUMBER_OF_FILES from \"posts\"." }
  ],
  "import": {
    "format": "text",
    "externalId": null,
    "idempotencyKey": "sentiment-es-2026-001",
    "rawSourcePreserved": true,
    "autoPublished": false
  },
  "parser": {
    "source": "llm",
    "warnings": [],
    "parsedFields": 6
  }
}

{
  "error": "Unsupported job import format",
  "code": "BAD_REQUEST",
  "requestId": "<REQUEST_ID>",
  "details": {
    "supportedFormats": [
      "text",
      "opentrain_canonical",
      "schema_org_job_posting",
      "indeed_xml",
      "hr_xml"
    ]
  }
}

List Job Proposals

Update Job Draft

⌘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