Asset sessions and event image imports

The checked-in Go OpenAPI and handler tests define these routes, but a usable deployment also needs the studio-asset and event-image-import adapters, authorized API-key scopes, backing state stores, and deployment configuration. Do not treat source routes or CLI help as deployment evidence. The public batchrelay CLI source provides a Smart Crop V2 folder workflow and a raw request alternative. Public HTTPS source ingestion and durable image-import commit remain fail-closed until their server adapters are configured and deployed.

An asset session is studio-scoped and carries a declared purpose and destination. The current route contract does not promise one universal session implementation for every catalog, branding, event, and template use case. Permanent records should reference Batch Relay asset IDs, never a third-party URL.

create session -> upload or ingest -> finalize -> prepare import -> review -> commit

The current OpenAPI session routes are:

POST /v1/studios/{studio_id}/asset-sessions
GET  /v1/studios/{studio_id}/asset-sessions/{session_id}
PUT  /v1/studios/{studio_id}/asset-sessions/{session_id}/assets/{asset_id}
POST /v1/studios/{studio_id}/asset-sessions/{session_id}/finalize
POST /v1/studios/{studio_id}/asset-sessions/{session_id}/cancel

The current OpenAPI event-import routes are:

POST  /v1/studios/{studio_id}/events/{event_id}/image-imports
GET   /v1/studios/{studio_id}/events/{event_id}/image-imports/{import_id}
PATCH /v1/studios/{studio_id}/events/{event_id}/image-imports/{import_id}
POST  /v1/studios/{studio_id}/events/{event_id}/image-imports/{import_id}/commit
POST  /v1/studios/{studio_id}/events/{event_id}/image-imports/{import_id}/cancel

An import request references an asset_session_id, an expected_session_revision, and a manifest. A raw request may use either a staged or smart_crop_masters_preview manifest; the latter also carries the frozen smart_crop_manifest document. Nothing should bind to the event until the durable commit adapter rechecks the current state.

Resolution policy

Every requested output reports source pixels, output inches, effective PPI, grade, and a human message.

Grade	Effective PPI	Result
`ready`	300 or higher	Accept normally.
`warning`	150 to 299	Show the warning in review.
`blocked`	Below 150	Require an explicit override.

A below-minimum override requires both an acknowledgement and a non-empty reason. Batch Relay records the actor, time, policy version, affected output, effective PPI, and reason. It does not upscale the source or suppress the warning. Use a deployment that has the required adapters and scopes. The CLI’s Smart Crop V2 folder workflow creates the session, uploads declared masters, finalizes it, and prepares the import with one stable root idempotency key:

batchrelay events images prepare --event evt_example \
  --folder ./masters \
  --manifest ./Smart-Crop-Masters-Preview.json \
  --mapping-csv ./mapping.csv \
  --idempotency-key smart-crop-event-20260829

--mapping-csv is optional. The folder must contain the declared JPEG masters. The CLI rejects an incomplete or altered manifest before any request: it requires schema version batchrelay.smart-crops/v1, coordinate space oriented-source-pixels-top-left, a producer name/version, 1–500 declared JPEGs, and matching local bytes, SHA-256, dimensions, and safe filenames. It passes the frozen Smart Crop manifest through unchanged; it does not recalculate crop rectangles. For an already-created session or a non-folder caller, the raw primitive is still available:

batchrelay events images prepare --event evt_example --file image-import.json \
  --idempotency-key image-import-20260829
batchrelay events images review imp_example --event evt_example --file review.json
batchrelay events images commit imp_example --event evt_example \
  --file commit.json --idempotency-key image-commit-20260829

The asset and import lifecycle uses authoritative optimistic-concurrency revisions. The raw request bodies are:

// finalize.json
{ "expected_revision": 4 }

// image-import.json for a staged session
{
  "asset_session_id": "ass_example",
  "expected_session_revision": 5,
  "manifest": {
    "kind": "staged",
    "entries": [{ "client_local_id": "master-001", "asset_id": "asset_example" }]
  }
}

// review.json
{
  "expected_revision": 6,
  "resolution_overrides": [{
    "policy_version": "resolution-v1",
    "reason": "customer-supplied-only-source",
    "effective_ppi": 120,
    "output": "print-8x10"
  }]
}
// commit.json
{ "expected_revision": 7 }

Review returns PPI diagnostics with source pixels, output inches, effective PPI, grade, and human message. Below-minimum work requires an explicit audit override; it is not silently upscaled. Re-read the returned revision after every lifecycle step and use that value for the next review, commit, or cancel. The lower-level commands remain available for explicitly managed sessions: batchrelay assets sessions create|upload|get|finalize|cancel and batchrelay events images get|cancel. A session upload is one declared local JPEG; do not substitute a public HTTPS URL until ingestion is deployed. The CLI source currently has the folder/manifest path above, but its local build must stay in lockstep with the generated public API client before it can be released. The configured deployment is still the product gate: source ingestion from public HTTPS URLs and durable event-image commit fail closed without their corresponding server-side adapters.

Recovery

Retry uploads with the same session and idempotency key. Fix a manifest or CSV before retrying prepare. Review unresolved bindings rather than committing them. A stale commit returns a conflict, so prepare and review again with the current revisions. Cancel abandoned sessions and imports instead of reusing an expired upload grant.

Start

Core Concepts

Product reference

Asset sessions and event image imports

Resolution policy

Recovery

​Resolution policy

​Recovery

Resolution policy

Recovery