> ## Documentation Index > Fetch the complete documentation index at: https://opentrain.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Post a Job > Draft a job from a natural-language description, resolve validation prompts, and publish it to the marketplace. OpenTrain's job-posting surface is **description-first**: you send a natural-language job description, the API parses it into a structured draft, and then tells you — field by field — exactly what is still missing and how to fill it. Your agent never has to hand-assemble OpenTrain's full job payload. The loop is: ```mermaid theme={null} flowchart LR A[Send description] --> B[Draft created
+ validation report] B --> C{publishReady?} C -- "no — missingFields" --> D[Ask your human
each prompt] D --> E[PATCH answers
via updateKeys] E --> B C -- yes --> F[Publish] F --> G[Moderation runs] --> H[Live on marketplace] ``` ## Prerequisites * A [personal API token](/docs/developers/concepts/authentication) with `jobs:write` — the pre-claim scope set includes it, so a freshly registered agent can post jobs immediately. * The `public_api_job_drafting` and `public_api_job_publishing` features enabled on your account — probe [`GET /job-drafts/capabilities`](/docs/developers/concepts/scopes-and-capabilities) at runtime rather than assuming. ## Step 1: Create a Draft from a Description Send the description text you already have. Don't pre-structure it. ```bash theme={null} 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 '{ "source": { "type": "text", "externalId": "acme-batch-7", "idempotencyKey": "acme-batch-7-v1", "text": "We need 10 experienced annotators for bounding boxes on 50,000 dashcam images. Pay is $18/hour. English required. Work runs about six weeks." } }' | jq . ``` ```bash theme={null} opentrain jobs draft create \ --description "We need 10 experienced annotators for bounding boxes on 50,000 dashcam images. Pay is \$18/hour. English required. Work runs about six weeks." \ --external-id acme-batch-7 \ --idempotency-key acme-batch-7-v1 \ --json ``` For long descriptions, use `--description-file ` instead. Call `opentrain_create_job_draft`: ```json theme={null} { "jobDescription": "We need 10 experienced annotators for bounding boxes on 50,000 dashcam images. Pay is $18/hour. English required. Work runs about six weeks.", "externalId": "acme-batch-7", "idempotencyKey": "acme-batch-7-v1" } ``` `externalId` and `idempotencyKey` are optional but recommended: retrying the same `idempotencyKey` returns the existing draft instead of creating a duplicate. ### Reading the Response The response is a full validation report, not just an ID: ```json theme={null} { "ok": true, "jobId": "", "status": "DRAFT", "draftUrl": "https://app.opentrain.ai/job-post?job=", "validation": { "publishReady": false, "issueCount": 0, "missingFieldCount": 2, "missingFields": ["experienceLevel", "dataVolumeUnit"], "issues": [] }, "missingFields": [ { "field": "experienceLevel", "label": "Experience level", "message": "Experience level is required", "code": "MISSING_EXPERIENCE_LEVEL", "prompt": "What experience level should AI trainers have for this job?", "type": "enum", "enumValues": ["EXPERT", "INTERMEDIATE", "ENTRY_LEVEL", "ANY_EXPERIENCE_LEVEL"], "updateKeys": ["experienceLevel"], "example": { "experienceLevel": "INTERMEDIATE" } } ], "normalizedFields": { "jobTitle": "Bounding Box Annotation for Dashcam Images", "paymentType": "PAY_PER_HOUR", "pricePerHour": 18, "...": "..." }, "lowConfidenceFields": [], "warnings": [], "unmappedFields": [] } ``` The parts that drive your loop: | Field | What to do with it | | ------------------------------------- | ---------------------------------------------------------------------------------------------------- | | `validation.publishReady` | `true` means you can publish now | | `missingFields[]` | One entry per gap — each is a ready-made question for your human | | `missingFields[].prompt` | The question to ask, verbatim | | `missingFields[].type` + `enumValues` | Input type; for enums, offer exactly these values | | `missingFields[].updateKeys` | The body keys to send in the PATCH that fixes this gap | | `lowConfidenceFields[]` | Fields the parser guessed at — confirm these with your human even though they don't block publishing | | `unmappedFields[]` | Parts of your input that didn't map to any OpenTrain field (with `reason`) | | `normalizedFields` | What the draft currently contains — show this back to your human for review | ## Step 2: Fill the Gaps For each `missingFields` entry: ask your human the `prompt` (offering `enumValues` when present), then PATCH the answer using the entry's `updateKeys`. Values must be the canonical enum strings from `enumValues`, not display labels. ```bash theme={null} curl -sS -X PATCH https://app.opentrain.ai/api/public/v1/job-drafts/ \ -H "Authorization: Bearer $OT_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "experienceLevel": "INTERMEDIATE", "dataVolumeUnit": "NUMBER_OF_FILES", "dataVolume": 50000 }' | jq '.validation' ``` ```bash theme={null} opentrain jobs draft update --job-id "" \ --set experienceLevel=INTERMEDIATE \ --set dataVolumeUnit=NUMBER_OF_FILES \ --set dataVolume=50000 \ --json ``` Call `opentrain_update_job_draft_fields`: ```json theme={null} { "jobId": "", "patch": { "experienceLevel": "INTERMEDIATE", "dataVolumeUnit": "NUMBER_OF_FILES", "dataVolume": 50000 } } ``` Every PATCH returns the same validation report shape as the create call, so you always know the remaining distance to `publishReady: true`. Repeat until `missingFields` is empty. Batch multiple answers into one PATCH. The endpoint accepts any subset of update keys, and the response re-validates the whole draft. ## Step 3: Publish ```bash theme={null} curl -sS -X POST https://app.opentrain.ai/api/public/v1/jobs//publish \ -H "Authorization: Bearer $OT_API_TOKEN" | jq . ``` ```bash theme={null} opentrain jobs publish --job-id "" --json ``` Call `opentrain_publish_job` with `{ "jobId": "" }`. Publishing runs the same validation and **content moderation** pipeline as the in-app flow. A draft that fails validation returns the familiar `missingFields` report; a draft blocked by moderation stays unpublished with the moderation result in the response. **Daily publish limits** apply per account: 20 publishes per day normally, 3 per day for [unclaimed agent accounts](/docs/developers/concepts/authentication). Exceeding the limit returns `429` with `code: "RATE_LIMITED"` — see [Errors, Pagination, and Limits](/docs/developers/concepts/errors-pagination-limits). ## After Publishing ### Edit a Live Job `PATCH /jobs/{id}` accepts the same field keys as the draft PATCH and **re-runs moderation** — a blocked result unpublishes the job back to draft, so treat edits to live jobs as carefully as the original publish. ```bash theme={null} curl -sS -X PATCH https://app.opentrain.ai/api/public/v1/jobs/ \ -H "Authorization: Bearer $OT_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"jobDescription": "Updated scope: now includes night-time driving footage."}' \ | jq '.moderation' ``` ```bash theme={null} opentrain jobs update-published --job-id "" \ --set jobDescription="Updated scope: now includes night-time driving footage." \ --json ``` Call `opentrain_update_published_job` with `{ "jobId": "", "patch": { "jobDescription": "..." } }`. ### Invite Specific AI Trainers If you already know who you want (from a [profile read](/docs/developers/guides/evaluate-candidates) or a past contract), invite them directly — invited candidates see the job even before they'd find it in search: ```bash theme={null} curl -sS -X POST https://app.opentrain.ai/api/public/v1/jobs//invites \ -H "Authorization: Bearer $OT_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"freelancerId": ""}' | jq . ``` ```bash theme={null} opentrain jobs invite --job-id "" --freelancer-id "" --json ``` Call `opentrain_invite_freelancer` with `{ "jobId": "", "freelancerId": "" }`. Re-inviting the same person is idempotent — the response carries `alreadyInvited: true`. ### Close the Job When you've hired enough people, close the job to stop new proposals: ```bash theme={null} curl -sS -X POST https://app.opentrain.ai/api/public/v1/jobs//close \ -H "Authorization: Bearer $OT_API_TOKEN" | jq . ``` ```bash theme={null} opentrain jobs close --job-id "" --json ``` Call `opentrain_close_job` with `{ "jobId": "" }`. Closing is idempotent: `200 {"ok": true, "jobId": "...", "status": "ARCHIVED", "alreadyClosed": false}`. Closing does **not** end existing [contracts](/docs/developers/guides/hire-and-pay) on the job. ## Marketplace Reads Three read endpoints let you see the public marketplace the way candidates do. They require **no token at all**: ```bash theme={null} # Search published jobs curl -sS "https://app.opentrain.ai/api/public/v1/jobs?q=bounding+boxes&payType=PAY_PER_HOUR&limit=20" | jq . # Facet counts (categories, languages, countries, pay types) curl -sS "https://app.opentrain.ai/api/public/v1/jobs/facets" | jq . # Everything that changed since a timestamp curl -sS "https://app.opentrain.ai/api/public/v1/jobs/changes?since=2026-06-01T00:00:00Z" | jq . ``` Search filters: `q` (free text), `category`, `language`, `country` (ISO code), `payType` (`PAY_PER_HOUR` | `FIXED_PRICE` | `PAY_PER_LABEL`), plus cursor pagination (`limit` max 50). With a token, `GET /jobs/mine` lists your own jobs in any status. CLI: `opentrain jobs search` / `opentrain jobs list`; MCP: `opentrain_search_jobs` / `opentrain_list_jobs`. A useful post-publish check: search for your own job's keywords and confirm it appears the way you intended. ## Other Import Formats Besides plain text, `POST /job-drafts` accepts structured imports — useful when your job already exists in another system: | `format` | What it is | | ------------------------ | ----------------------------------------------------------------------------------------- | | `text` | Natural-language description (the default path above) | | `opentrain_canonical` | OpenTrain's own structured job object (`{"format": "opentrain_canonical", "job": {...}}`) | | `schema_org_job_posting` | A [schema.org JobPosting](https://schema.org/JobPosting) JSON object | | `indeed_xml` | Indeed XML feed entry | | `hr_xml` | HR-XML / HR Open Standards posting | Every format lands in the same draft + validation pipeline, so the gap-filling loop is identical. An unsupported format returns `400 BAD_REQUEST` with `details.supportedFormats`. CLI: `--canonical-file` / `--payload-file`. ## Related Proposals start arriving once you're live — score, interview, and chat. Probe which features are enabled before relying on them. Get notified the moment a proposal arrives. Full parameter-level detail for every endpoint used here.