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 the generated effect model to distinguish reads, handoffs, previewed actions, and direct resource creation.

On this page

Start here #

Read the live manifest and complete the minimum setup before authenticated calls.

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.

Read the public manifest Confirms Shopify Flow edition identity, docs URLs, capability metadata, and safety boundaries.

curl https://api.flowrelay.app/agent/v1/manifest

Inspect the OpenAPI contract Use this for exact request and response shapes before calling authenticated routes.

curl https://docs.flowrelay.app/reference/openapi/agent-operations.openapi.json

Read mapping semantics Use this before creating or editing an endpoint through API, CLI, or MCP.

https://docs.flowrelay.app/setup/trigger-variants-and-event-mapping/

Read mission playbooks Use this to map the operator's goal to context reads, safe actions, and escalation.

https://docs.flowrelay.app/agent-access/agent-mission-playbooks/

Read availability guidance Use this before assuming a listed capability can be executed.

https://docs.flowrelay.app/agent-access/availability-and-refusals/

Read plan usage Check usage meters before broad reads, polling, or repeated action previews.

curl -H "Authorization: Bearer $FLOWRELAY_AGENT_TOKEN" https://api.flowrelay.app/agent/v1/plan-usage

Read scoped event history Requires a merchant-authorized Agent Access grant token.

curl -H "Authorization: Bearer $FLOWRELAY_AGENT_TOKEN" "https://api.flowrelay.app/agent/v1/events?limit=25"

Authenticate and read #

Use the scoped grant model and choose the smallest read for the job.

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.

Generated operation effect matrix #

This matrix is generated from Agent Operations OpenAPI schema version 2026-06-17. read_only returns facts; handoff_only returns or prepares a human-owned next step; preview_or_execute uses the preview, confirmation, and execute controls; create_resource records a new resource directly when its request is accepted.

Route and method	Operation ID	Required scopes	Access	Effect	Confirmation	Docs URL
GET /agent/v1/manifest	getAgentOperationsManifest	None	public	read_only	Not required	https://docs.flowrelay.app/reference/api/
GET /agent/v1/setup-state	getSetupState	setup:read	agent_grant	read_only	Not required	https://docs.flowrelay.app/getting-started/first-event/
GET /agent/v1/plan-usage	getPlanUsage	setup:read	agent_grant	read_only	Not required	https://docs.flowrelay.app/operate/usage-limits/
GET /agent/v1/billing-handoff	getBillingHandoff	setup:read	agent_grant	handoff_only	Not required	https://docs.flowrelay.app/reference/api/
GET /agent/v1/grant	getCurrentAgentGrant	None	agent_grant	read_only	Not required	https://docs.flowrelay.app/agent-access/grants-and-scopes/
GET /agent/v1/event-result	getLatestEventResult	event:read	agent_grant	read_only	Not required	https://docs.flowrelay.app/operate/receipts/
GET /agent/v1/events	listEvents	event:read	agent_grant	read_only	Not required	https://docs.flowrelay.app/operate/event-history/
GET /agent/v1/events/{eventId}	getEventDetail	event:read	agent_grant	read_only	Not required	https://docs.flowrelay.app/operate/receipts/
GET /agent/v1/reliability/tenant	getTenantReliabilityHealth	event:read	agent_grant	read_only	Not required	https://docs.flowrelay.app/operate/event-history/
GET /agent/v1/reliability/destination	getDestinationReliabilityHealth	event:read	agent_grant	read_only	Not required	https://docs.flowrelay.app/operate/event-history/
GET /agent/v1/endpoints/{endpointId}	getEndpointDetail	setup:read	agent_grant	read_only	Not required	https://docs.flowrelay.app/setup/endpoints/
POST /agent/v1/endpoints/{endpointId}/edit-intents	createEndpointEditIntent	setup:read, endpoint:write	agent_grant	preview_or_execute	Required	https://docs.flowrelay.app/setup/trigger-variants-and-event-mapping/
POST /agent/v1/endpoints/{endpointId}/delete-intents	createEndpointDeleteIntent	setup:read, endpoint:delete	agent_grant	preview_or_execute	Required	https://docs.flowrelay.app/reference/action-intents/
POST /agent/v1/endpoints/{endpointId}/secret-rotation-intents	createSecretRotationIntent	setup:read, secret:rotate	agent_grant	preview_or_execute	Required	https://docs.flowrelay.app/reference/action-intents/
POST /agent/v1/endpoints/{endpointId}/test-intents	createEndpointTestIntent	setup:read, endpoint:test	agent_grant	handoff_only	Not required	https://docs.flowrelay.app/getting-started/first-event/
POST /agent/v1/endpoints	createEndpoint	setup:read, endpoint:write	agent_grant	create_resource	Not required	https://docs.flowrelay.app/setup/trigger-variants-and-event-mapping/
POST /agent/v1/events/{eventId}/replay-intents	createReplayIntent	event:read, replay:execute	agent_grant	preview_or_execute	Required	https://docs.flowrelay.app/recover/replay/
POST /agent/v1/diagnostics-share-intents	createDiagnosticsShareIntent	setup:read, event:read, diagnostics:create	agent_grant	preview_or_execute	Required	https://docs.flowrelay.app/recover/diagnostics/
POST /agent/v1/support-request-intents	createSupportRequestIntent	setup:read, support:request	agent_grant	preview_or_execute	Required	https://docs.flowrelay.app/agent-access/support-and-expansion-requests/
POST /agent/v1/expansion-requests	createExpansionRequest	expansion:request	agent_grant	create_resource	Not required	https://docs.flowrelay.app/agent-access/support-and-expansion-requests/
POST /agent/v1/feature-requests	createFeatureRequest	expansion:request	agent_grant	create_resource	Not required	https://docs.flowrelay.app/agent-access/support-and-expansion-requests/

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, Source label, trigger variant, default or resolved 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.

Plan changes #

Preview state-changing work and use the correct request lane before execution.

Action previews #

Only preview_or_execute operations use the full preview, confirmation, idempotency, metering, audit, and refusal lifecycle. Use it for replay, diagnostics sharing, endpoint edit, secret rotation, endpoint deletion, and support request preview/submit. Endpoint creation and expansion or feature requests are direct create_resource operations; endpoint creation executes immediately and returns the new endpoint secret once. Endpoint-test intent is handoff_only and does not send signed traffic for the operator.

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. Support uses request-specific preview and submit states with consent and idempotency; the API does not claim that submit is bound to a persisted matching preview record. Expansion and feature requests are direct create_resource operations with expansion:request scope. All three record product-state signals without creating a commitment, priority, or timeline.

Route	Effect	Use it for
POST /agent/v1/support-request-intents	preview_or_execute	Previewing or submitting an active help or recovery request with consent, redaction, and safe support context.
POST /agent/v1/expansion-requests	create_resource	Recording non-binding demand for future platform, native-edition, trigger-lane, multi-store, or event-reliability expansion.
POST /agent/v1/feature-requests	create_resource	Recording non-binding requests for missing FlowRelay capabilities inside the current product surface, not support tickets, expansion requests, or generic wishlists.

Diagnose and check availability #

Use the error, schema, mission, and availability contracts instead of guessing.

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.

START

USE CASES

SET UP

OPERATE

RECOVER

AGENT ACCESS

REFERENCE