SteveExternal API Overview
What integrators can build with Steve's live API-keyed HTTP surface.
Steve's external API supports document and audio workflows, submission review, and standalone Shelf Watcher captures.
At a high level, an integration can:
- Discover which workflows its company is allowed to use.
- Create a session and upload files directly to Cloudflare R2.
- Submit the session for asynchronous processing.
- Receive completion via webhook or poll the session job endpoint.
- Read the resulting submission, resolve fraud matches, and approve, reject, or cancel it.
Namespace
Every endpoint in this namespace requires:
Endpoint map
Workflows
| Endpoint | Purpose |
|---|---|
GET /api/v1/workflows | List workflows accessible to the authenticated company |
GET /api/v1/workflows/{slug} | Read the currently published workflow summary |
GET /api/v1/workflows/{slug}/versions/{version} | Read the immutable upload and output contract for one workflow version |
POST /api/v1/workflows/{slug}/sessions | Create an upload session and receive pre-signed R2 URLs |
POST /api/v1/workflows/{slug}/sessions/{sessionId}/submit | Queue a session for processing |
Shelf Watcher
Shelf captures use their own profiles, sessions, analysis runs and results. They can run with the Submissions module disabled. Follow the standalone Shelf Watcher guide.
| Endpoint | Purpose |
|---|---|
GET /api/v1/shelf/profiles | Discover granted profile versions and photo limits |
POST /api/v1/shelf/sessions | Create an independent capture |
POST /api/v1/shelf/sessions/{sessionId}/uploads | Reserve a photo upload |
POST /api/v1/shelf/sessions/{sessionId}/photos | Register the uploaded photo |
POST /api/v1/shelf/sessions/{sessionId}/analyze | Start analysis |
GET /api/v1/shelf/sessions/{sessionId} | Read status and last successful result |
POST /api/v1/shelf/sessions/{sessionId}/reprocess | Start another analysis run |
POST /api/v1/shelf/sessions/{sessionId}/cancel | Cancel open or active work |
Session utilities
| Endpoint | Purpose |
|---|---|
GET /api/v1/jobs/{sessionId} | Poll asynchronous session state and the current business outcome |
POST /api/v1/webhooks/test | Verify webhook reachability before enabling production deliveries |
GET /api/v1/companies | List active companies for setup or migration tooling |
Submission review
| Endpoint | Purpose |
|---|---|
GET /api/v1/submissions | List submissions visible to the authenticated company |
GET /api/v1/submissions/{submissionId} | Fetch full submission detail, files, fraud matches, and event history |
POST /api/v1/submissions/{submissionId}/approve | Approve a submission in review |
POST /api/v1/submissions/{submissionId}/reject | Reject a submission in review |
POST /api/v1/submissions/{submissionId}/cancel | Cancel a submission before it is approved or synced |
Approval returns 409 when verification checks did not pass; a reviewer must approve with a reason. This includes stale results and enabled checks that have not run, including fraud skips. A Steve reviewer must run checks or approve with an audited reason; the API does not accept an override reason.
Fraud
| Endpoint | Purpose |
|---|---|
GET /api/v1/submissions/{submissionId}/fraud-matches | Inspect duplicate or suspicious match candidates |
POST /api/v1/submissions/{submissionId}/fraud-matches/{matchId}/resolve | Resolve an individual fraud match |
Contract boundaries
- This is a server-to-server API. Do not embed Steve API keys in browsers or mobile apps.
- API keys are usually company-scoped, and a scoped key only sees workflows and submissions for its company. Legacy and platform-created keys may be unscoped; company-scoped endpoints reject them with
403 Forbidden. - Workflow outputs are versioned. Use the workflow version endpoint when you need a stable machine-readable contract.
- Workflow authoring, API key self-service, company management, and admin-only routes are not part of this external contract.
- The file upload step is direct-to-R2. Steve coordinates the session, not the file transfer itself.
- All body field names are camelCase. All body timestamps are ISO 8601 strings.
- Every non-2xx response uses RFC 9457
application/problem+json.
Recommended reading
Capture-quality reruns
Submission detail exposes the latest file-level captureQuality verdict and reasons, or null
when no measurement exists. To authorize one run after a capture-quality block, call
POST /api/v1/submissions/{submissionId}/process-anyway
with no body. 202 reports the current submission status and duplicate requests are idempotent.
The endpoint requires current workflow access and refuses delivery history or missing measurements.
It reopens a failed API job for polling the same session, with a new generation-specific webhook ID.
See submission review for errors and retry behavior.