Product Journey API

The Product Journey API exposes scoped versioned endpoints for canonical Journey authoring, immutable versions, activation, recording, evidence, Network commands, imports/exports, registry objects, settings, and verification.

This reference describes the reachable route families in the current application. It is not a generated OpenAPI contract and does not imply that every internal module is a public API.

Base and authentication

Connected developer requests use:

https://reshot.dev/api/v1/projects/{projectId}/...
Authorization: Bearer {project-api-key}

Mutation clients also send:

Idempotency-Key: bounded-unique-operation
If-Match: "{expectedRevision}"
x-reshot-channel: cli|api|...
x-request-id: {channel}:{operation}

Project and workspace authorization applies server-side. Never expose project keys in browser bundles or public content.

Journeys

Current route families include:

GET|POST /v1/projects/{projectId}/journeys
GET|...  /v1/projects/{projectId}/journeys/{journeyId}
POST     /v1/projects/{projectId}/journeys/{journeyId}/archive
POST     /v1/projects/{projectId}/journeys/{journeyId}/restore
GET|POST /v1/projects/{projectId}/journeys/{journeyId}/versions
POST     /v1/projects/{projectId}/journeys/{journeyId}/versions/{versionId}/branch
POST     /v1/projects/{projectId}/journeys/{journeyId}/versions/{versionId}/publish
POST     /v1/projects/{projectId}/journeys/{journeyId}/versions/{versionId}/supersede

Creation and drafting require idempotency and revision control. Published versions are immutable; changes create branches or new versions.

Activation and recording

POST /v1/projects/{projectId}/journeys/activation
POST /v1/projects/{projectId}/journeys/recorder-authorization
POST /v1/projects/{projectId}/journeys/recordings
POST /v1/projects/{projectId}/journeys/recordings/artifacts

Activation can register a native Playwright source contract. Recording authorization and artifacts remain private and scoped. Source must pass native execution and Review before trusted binding.

Evidence and verification

POST /v1/projects/{projectId}/evidence
POST /v1/projects/{projectId}/verify

Evidence uploads use exact content identity, bounded media, private storage, and Journey/Run references. Verification returns contract results; it does not grant an attributable human Decision.

Public account-free credential and Release Book verification have separate routes/tools and do not expose private project evidence.

Imports and exports

POST /v1/imports/{kind}
POST /v1/imports/candidates/{candidateId}/bind
GET  /v1/exports/{kind}

Imports produce candidates until exact supported binding. Playwright source preserves native execution. Scribe/Tango procedures and media remain unverified outward candidates. CSV/API ownership metadata cannot invent Journey identity.

Exports preserve canonical identity and explicit format/contract. Validate round-trip semantics rather than assuming visible-step equivalence.

Network and registry

POST /v1/projects/{projectId}/network/{command}
GET|POST /v1/registry/entries
GET|...  /v1/registry/entries/{entryId}
GET|POST /v1/registry/subscriptions
GET|...  /v1/registry/subscriptions/{subscriptionId}
GET       /v1/registry/discover

Network capability compilation fails unless the source contract is exact and native-run-passed. Registry discovery does not authorize execution. Identity, subscription, credentials, and command scope remain explicit.

Settings and assets

GET|POST /v1/projects/{projectId}/settings
GET       /v1/projects/{projectId}/settings/export
GET       /v1/assets/{path...}

Settings export is scoped. Asset delivery validates authorization or public publication policy, bounded paths, and storage identity.

Errors and concurrency

Treat authorization, validation, revision conflict, idempotency collision, unsupported source, unavailable integration, and infrastructure failure separately. Do not automatically retry permanent or semantic failures. Reuse an idempotency key only for the exact same mutation input.

Mutation lifecycle

Read the current resource and revision. Prepare one bounded mutation. Send a unique operation key and expected revision. On success, persist the returned identity/revision. On timeout, replay the exact same input and key. On conflict, fetch current state and perform an attributed merge rather than increasing the revision blindly.

This pattern applies to Journey creation, draft versions, Run transitions, Decisions, Publications, and settings changes.

Runs and observations

Some Run/Observation mutations are exposed through project resource dispatch routes used by the canonical client:

POST /v1/projects/{projectId}/journeys/{journeyId}/runs
POST /v1/projects/{projectId}/runs/{runId}/observations
POST /v1/projects/{projectId}/runs/{runId}/complete
POST /v1/projects/{projectId}/uploads
POST /v1/projects/{projectId}/uploads/{uploadId}/complete
POST /v1/projects/{projectId}/decisions

The generalized resource route still validates supported resource names and authorization. Do not assume an arbitrary table proxy.

Response identity

Responses return a data envelope or direct canonical result depending on route/client layer. Consumers should rely on documented identity, revision, contract/schema version, and content hash rather than UI-specific fields. Preserve request ID for support and audit correlation.

Rate limits and retries

Use exponential/bounded retry only for safe transient errors. Respect Retry-After where present. Do not retry revision conflicts, validation failures, unsupported source, or permission denial as infrastructure noise.

Privacy

Do not send reusable storage state, raw secrets, or customer data unless the documented private endpoint and policy require it. Public APIs and schemas expose contract structure, not workspace content. Apply retention, holds, deletion, and audit requirements to uploaded evidence.

Example client

The Reshot CLI’s canonical client builds project-scoped URLs, sends Bearer authentication, retries safe requests, requires operation keys/revisions, initializes presigned uploads, uploads bytes directly, and commits completion.

Use that behavior as the current executable reference. Generate a formal OpenAPI document only when it is tested against the routes and does not advertise internal or unavailable endpoints.

Continue with Reshot CLI, Product Journey Webhooks, and Import, Export, and Portability.