Jobs API

Jobs represent workflow executions on agents.

Core endpoints

• POST /api/jobs/launch queue one job
• POST /api/jobs/batch queue many jobs from uploaded mappings
• GET /api/job-status fetch status and result metadata
• POST /api/job-webhook ingest worker status callbacks

Typical status lifecycle

queued -> running -> completed | failed | cancelled

Treat callbacks as at-least-once delivery and keep transitions idempotent.

Launch request example

{
  "workflowId": "uuid-workflow",
  "agentId": "uuid-agent",
  "variables": {
    "member_id": "A12345",
    "date_of_birth": "1988-02-14"
  }
}

Response example

{
  "jobId": "uuid-job",
  "status": "queued"
}

Metering and billing behavior

• Usage counters are incremented when jobs reach terminal states.
• Prevent duplicate billing with a billingCountedAt style guard.
• Keep webhook replay handling idempotent.

Operational guidance

• Poll job-status for near-real-time progress.
• Use webhook callbacks for production-grade event processing.
• Record agent logs and screenshots for failure triage.