# FlowRelay Docs

> Public documentation index for FlowRelay. Fetch individual Markdown pages when an agent needs full page context.

Canonical docs origin: https://docs.flowrelay.app
Official product page: https://flowrelay.app/shopify-flow/
Shopify App Store listing: https://apps.shopify.com/flowrelay-1
Public status page: https://api.flowrelay.app/status
Public status JSON: https://api.flowrelay.app/status.json

## Quick answer

FlowRelay for Shopify Flow receives authenticated external events from outside systems, records receipt facts and replay context, and hands normalized triggers to Shopify Flow without replacing Shopify Flow.

Shopify scope boundary: Generic FlowRelay endpoints can run without Shopify Order, Customer, or Product read scopes. FlowRelay requests read_orders, read_customers, or read_products only when a merchant chooses the matching native Order, Customer, or Product trigger so Shopify Flow can receive a native reference supplied by the event payload. FlowRelay does not query, read, sync, enrich, browse, harvest, or export Shopify Orders, Customers, or Products for event enrichment.

## Start
- [Docs home](https://docs.flowrelay.app/) ([Markdown](https://docs.flowrelay.app/index.md))
- [Shopify App Store listing](https://apps.shopify.com/flowrelay-1)
- [Public status](https://api.flowrelay.app/status) ([JSON](https://api.flowrelay.app/status.json))
- [How it works](https://docs.flowrelay.app/getting-started/) ([Markdown](https://docs.flowrelay.app/getting-started.md))
- [First endpoint guide](https://docs.flowrelay.app/getting-started/first-endpoint/) ([Markdown](https://docs.flowrelay.app/getting-started/first-endpoint.md))
- [Send your first test event](https://docs.flowrelay.app/getting-started/first-event/) ([Markdown](https://docs.flowrelay.app/getting-started/first-event.md))

## Use cases
- [External events into Shopify Flow](https://docs.flowrelay.app/use-cases/external-events-to-shopify-flow/) ([Markdown](https://docs.flowrelay.app/use-cases/external-events-to-shopify-flow.md))
- [Swap over to FlowRelay](https://docs.flowrelay.app/use-cases/swapover-to-flowrelay/) ([Markdown](https://docs.flowrelay.app/use-cases/swapover-to-flowrelay.md))
- [Agency and developer partner kit](https://docs.flowrelay.app/use-cases/agency-developer-partner-kit/) ([Markdown](https://docs.flowrelay.app/use-cases/agency-developer-partner-kit.md))
- [Recover a failed handoff](https://docs.flowrelay.app/use-cases/recover-failed-handoff/) ([Markdown](https://docs.flowrelay.app/use-cases/recover-failed-handoff.md))
- [Work with a partner without sharing secrets](https://docs.flowrelay.app/use-cases/share-diagnostics-with-partner/) ([Markdown](https://docs.flowrelay.app/use-cases/share-diagnostics-with-partner.md))
- [Let an agent investigate an event](https://docs.flowrelay.app/use-cases/agent-assisted-operations/) ([Markdown](https://docs.flowrelay.app/use-cases/agent-assisted-operations.md))

## Setup
- [Create an endpoint](https://docs.flowrelay.app/setup/endpoints/) ([Markdown](https://docs.flowrelay.app/setup/endpoints.md))
- [Authenticate requests](https://docs.flowrelay.app/setup/authentication/) ([Markdown](https://docs.flowrelay.app/setup/authentication.md))
- [Event types and payloads](https://docs.flowrelay.app/setup/event-types-and-payloads/) ([Markdown](https://docs.flowrelay.app/setup/event-types-and-payloads.md))
- [Permissions and data access](https://docs.flowrelay.app/setup/permissions-and-data-access/) ([Markdown](https://docs.flowrelay.app/setup/permissions-and-data-access.md))
- [Trigger variants and event mapping](https://docs.flowrelay.app/setup/trigger-variants-and-event-mapping/) ([Markdown](https://docs.flowrelay.app/setup/trigger-variants-and-event-mapping.md))
- [Rotate credentials](https://docs.flowrelay.app/setup/rotate-credentials/) ([Markdown](https://docs.flowrelay.app/setup/rotate-credentials.md))
- [Add the Shopify Flow trigger](https://docs.flowrelay.app/setup/shopify-flow-trigger/) ([Markdown](https://docs.flowrelay.app/setup/shopify-flow-trigger.md))

## Operate and recover
- [Read receipts](https://docs.flowrelay.app/operate/receipts/) ([Markdown](https://docs.flowrelay.app/operate/receipts.md))
- [Event history](https://docs.flowrelay.app/operate/event-history/) ([Markdown](https://docs.flowrelay.app/operate/event-history.md))
- [Event lifecycle](https://docs.flowrelay.app/operate/event-lifecycle/) ([Markdown](https://docs.flowrelay.app/operate/event-lifecycle.md))
- [Retention](https://docs.flowrelay.app/operate/retention/) ([Markdown](https://docs.flowrelay.app/operate/retention.md))
- [Usage limits](https://docs.flowrelay.app/operate/usage-limits/) ([Markdown](https://docs.flowrelay.app/operate/usage-limits.md))
- [Support codes](https://docs.flowrelay.app/recover/error-codes/) ([Markdown](https://docs.flowrelay.app/recover/error-codes.md))
- [Retries, replay, and resend](https://docs.flowrelay.app/recover/retries-replay-and-resend/) ([Markdown](https://docs.flowrelay.app/recover/retries-replay-and-resend.md))
- [Replay an event](https://docs.flowrelay.app/recover/replay/) ([Markdown](https://docs.flowrelay.app/recover/replay.md))
- [Duplicates and idempotency](https://docs.flowrelay.app/recover/duplicates-and-idempotency/) ([Markdown](https://docs.flowrelay.app/recover/duplicates-and-idempotency.md))
- [Share diagnostics](https://docs.flowrelay.app/recover/diagnostics/) ([Markdown](https://docs.flowrelay.app/recover/diagnostics.md))
- [Work with support](https://docs.flowrelay.app/recover/support-signals/) ([Markdown](https://docs.flowrelay.app/recover/support-signals.md))

## Agent access and reference
- [Agent Access](https://docs.flowrelay.app/agent-access/) ([Markdown](https://docs.flowrelay.app/agent-access.md))
- [Grants and scopes](https://docs.flowrelay.app/agent-access/grants-and-scopes/) ([Markdown](https://docs.flowrelay.app/agent-access/grants-and-scopes.md))
- [Agent orientation](https://docs.flowrelay.app/agent-access/agent-orientation/) ([Markdown](https://docs.flowrelay.app/agent-access/agent-orientation.md))
- [Agent and API rate limits](https://docs.flowrelay.app/agent-access/rate-limits-and-backoff/) ([Markdown](https://docs.flowrelay.app/agent-access/rate-limits-and-backoff.md))
- [Agent mission playbooks](https://docs.flowrelay.app/agent-access/agent-mission-playbooks/) ([Markdown](https://docs.flowrelay.app/agent-access/agent-mission-playbooks.md))
- [Use FlowRelay with Shopify Sidekick](https://docs.flowrelay.app/agent-access/shopify-sidekick/) ([Markdown](https://docs.flowrelay.app/agent-access/shopify-sidekick.md))
- [Set up FlowRelay with an agent](https://docs.flowrelay.app/agent-access/setup-with-an-agent/) ([Markdown](https://docs.flowrelay.app/agent-access/setup-with-an-agent.md))
- [Endpoint swap plan](https://docs.flowrelay.app/agent-access/endpoint-swap-plan/) ([Markdown](https://docs.flowrelay.app/agent-access/endpoint-swap-plan.md))
- [Support, expansion, and feature requests](https://docs.flowrelay.app/agent-access/support-and-expansion-requests/) ([Markdown](https://docs.flowrelay.app/agent-access/support-and-expansion-requests.md))
- [Availability and refusals](https://docs.flowrelay.app/agent-access/availability-and-refusals/) ([Markdown](https://docs.flowrelay.app/agent-access/availability-and-refusals.md))
- [FlowRelay Operator Skill](https://docs.flowrelay.app/agent-access/skills/) ([Markdown](https://docs.flowrelay.app/agent-access/skills.md))
- [Raw FlowRelay Operator Skill](https://docs.flowrelay.app/agent-access/skills/flowrelay-operator/SKILL.md)
- [Glossary](https://docs.flowrelay.app/reference/glossary/) ([Markdown](https://docs.flowrelay.app/reference/glossary.md))
- [API reference](https://docs.flowrelay.app/reference/api/) ([Markdown](https://docs.flowrelay.app/reference/api.md))
- [CLI reference](https://docs.flowrelay.app/reference/cli/) ([Markdown](https://docs.flowrelay.app/reference/cli.md))
- [MCP reference](https://docs.flowrelay.app/reference/mcp/) ([Markdown](https://docs.flowrelay.app/reference/mcp.md))
- [Action previews](https://docs.flowrelay.app/reference/action-intents/) ([Markdown](https://docs.flowrelay.app/reference/action-intents.md))
- [OpenAPI](https://docs.flowrelay.app/reference/openapi/) ([Markdown](https://docs.flowrelay.app/reference/openapi.md))
- [Agent Operations OpenAPI JSON](https://docs.flowrelay.app/reference/openapi/agent-operations.openapi.json)

## Agent orientation
1. Start at this index.
2. Read the specific Markdown page for the task.
3. Use /agent/v1/manifest for edition identity, capability metadata, safety boundaries, and canonical docs URLs.
4. Use OpenAPI for exact contracts.
5. For endpoint create or edit work, read Permissions and data access plus Trigger variants and event mapping before choosing triggerVariant or resource path fields.
6. Use Agent mission playbooks to translate the operator's goal into context reads and safe actions.
7. Use First endpoint guide for a merchant-owned first setup, Agency and developer partner kit for partner-led merchant event paths, Use FlowRelay with Shopify Sidekick for Shopify Admin Sidekick guidance, Set up FlowRelay with an agent for a new Agent Access endpoint, Swap over to FlowRelay for merchant migration planning, and Endpoint swap plan for an existing sender or receiver path operated by an authorized agent.
8. Use Availability and refusals to decide whether a capability is allowed by scope, usage, target state, safety, and product boundary.
9. Use the FlowRelay Operator Skill for controlled setup, receipt investigation, recovery, diagnostics, support, and API/CLI/MCP selection.
10. Use one store-scoped CLI profile or MCP host entry per grant, then verify store identity before acting.
11. Use public /status.json or flowrelay-agent status for aggregate service status; do not treat it as merchant-specific health or downstream Shopify Flow completion.
12. Use the CLI, or MCP Agent Operations access when enabled, only through the same scoped Agent Operations grant.
13. Check Usage limits, Agent and API rate limits, and /agent/v1/plan-usage before broad reads, polling, or repeated action previews.

## Copy-paste starts
- API manifest: `curl https://api.flowrelay.app/agent/v1/manifest`
- Public status JSON: `curl https://api.flowrelay.app/status.json`
- CLI public status: `npx flowrelay-agent status --base-url https://api.flowrelay.app`
- CLI docs: `npx flowrelay-agent docs --base-url https://api.flowrelay.app`
- CLI profile identity check: `FLOWRELAY_AGENT_PROFILE=client-a FLOWRELAY_CLIENT_A_TOKEN=$FLOWRELAY_CLIENT_A_TOKEN npx flowrelay-agent whoami`
- MCP endpoint: `https://api.flowrelay.app/agent/v1/mcp` with `Authorization: Bearer $FLOWRELAY_AGENT_TOKEN`; add `X-FlowRelay-Expected-Platform-Key`, `X-FlowRelay-Expected-Platform-Account-Id`, `X-FlowRelay-Expected-Shop-Domain`, and `X-FlowRelay-Expected-Installation-Id` when the MCP host supports custom headers.
- MCP public status link: `https://api.flowrelay.app/status.json`; MCP execute remains limited to allowed `/agent/v1/*` operations.
- First endpoint guide: https://docs.flowrelay.app/getting-started/first-endpoint/
- Agency and developer partner kit: https://docs.flowrelay.app/use-cases/agency-developer-partner-kit/
- Swap over to FlowRelay: https://docs.flowrelay.app/use-cases/swapover-to-flowrelay/
- Set up FlowRelay with an agent: https://docs.flowrelay.app/agent-access/setup-with-an-agent/
- Endpoint swap plan: https://docs.flowrelay.app/agent-access/endpoint-swap-plan/
- Operator Skill source: https://docs.flowrelay.app/agent-access/skills/flowrelay-operator/SKILL.md

FlowRelay is built from the ground up for agent operations: authorized agents use receipts, scoped grants, action previews, redaction, and audit instead of raw event bodies, secrets, and guesswork.

## Safety boundary
Do not share endpoint secrets, authentication headers, HMAC values, tokens, raw event bodies, customer records, Shopify sessions, store passwords, or database URLs in public examples.