FlowRelay
Reference
Agent Operations API Reference
Agent Operations API as the canonical machine access contract for scoped reads and governed action intents.
Start with the manifest #
Use the manifest before authenticated calls. It identifies the Shopify Flow edition, capability URLs, safety boundaries, OpenAPI location, docs index, CLI reference, MCP reference, and current public docs pointers.
| Route | Use it for |
|---|---|
| GET /agent/v1/manifest | Edition identity, capability metadata, docs URLs, and safety boundaries. |
| https://docs.flowrelay.app/llms.txt | Canonical human and Markdown docs discovery. |
| https://docs.flowrelay.app/reference/openapi/agent-operations.openapi.json | Exact request and response contract discovery. |
Authentication model #
Authenticated Agent Operations use merchant-authorized grant tokens. Public examples must never include real bearer tokens, grant tokens, auth headers, Shopify tokens, sessions, or private endpoint material.
| Signal | How to use it |
|---|---|
| scope | Confirms whether the grant permits the read, preview, or execution. |
| actor | Preserves human or authorized-agent attribution. |
| refusal | Explains why an action is outside authority or unsafe. |
Reads #
Read routes return safe setup, event history, receipt, diagnostics, plan, and grant facts without exposing raw private material unless the product explicitly authorizes that surface.
| Read area | Purpose |
|---|---|
| Setup and endpoints | Explain how the sender, event type, auth mode, and Shopify Flow trigger are configured. |
| Events and receipts | Find what FlowRelay accepted, where the handoff stopped, and what recovery options exist. |
| Diagnostics and plan state | Prepare support-safe collaboration and understand usage limits. |
Action intents #
Side-effecting operations use preview, confirmation, idempotency, metering, audit, and refusal semantics. Use the action-intents reference before replay, diagnostics share, endpoint edit, rotation, delete, or test execution.
Errors and schemas #
Use stable error codes and generated schemas for exact fields. The prose docs explain product meaning; the generated OpenAPI contract explains exact request and response shape.