Jobs APICopy Anchor Link

Async jobs support long-running procedure discovery and document digitization. Historical validation and report jobs remain readable.

Queued or retryable rows with a retired or unknown historical job type fail with an explicit non-retryable error. Stored metadata cannot select or revive the removed generic agent runner.

List JobsCopy Anchor Link

GET /api/v1/jobs

Query ParamsCopy Anchor Link

• limit (1-100, default 50)
• offset (default 0)
• status (pending, discovering, parsing, extracting, fetching, analyzing, validating, complete, failed)
• jobType (discovery, document-digitization, or historical read-only types site-control-requirements, site-control-compliance, deficiency-location, and report-generation)
• onlyCurrentKey (true to scope by current API key id)

Create JobCopy Anchor Link

POST /api/v1/jobs

Creatable job types are discovery and document-digitization. The legacy site-control-requirements, site-control-compliance, deficiency-location, and report-generation types return 410 JOB_TYPE_RETIRED on creation, while existing jobs remain available through GET.

BodyCopy Anchor Link

{
  "jobType": "discovery",
  "utilityName": "duke-energy",
  "state": "NC",
  "metadata": {
    "discoveryMode": "pda-only"
  },
  "webhookUrl": "https://partner.example/webhooks/gridwonk"
}

Document Digitization MetadataCopy Anchor Link

For applicant-document jobs, the organization API key must be authorized for the referenced document and the row must be organization-visible. Private or individually shared applicant documents are not eligible for organization-key job creation; use a user-scoped workflow instead. Procedure-document jobs must also provide the matching utilityName.

Salesforce-owned documents cannot be processed through this generic job endpoint, even when the organization can read the copy; creation returns 404 NOT_FOUND. There is no Salesforce job type to select here. Source capture and review belong to the separate default-disabled Salesforce connector, which remains disabled.

For PDA (Procedures Discovery Agent) discovery-only runs, create a discovery job with metadata.discoveryMode: "pda-only". The USE_WORKFLOW_PDA_DISCOVERY flag controls whether that mode is admitted. Once admitted, the job uses the PDA workflow and leaves requirements extraction out of the run; the flag does not select between cron and Workflow engines.

Packet intake Review loads reviewed deterministic requirements from ix_packet_requirements and does not depend on the retired legacy job types.

Get JobCopy Anchor Link

GET /api/v1/jobs/{jobId}

Returns current status, progress, counters, metadata, and result payload (if terminal).

Terminal status is compare-and-set from an active status. If another actor already completed, failed, cancelled, or generation-superseded the row, a stale runner cannot overwrite that result or send a terminal webhook it did not earn. Generation-superseded jobs intentionally emit no customer terminal webhook.

Cancel JobCopy Anchor Link

DELETE /api/v1/jobs/{jobId}

Cancels active jobs. Returns 409 if job is already terminal or cannot be canceled.

For packet-review jobs, cancellation settles the linked active review and blocks further packet results without deleting completed document findings. The key must match the job organization and the packet's review-authority organization; a utility-executed applicant self-check does not become utility-cancellable merely because its job ran in that utility's workspace. Use the authorized project action when the key cannot reach the exact review lane.

A successful response retains success and jobId and may add runtime and warning. Runtime outcomes distinguish a requested stop, an already-terminal runtime, unavailable identity, a failed stop or no stop attempted. Read the warning before retrying: an already-running provider request may finish even though its packet result can no longer publish. Cancellation is not a repair of the failure that caused a stuck run.

Stream Job UpdatesCopy Anchor Link

GET /api/v1/jobs/{jobId}/stream

Server-Sent Events stream.

Event TypesCopy Anchor Link

• job.update
• job.complete
• error
• timeout

Compatibility NoteCopy Anchor Link

The Jobs API contract remains stable across Workflow-backed execution:

• POST /api/v1/jobs and related endpoints still return the same jobId / polling flow
• Job state remains in discovery_jobs and streams through the same SSE channel
• Supported async job types route through Workflow-backed execution; external API behavior remains compatible

For workflow-owned rows, discovery_jobs.metadata may include:

• execution_engine
• workflow_run_id
• workflow_entry_mode
• workflow_stage

These fields are additive metadata and do not change response contracts.

Example Create + PollCopy Anchor Link

# Create
curl -X POST https://gridwonk.com/api/v1/jobs \
  -H "Authorization: Bearer $GRIDBOOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jobType":"discovery","utilityName":"duke-energy"}'

# Poll
curl https://gridwonk.com/api/v1/jobs/<jobId> \
  -H "Authorization: Bearer $GRIDBOOST_API_KEY"