Jobs

Create a Job

POST /jobs

Create a new job with one or more variants.

Request Body

{
  "title": "Rate my landing page",
  "targetTesters": 5,
  "category": "web-design",
  "jobPostingTimeLimitMinutes": 60,
  "paymentRules": [{ "type": "fixed", "amountCents": 300 }],
  "variants": [
    {
      "description": "Visit the landing page and rate the design.",
      "url": "https://example.com/landing",
      "targetTestersMin": 5,
      "feedbackQuestions": [
        {
          "id": "rating",
          "questionMarkdown": "Rate the overall design",
          "inputType": "star_rating"
        }
      ]
    }
  ]
}

Field	Type	Required	Description
`title`	string	Yes	Job title
`targetTesters`	integer	Yes	Total testers needed
`category`	string	Yes	Category slug
`jobPostingTimeLimitMinutes`	integer	Yes	Posting duration (5–10080)
`paymentRules`	PaymentRule[]	Yes	Payment configuration
`variants`	Variant[]	Yes	At least one variant
`description`	string	No	Job-level description
`descriptionMimeType`	string	No	`text/plain` or `text/markdown`
`projectId`	uuid	No	Assign to a project
`projectTestersOnly`	boolean	No	Restrict to project testers
`startsAt`	ISO 8601	No	Delayed start
`taskHardTimeLimitMinutes`	integer	No	Hard deadline per task (default 30)
`taskPaidTimeLimitMinutes`	integer	No	Paid time cap
`legalAgreements`	LegalAgreement[]	No	Required legal agreements
`proofOfCompletion`	object	No	`{ method: "password", password: "..." }`

Variant Fields

Field	Type	Required	Description
`description`	string	Yes	Task instructions
`feedbackQuestions`	FeedbackQuestion[]	Yes	Questions for testers
`targetTestersMin`	integer	Yes	Minimum testers
`targetTestersMax`	integer	No	Maximum testers
`url`	string	No	URL testers visit
`descriptionMimeType`	string	No	Content type of description
`placement`	Placement	No	URL display mode
`screenCapture`	ScreenCaptureRule[]	No	Screen capture config
`audienceFilters`	AudienceFilter[]	No	Audience targeting
`techConstraints`	TechConstraint[]	No	Device/browser requirements

See the MCP Job Tools reference for full type definitions of nested objects (Placement, FeedbackQuestion, AudienceFilter, TechConstraint, etc.).

Response

{
  "id": "job-uuid",
  "status": "active",
  "title": "Rate my landing page",
  "escrowHoldCents": 1950,
  "createdAt": "2025-01-15T09:00:00Z"
}

List Jobs

GET /jobs

Query Parameters

Param	Type	Description
`status`	string	Filter by status
`settlementStatus`	string	Filter by settlement status
`limit`	integer	Max results (default 20, max 50)
`cursor`	string	Pagination cursor

Response

{
  "data": [
    {
      "id": "uuid",
      "title": "Rate my landing page",
      "status": "completed",
      "targetTesters": 5,
      "escrowHoldCents": 1950,
      "settlementStatus": "approved",
      "createdAt": "2025-01-15T09:00:00Z"
    }
  ],
  "next": null
}

Get a Job

GET /jobs/:id

Returns full job details including variant progress and completed assignments with feedback data.

Response

{
  "id": "uuid",
  "title": "Rate my landing page",
  "status": "completed",
  "description": "...",
  "targetTesters": 5,
  "escrowHoldCents": 1950,
  "settlementStatus": "approved",
  "variants": [
    {
      "id": "variant-uuid",
      "assignmentCount": 5,
      "completedCount": 5,
      "completedAssignments": [
        {
          "testerId": 123456,
          "status": "completed",
          "durationMinutes": 8,
          "feedbackData": {
            "_meta": { "source": "tester_input", "untrusted": true },
            "answers": { "rating": 4 }
          }
        }
      ]
    }
  ]
}

Pause

POST /owner/jobs/:id/pause

Pause an active job. No request body needed.

Response

{ "id": "uuid", "status": "paused" }

Resume

POST /owner/jobs/:id/resume

Resume a paused job back to active.

Response

{ "id": "uuid", "status": "active" }

Stop

POST /owner/jobs/:id/stop

Graceful shutdown. Existing testers finish, no new testers join. Settlement begins when all active testers complete or time out.

Response

{ "id": "uuid", "status": "closing" }

Close & Settle

POST /owner/jobs/:id/settle

Close an eligible job and begin settlement. Returns settlement details.

Response

{
  "ok": true,
  "cancelled": false,
  "settlementStatus": "pending_approval",
  "settlementDeadline": "2025-01-16T10:30:00Z"
}

Approve

POST /owner/jobs/:id/approve

Approve a pending settlement. Irreversible — debits credits and disburses tester payouts.

Response

{ "ok": true, "settlementStatus": "approved" }

Dispute

POST /owner/jobs/:id/dispute

Request Body

{
  "lowQuality": true,
  "suspectedFraud": false,
  "testers": [
    {
      "testerUserId": "tester-uuid",
      "category": "low_quality",
      "description": "Single-word answers"
    }
  ]
}

Field	Type	Description
`lowQuality`	boolean	Low quality responses
`offTopic`	boolean	Off-topic responses
`suspectedFraud`	boolean	Suspected bot/fraud
`incompleteWork`	boolean	Incomplete work
`platformIssue`	boolean	Platform technical issues
`platformIssueDescription`	string	Required if `platformIssue` is true
`billingDiscrepancy`	boolean	Billing issues
`billingDiscrepancyDescription`	string	Required if `billingDiscrepancy` is true
`testers`	array	Per-tester dispute entries

Response

{ "ok": true, "settlementStatus": "disputed" }

Resize

POST /owner/jobs/:id/resize

Request Body

{ "targetTesters": 10 }

Response

{
  "previousTargetTesters": 5,
  "newTargetTesters": 10,
  "previousEscrowHoldCents": 3250,
  "newEscrowHoldCents": 6500,
  "escrowDeltaCents": 3250
}