FlowRelay
Reference
Agent Operations API Reference
The Agent Operations API is the canonical machine-access contract for FlowRelay. The API, CLI, and MCP are access surfaces over this one contract; they do not grant separate authority. Use it for scoped reads and action previews.
Start with the manifest #
Use the manifest before authenticated calls, and reread it before reusing cached capability URLs or operation names. It identifies the live edition (Shopify Flow), capability URLs, safety boundaries, the OpenAPI location, the docs index, the CLI reference, the MCP reference, and current public docs pointers.
| Route | Use it for |
|---|---|
| GET /agent/v1/manifest | Edition identity, capability metadata, docs URLs, and safety boundaries. |
| GET /agent/v1/plan-usage | Exact usage meters, remaining capacity, enforcement state, and retry guidance before loops or high-volume work. |
| 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. |
| https://docs.flowrelay.app/setup/trigger-variants-and-event-mapping/ | Product meaning for triggerVariant, resourceIdPath, relatedResourceIdPath, and mapping fields. |
| https://docs.flowrelay.app/agent-access/agent-mission-playbooks/ | Translate an operator mission into context reads, allowed actions, and escalation boundaries. |
| https://docs.flowrelay.app/agent-access/setup-with-an-agent/ | Guide a new endpoint setup through inventory, one endpoint, one synthetic handoff proof, plan fit, and monitoring cadence. |
| https://docs.flowrelay.app/agent-access/endpoint-swap-plan/ | Guide an existing sender or receiver lane migration through inventory, one safe pilot, operator approval, rollback, and cutover planning. |
| https://docs.flowrelay.app/agent-access/support-and-expansion-requests/ | Choose the right lane for support issues, future-edition expansion demand, and missing FlowRelay feature requests. |
| https://docs.flowrelay.app/agent-access/availability-and-refusals/ | Explain whether an action is available, blocked, human-only, or outside the current edition. |
Get set up #
Start with public discovery, then add a merchant-authorized Agent Access bearer token for operational reads and approved action previews.
curl https://api.flowrelay.app/agent/v1/manifestcurl https://docs.flowrelay.app/reference/openapi/agent-operations.openapi.jsonhttps://docs.flowrelay.app/setup/trigger-variants-and-event-mapping/https://docs.flowrelay.app/agent-access/agent-mission-playbooks/https://docs.flowrelay.app/agent-access/availability-and-refusals/curl -H "Authorization: Bearer $FLOWRELAY_AGENT_TOKEN" https://api.flowrelay.app/agent/v1/plan-usagecurl -H "Authorization: Bearer $FLOWRELAY_AGENT_TOKEN" "https://api.flowrelay.app/agent/v1/events?limit=25"Authentication model #
Authenticated Agent Operations use merchant-authorized grant tokens supplied at request time. Public examples must never include real bearer tokens, grant tokens, session values, authentication headers, Shopify tokens, or private endpoint material; use placeholder environment variables such as $FLOWRELAY_AGENT_TOKEN.
| 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 facts (setup, event history, receipts, diagnostics, plan usage, and grant status) without exposing raw private material unless the grant explicitly authorizes that surface.
| Read area | Purpose |
|---|---|
| Setup and endpoints | Explain how the sender, event type, authentication mode, and Shopify Flow trigger are configured. |
| Events and receipts | Find what FlowRelay accepted, where the handoff stopped, and what recovery options exist. Delivered means FlowRelay handed the trigger to Shopify Flow. It does not mean downstream Shopify Flow branches, app calls, fulfillment changes, emails, or later systems completed. |
| Diagnostics and plan state | Prepare redacted support collaboration and understand usage safeguards. |
Action previews #
Side-effecting operations use preview, confirmation, idempotency, metering, audit, and refusal semantics. Use the action previews reference before replay, diagnostics share, endpoint edit, rotation, delete, or test execution.
Request lanes #
Use the structured request lanes when the agent needs human support, wants to record future-edition demand, or finds a missing FlowRelay capability. These routes record product-state signals so the team has context; they do not create a commitment, priority, or timeline. Responses acknowledge receipt, not delivery of a feature.
| Route | Use it for |
|---|---|
| POST /agent/v1/support-request-intents | Previewing or submitting an active help or recovery request with consent, redaction, and safe support context. |
| POST /agent/v1/expansion-requests | Recording non-binding demand for future platform, native-edition, trigger-lane, multi-store, or event-reliability expansion. |
| POST /agent/v1/feature-requests | Recording non-binding requests for missing FlowRelay capabilities inside the current product surface, not support tickets, expansion requests, or generic wishlists. |
Errors and schemas #
Use support codes and generated schemas for exact fields. The prose docs explain product meaning; the generated OpenAPI contract explains exact request and response shape. Endpoint create and edit work should pair the OpenAPI schema with the trigger variants and event mapping reference.
Mission and availability #
When an agent receives a goal rather than a specific route, use the mission playbooks before tool use. When a route exists but may be blocked by scope, usage, target state, safety, or product boundary, use the availability and refusals guide before retrying.