Session Jobs

The job polling endpoint reads from the apiSessions table. A session record is the canonical async state holder for Steve's external workflows.

Polling endpoint

GET /api/v1/jobs/{sessionId}
Authorization: Bearer aok_<key>

Access is scoped to the owning API key. If a different key tries to poll the session, Steve returns 403.

Response shape

{
  "sessionId": "jx7ses789...",
  "status": "complete",
  "result": {
    "example": "opaque payload"
  },
  "webhookDeliveryStatus": "delivered"
}

Notes

result is null until processing finishes or fails.
webhookDeliveryStatus is null when no webhook URL was configured.
The live response does not currently include a pipeline type.

Status values

Status	Meaning
`pending`	Session exists but has not been submitted
`submitted`	Processing has been queued or is in progress
`complete`	Processing finished and a result payload was stored
`failed`	Processing failed
`expired`	The session aged out before submit

Expiration model

Sessions are created with a 30-minute TTL. Expiration is not enforced inline by the polling endpoint; it is finalized by an hourly cron job that marks stale pending sessions as expired.

That means expiry is operationally eventual rather than exact to the millisecond. A stale unsubmitted session may still read as pending until the cron sweep runs.

Webhook delivery status values

Value	Meaning
`null`	No webhook was configured
`pending`	Delivery is queued or retrying
`delivered`	A webhook target returned `2xx`
`failed`	Delivery exhausted its retry budget

Practical guidance

Poll at a moderate cadence such as every 5 to 10 seconds.
Stop polling on complete, failed, or expired.
Prefer webhook delivery for low-latency integrations, with polling as a fallback or recovery path.