Standalone Shelf Watcher

Shelf Watcher runs independently of document and audio submissions. Your company needs the Shelf Watcher module and access to an active shelf profile. It does not need the Submissions module or a workflow grant.

A profile versions the recognition settings, photo limits, capture quality gate and review policy. Every capture pins an immutable profile version. Updating a profile affects new captures; retrying or reprocessing an existing capture keeps its original configuration.

Capture and analyze

Send your company-scoped API key in Authorization: Bearer aok_<key> on every Steve request.

1. Call GET /api/v1/shelf/profiles. Choose a profile and keep its versionId and upload limits.
2. Create a capture with POST /api/v1/shelf/sessions:

{
  "profileVersionId": "<versionId>",
  "clientCaptureId": "store-42-visit-2026-10-03",
  "storeName": "Store 42",
  "webhookUrl": "https://your-service.example/shelf-events"
}

The response contains sessionId. Use a stable clientCaptureId: if the response is lost, repeat the request to recover the same session. A different profile version under that identifier is a conflict. storeId optionally links an existing company store; webhookUrl is optional.

3. Reserve each photo with POST /api/v1/shelf/sessions/{sessionId}/uploads:

{ "photoIndex": 0, "mimeType": "image/jpeg" }

4. PUT the photo bytes to the returned uploadUrl, with the requested Content-Type. That URL expires after 15 minutes. Then register it with POST /api/v1/shelf/sessions/{sessionId}/photos:

{
  "photoIndex": 0,
  "mimeType": "image/jpeg",
  "r2Url": "<exact returned r2Url>",
  "fileSize": 1250000
}

Photo indices start at zero. The URL must have been reserved for this session and slot. Repeating the same registration is safe; replacing an occupied slot is a conflict. Upload photos within the profile's count and size limits. Optional sectionIndex and sectionPhotoIndex group photos captured across shelf sections.

5. Call POST /api/v1/shelf/sessions/{sessionId}/analyze with {}. It returns 202 and runId. Retrying while queued or processing returns the same run.
6. Poll GET /api/v1/shelf/sessions/{sessionId} or receive a webhook.

Outcomes and review

The session progresses from created through queued and processing to completed, blocked, failed or cancelled. Capture quality and moderation run before paid shelf recognition. A blocked capture includes an error explaining what needs attention.

A completed analysis publishes its result immediately, including facings by SKU and brand, detection totals and optional insights. Review is a separate state: not_required, pending or confirmed. Staff review and corrections happen in the shelf review screen. A pending review does not hide the analysis result or enter the regular submission approval pipeline.

Use POST /api/v1/shelf/sessions/{sessionId}/reprocess with {} after a terminal outcome to start another run. The last successful result remains available while it runs, and resultRunId identifies the run that produced that result. activeRunId identifies the latest analysis attempt.

Use POST /api/v1/shelf/sessions/{sessionId}/cancel with {} to cancel an open or active capture. A completed or otherwise terminal outcome stays intact. Workers finishing after cancellation cannot publish a result.

Webhooks

Provide an HTTPS webhook URL at capture creation to receive:

• shelf.analysis.completed
• shelf.analysis.blocked
• shelf.analysis.failed
• shelf.analysis.cancelled
• shelf.review.confirmed

Each event contains id, type, occurredAt and a session snapshot with the session/run IDs, status, review state and last successful result. The snapshot and event ID stay unchanged across delivery retries. Deduplicate by event ID and acknowledge with a 2xx response.

Shelf events use the same HMAC signing protocol as the existing API, with X-Webhook-Signature, X-Webhook-Event, X-Webhook-Id and X-Webhook-Timestamp headers. Delivery makes up to four attempts, with retries after 30 seconds, 5 minutes and 30 minutes. Every analysis event has its own retry budget.

API change

Shelf Watcher no longer accepts workflow IDs or creates submission IDs. Use shelf profile version IDs and shelf session/run IDs, the /api/v1/shelf endpoints and the shelf review APIs. Document and audio submission endpoints continue to serve their existing purposes. There is no migration or compatibility adapter for the former shelf submission flow.