# FromSunday.io Developer API

The FromSunday.io v1 Developer API supports authorized Sales Preview automation. It is intended for trusted integrations operated by FromSunday.io platform administrators, including the Hermes Sales Preview uploader. It is not a public signup API and does not expose ordinary customer church content.

## Base URL and authentication

- Base URL: https://fromsunday.io/api/developer/v1
- OpenAPI: https://fromsunday.io/openapi.json
- Authentication header: Authorization: Bearer <developer-api-key>
- Key prefix: fsdk_

Developer keys are created in the authenticated platform-admin Sales Preview interface. Raw keys are shown once; only a hash and key preview are stored. Never place a key in a URL, browser bundle, log, or public document.

## Scopes

- sales_previews:create — create a Sales Preview record.
- sales_previews:upload — initialize and complete sermon uploads.
- sales_previews:read — read a Sales Preview by identifier. These trusted platform-admin keys currently have platform-wide Sales Preview access.
- sales_previews:update — update approved Sales Preview fields.

## Operations

- POST /sales-previews — create or replay an idempotent Sales Preview request.
- GET /sales-previews/{previewId} — read an authorized Sales Preview.
- PATCH /sales-previews/{previewId} — update approved Sales Preview metadata.
- POST /sales-previews/{previewId}/upload/init — initialize an upload target.
- POST /sales-previews/{previewId}/upload/complete — complete the initialized upload and start processing.

Create and upload requests carry an idempotencyKey in the JSON body. Reuse the same key only for an exact retry of the same logical operation. Upload completion must use the same developer key, preview ID, idempotency key, and object path returned by initialization.

## Versioning and deprecation

Stable operations use a major version in the URL (/api/developer/v1). Breaking wire-contract changes require a new major path. Before a supported major version is retired, FromSunday.io will document the replacement and planned date in this guide and send standard Deprecation and Sunset response headers during the migration period.

## Response envelope

Success response:

    { "data": { "...": "operation-specific fields" }, "error": null }

Error response:

    { "data": null, "error": { "message": "Human-readable detail", "code": "STABLE_CODE" } }

Missing bearer credentials return 401. Invalid, expired, revoked, or insufficiently scoped credentials return 403. Route-level JSON shape failures return 400. Deeper domain validation can currently surface as a 500 response; correct the request before retrying, and preserve the same idempotency key for an exact logical retry.

For access questions, contact support@fromsunday.io.