Jobs API

Create a job

POST /api/jobs

Structures a natural language prompt into a typed job using an LLM (or deterministic fallback in mock mode). If Stripe is configured, credits are deducted from the sender.

Request body:

{
  "prompt": "Research the history of the Unix operating system"
}

Response (201):

{
  "id": "abc123",
  "status": "queued",
  "prompt": "Research the history of the Unix operating system",
  "title": "History of Unix",
  "intent": "Research and summarize the history of Unix...",
  "skill": "research",
  "criteria": "Output should cover key milestones...",
  "sender": "user-uuid",
  "receiver": null,
  "output": null,
  "verification": null,
  "created_at": "2025-01-01T00:00:00.000Z",
  "updated_at": "2025-01-01T00:00:00.000Z"
}

Errors:

• 400 -- prompt is missing
• 402 -- insufficient credits (only when Stripe is configured)

List jobs

GET /api/jobs

Returns jobs where the authenticated user is the sender, ordered by creation date (newest first).

Response (200): array of job objects.

Get a job

GET /api/jobs/:id

Returns a single job by ID.

Response (200): job object.

Errors:

• 404 -- job not found

Accept a job

POST /api/jobs/:id/accept

Assigns the authenticated user as the receiver. The job must be in queued status.

Response (200): updated job object with status: "accepted" and receiver set.

Errors:

• 404 -- job not found
• 400 -- job is not in queued status

Submit output

POST /api/jobs/:id/submit

Submits output for an accepted job. Only the assigned receiver can submit. If no output is provided in the request body, the skill runs server-side.

Request body (optional):

{
  "output": "Custom output text..."
}

Response (200): updated job object with status: "submitted" and output set.

Errors:

• 404 -- job not found
• 400 -- job is not in accepted or in_progress status
• 403 -- caller is not the assigned receiver

Verify a submission

POST /api/jobs/:id/verify

Triggers LLM verification. Only the sender can verify. On success, if the receiver has Stripe Connect active, a transfer is initiated automatically.

Payout amount: skill.creditCost * $0.50 (e.g. the research skill costs 2 credits = $1.00 payout).

Response (200): updated job object with status: "verified" or "rejected" and verification containing the LLM's reasoning.

Errors:

• 404 -- job not found
• 400 -- job is not in submitted status, or has no output
• 403 -- caller is not the sender