{"schemaVersion":1,"name":"FlowRelay Agent Operations API","version":"v1","platform":{"schemaVersion":1,"platformKey":"shopify_flow","platformName":"Shopify Flow","editionName":"FlowRelay for Shopify Flow","automationSystem":"shopify_flow","billingProvider":"shopify"},"docs":{"docsHome":"https://docs.flowrelay.app/","gettingStarted":"https://docs.flowrelay.app/getting-started/","firstEvent":"https://docs.flowrelay.app/getting-started/first-event/","agentAccess":"https://docs.flowrelay.app/agent-access/","grantsAndScopes":"https://docs.flowrelay.app/agent-access/grants-and-scopes/","agentOrientation":"https://docs.flowrelay.app/agent-access/agent-orientation/","agentMissionPlaybooks":"https://docs.flowrelay.app/agent-access/agent-mission-playbooks/","agentSetupGuide":"https://docs.flowrelay.app/agent-access/setup-with-an-agent/","endpointSwapPlan":"https://docs.flowrelay.app/agent-access/endpoint-swap-plan/","availabilityAndRefusals":"https://docs.flowrelay.app/agent-access/availability-and-refusals/","triggerMapping":"https://docs.flowrelay.app/setup/trigger-variants-and-event-mapping/","usageLimits":"https://docs.flowrelay.app/operate/usage-limits/","skillsReference":"https://docs.flowrelay.app/agent-access/skills/","operatorSkill":"https://docs.flowrelay.app/agent-access/skills/flowrelay-operator/SKILL.md","apiReference":"https://docs.flowrelay.app/reference/api/","cliReference":"https://docs.flowrelay.app/reference/cli/","mcpReference":"https://docs.flowrelay.app/reference/mcp/","publicStatus":"https://api.flowrelay.app/status.json","actionIntents":"https://docs.flowrelay.app/reference/action-intents/","errorCodes":"https://docs.flowrelay.app/recover/error-codes/","openApi":"https://docs.flowrelay.app/reference/openapi/agent-operations.openapi.json","llms":"https://docs.flowrelay.app/llms.txt"},"quickstart":[{"key":"read_manifest","title":"Identify this Agent Operations surface","description":"Read the public manifest first to confirm platform identity, docs URLs, safety rules, capabilities, and route names.","route":"/agent/v1/manifest","cli":"flowrelay-agent manifest","docsUrl":"https://docs.flowrelay.app/agent-access/agent-orientation/","requiresAgentToken":false},{"key":"inspect_grant","title":"Inspect the current grant","description":"Read the active grant to understand authority tier, scopes, expiration, safety guidance, and what actions are unavailable.","route":"/agent/v1/grant","cli":"flowrelay-agent grant","docsUrl":"https://docs.flowrelay.app/agent-access/grants-and-scopes/","requiresAgentToken":true},{"key":"inspect_setup_state","title":"Read setup state and next actions","description":"Read setup state before creating or changing anything. Use checklist, nativeReferenceScopes, and nextRecommendedActions to decide the next safe step.","route":"/agent/v1/setup-state","cli":"flowrelay-agent setup-state","docsUrl":"https://docs.flowrelay.app/getting-started/first-event/","requiresAgentToken":true},{"key":"check_plan_usage","title":"Check plan usage before loops","description":"Read usage meters, paid-plan event grace state, enforcement state, and retry guidance before broad investigation, polling, or repeated action previews.","route":"/agent/v1/plan-usage","cli":"flowrelay-agent plan-usage","docsUrl":"https://docs.flowrelay.app/operate/usage-limits/","requiresAgentToken":true},{"key":"use_agent_setup_guide","title":"Use the agent setup guide","description":"For new endpoint work, inventory sender facts, confirm plan usage, create one endpoint when scoped, prove one synthetic FlowRelay handoff, and stop before human-only sender or Shopify Flow changes.","route":null,"cli":null,"docsUrl":"https://docs.flowrelay.app/agent-access/setup-with-an-agent/","requiresAgentToken":false},{"key":"use_endpoint_swap_plan","title":"Use the endpoint swap plan","description":"For existing sender or receiver lanes, inventory endpoints, choose one safe pilot, confirm plan fit and rollback, prove one FlowRelay handoff, then prepare the broader cutover plan.","route":null,"cli":null,"docsUrl":"https://docs.flowrelay.app/agent-access/endpoint-swap-plan/","requiresAgentToken":false},{"key":"create_endpoint","title":"Create the FlowRelay endpoint when scoped","description":"Create one endpoint only when the grant includes endpoint write authority. Generic endpoint setup needs no Shopify resource scope; native Product, Order, or Customer setup requires the matching granted scope from setup-state nativeReferenceScopes. Read trigger mapping guidance before choosing triggerVariant or resource path fields. The endpoint secret is revealed once in the response.","route":"/agent/v1/endpoints","cli":"flowrelay-agent create-endpoint --json endpoint.json","docsUrl":"https://docs.flowrelay.app/setup/trigger-variants-and-event-mapping/","requiresAgentToken":true},{"key":"enable_shopify_flow_trigger","title":"Enable the matching Shopify Flow trigger","description":"Use the endpoint's flowSetupGuide to guide the merchant or separately authorized Shopify operator. FlowRelay does not edit Shopify Flow workflows.","route":null,"cli":null,"docsUrl":"https://docs.flowrelay.app/setup/shopify-flow-trigger/","requiresAgentToken":false},{"key":"send_test_event","title":"Send one authenticated test event from the sender","description":"Use senderSetupInstructions to configure the external sender. FlowRelay does not ask agents to expose or store sender secrets.","route":null,"cli":null,"docsUrl":"https://docs.flowrelay.app/getting-started/first-event/","requiresAgentToken":false},{"key":"check_event_result","title":"Check the first FlowRelay receipt","description":"Read the latest event result and confirm whether FlowRelay accepted, rejected, delivered, or needs recovery. Delivered means Shopify Flow handoff, not downstream workflow completion.","route":"/agent/v1/event-result","cli":"flowrelay-agent event-result --endpoint-id <endpoint-id>","docsUrl":"https://docs.flowrelay.app/operate/receipts/","requiresAgentToken":true}],"safety":{"neverRequest":["Shopify tokens","Shopify session data","FlowRelay agent tokens after one-time reveal","endpoint secrets except one-time create or rotation responses","raw event bodies by default","full authentication headers or HMAC values","database URLs","customer data copied into prompts or tracked files"],"humanOnly":["Shopify billing approval","agent grant creation, revocation, tier changes, or scope expansion","Shopify optional data-access scope approval for native Product, Order, or Customer triggers","Shopify Flow workflow edits unless separately authorized outside FlowRelay","app install or uninstall","Shopify staff permission changes","support ticket submission without human consent"],"governedActionsRequire":["preview before execute","explicit confirmation for side-effecting execute steps","idempotency keys where the API requires them","audit records for approved actions","redacted summaries instead of raw secret or event-body material"],"mcp":{"transport":"streamable_http","codeMode":true,"exposedTools":["search","execute"],"outboundNetwork":"disabled","authLocation":"host_request_handler"}},"credentialGuidance":{"profileModel":"one profile per store-scoped grant","storeTokenIn":["environment variable","OS keychain","secret manager","MCP host secret config"],"doNotStoreTokenIn":["repo files","docs","prompts","tickets","logs","profile JSON","screenshots"],"verifyBeforeAction":["/agent/v1/grant","/agent/v1/plan-usage"],"grantIdentitySource":"/agent/v1/grant","profileSuggestionSource":"/agent/v1/grant","contextHeaders":["X-FlowRelay-Expected-Platform-Key","X-FlowRelay-Expected-Platform-Account-Id","X-FlowRelay-Expected-Shop-Domain","X-FlowRelay-Expected-Installation-Id"]},"capabilities":["setup_state_read","plan_usage_read","billing_handoff","agent_grant_read","endpoint_read","endpoint_create","endpoint_edit_intent","endpoint_delete_intent","endpoint_test_intent","event_list_read","event_read","reliability_health_read","replay_intent","secret_rotation_intent","diagnostics_share_intent","support_request_intent","expansion_request_submit","feature_request_submit","mcp_agent_operations_access"],"capabilityDetails":[{"capability":"setup_state_read","title":"Read setup state","description":"Read store setup, endpoint summaries, readiness, checklist, and next recommended actions.","route":"/agent/v1/setup-state","method":"GET","requiredScopes":["setup:read"],"access":"agent_grant","effect":"read_only","requiresConfirmation":false,"docsUrl":"https://docs.flowrelay.app/getting-started/first-event/"},{"capability":"plan_usage_read","title":"Read plan and usage","description":"Read billing plan, published usage meters, paid-plan event grace state, and enforcement state without creating or approving charges.","route":"/agent/v1/plan-usage","method":"GET","requiredScopes":["setup:read"],"access":"agent_grant","effect":"read_only","requiresConfirmation":false,"docsUrl":"https://docs.flowrelay.app/operate/usage-limits/"},{"capability":"billing_handoff","title":"Prepare billing handoff","description":"Read billing options and human approval links. Agents cannot approve Shopify billing.","route":"/agent/v1/billing-handoff","method":"GET","requiredScopes":["setup:read"],"access":"agent_grant","effect":"handoff_only","requiresConfirmation":false,"docsUrl":"https://docs.flowrelay.app/reference/api/"},{"capability":"agent_grant_read","title":"Read current grant","description":"Read the active grant, scopes, expiry, authority tier, and safety guidance.","route":"/agent/v1/grant","method":"GET","requiredScopes":[],"access":"agent_grant","effect":"read_only","requiresConfirmation":false,"docsUrl":"https://docs.flowrelay.app/agent-access/grants-and-scopes/"},{"capability":"endpoint_read","title":"Read endpoint detail","description":"Read one endpoint detail, setup guidance, recent events, and safe diagnostics state without full secrets.","route":"/agent/v1/endpoints/{endpointId}","method":"GET","requiredScopes":["setup:read"],"access":"agent_grant","effect":"read_only","requiresConfirmation":false,"docsUrl":"https://docs.flowrelay.app/setup/endpoints/"},{"capability":"endpoint_create","title":"Create endpoint","description":"Create one endpoint for the authorizing store. Read the trigger mapping reference before choosing triggerVariant or resource path fields. The endpoint secret appears once in the response.","route":"/agent/v1/endpoints","method":"POST","requiredScopes":["setup:read","endpoint:write"],"access":"agent_grant","effect":"create_resource","requiresConfirmation":false,"docsUrl":"https://docs.flowrelay.app/setup/trigger-variants-and-event-mapping/"},{"capability":"endpoint_edit_intent","title":"Preview or execute endpoint edit","description":"Edit safe endpoint metadata and mapping through preview/execute action-preview controls. Use the trigger mapping reference before changing triggerVariant, resourceIdPath, or relatedResourceIdPath.","route":"/agent/v1/endpoints/{endpointId}/edit-intents","method":"POST","requiredScopes":["setup:read","endpoint:write"],"access":"agent_grant","effect":"preview_or_execute","requiresConfirmation":true,"docsUrl":"https://docs.flowrelay.app/setup/trigger-variants-and-event-mapping/"},{"capability":"endpoint_delete_intent","title":"Preview or execute endpoint delete","description":"Permanently delete an archived endpoint URL through action-preview controls while preserving historical receipts.","route":"/agent/v1/endpoints/{endpointId}/delete-intents","method":"POST","requiredScopes":["setup:read","endpoint:delete"],"access":"agent_grant","effect":"preview_or_execute","requiresConfirmation":true,"docsUrl":"https://docs.flowrelay.app/reference/action-intents/"},{"capability":"endpoint_test_intent","title":"Prepare endpoint test handoff","description":"Preview sender-test instructions. Execute returns a handoff refusal instead of sending signed traffic.","route":"/agent/v1/endpoints/{endpointId}/test-intents","method":"POST","requiredScopes":["setup:read","endpoint:test"],"access":"agent_grant","effect":"handoff_only","requiresConfirmation":false,"docsUrl":"https://docs.flowrelay.app/getting-started/first-event/"},{"capability":"event_list_read","title":"List events","description":"List retained store-scoped event summaries with safe filters and no raw event bodies.","route":"/agent/v1/events","method":"GET","requiredScopes":["event:read"],"access":"agent_grant","effect":"read_only","requiresConfirmation":false,"docsUrl":"https://docs.flowrelay.app/operate/event-history/"},{"capability":"event_read","title":"Read event detail","description":"Read one retained event receipt, handoff facts, recovery guidance, replay history, and diagnostics state.","route":"/agent/v1/events/{eventId}","method":"GET","requiredScopes":["event:read"],"access":"agent_grant","effect":"read_only","requiresConfirmation":false,"docsUrl":"https://docs.flowrelay.app/operate/receipts/"},{"capability":"reliability_health_read","title":"Read reliability health","description":"Read store, endpoint, or trigger-variant reliability summaries derived from retained event and replay facts.","route":"/agent/v1/reliability/tenant","method":"GET","requiredScopes":["event:read"],"access":"agent_grant","effect":"read_only","requiresConfirmation":false,"docsUrl":"https://docs.flowrelay.app/operate/event-history/"},{"capability":"replay_intent","title":"Preview or execute replay","description":"Preview replay safety for a retained event, then execute only with explicit confirmation because Shopify Flow side effects may run again.","route":"/agent/v1/events/{eventId}/replay-intents","method":"POST","requiredScopes":["event:read","replay:execute"],"access":"agent_grant","effect":"preview_or_execute","requiresConfirmation":true,"docsUrl":"https://docs.flowrelay.app/recover/replay/"},{"capability":"secret_rotation_intent","title":"Preview or execute secret rotation","description":"Rotate an endpoint secret through action-preview controls. The new secret appears once on execute.","route":"/agent/v1/endpoints/{endpointId}/secret-rotation-intents","method":"POST","requiredScopes":["setup:read","secret:rotate"],"access":"agent_grant","effect":"preview_or_execute","requiresConfirmation":true,"docsUrl":"https://docs.flowrelay.app/reference/action-intents/"},{"capability":"diagnostics_share_intent","title":"Preview or create diagnostics share","description":"Preview and create a redacted diagnostics share for a support request.","route":"/agent/v1/diagnostics-share-intents","method":"POST","requiredScopes":["setup:read","event:read","diagnostics:create"],"access":"agent_grant","effect":"preview_or_execute","requiresConfirmation":true,"docsUrl":"https://docs.flowrelay.app/recover/diagnostics/"},{"capability":"support_request_intent","title":"Preview or submit support request","description":"Preview and submit a structured support request through FlowRelay's first-party support ledger. FlowRelay mirrors safe summaries to the configured support workspace.","route":"/agent/v1/support-request-intents","method":"POST","requiredScopes":["setup:read","support:request"],"access":"agent_grant","effect":"preview_or_execute","requiresConfirmation":true,"docsUrl":"https://docs.flowrelay.app/agent-access/support-and-expansion-requests/"},{"capability":"expansion_request_submit","title":"Submit expansion request","description":"Record a non-binding FlowRelay-adjacent request for future edition interest, multi-platform event reliability, trigger lanes, operational-memory or exception-handling capabilities. The request must explain the concrete FlowRelay fit and come from a real merchant task or explicit merchant ask.","route":"/agent/v1/expansion-requests","method":"POST","requiredScopes":["expansion:request"],"access":"agent_grant","effect":"create_resource","requiresConfirmation":false,"docsUrl":"https://docs.flowrelay.app/agent-access/support-and-expansion-requests/"},{"capability":"feature_request_submit","title":"Submit feature request","description":"Record a non-binding request for a missing FlowRelay capability inside the current product surface. The request must explain the concrete merchant workflow, current FlowRelay gap, desired outcome, and FlowRelay fit.","route":"/agent/v1/feature-requests","method":"POST","requiredScopes":["expansion:request"],"access":"agent_grant","effect":"create_resource","requiresConfirmation":false,"docsUrl":"https://docs.flowrelay.app/agent-access/support-and-expansion-requests/"},{"capability":"mcp_agent_operations_access","title":"Use MCP Agent Operations access","description":"Use MCP Agent Operations access over the Agent Operations OpenAPI contract when enabled. The host keeps auth out of sandbox code; if unavailable, use the Agent Operations API or CLI.","route":"/agent/v1/mcp","method":"POST","requiredScopes":[],"access":"agent_grant","effect":"mcp_agent_operations_access","requiresConfirmation":false,"docsUrl":"https://docs.flowrelay.app/reference/mcp/"}],"requiredScopes":["setup:read","event:read","endpoint:write","endpoint:delete","endpoint:test","replay:execute","secret:rotate","diagnostics:create","support:request","expansion:request"],"routes":{"manifest":"/agent/v1/manifest","setupState":"/agent/v1/setup-state","planUsage":"/agent/v1/plan-usage","billingHandoff":"/agent/v1/billing-handoff","grant":"/agent/v1/grant","eventResult":"/agent/v1/event-result","events":"/agent/v1/events","endpoints":"/agent/v1/endpoints","endpointDetail":"/agent/v1/endpoints/{endpointId}","endpointEditIntents":"/agent/v1/endpoints/{endpointId}/edit-intents","endpointDeleteIntents":"/agent/v1/endpoints/{endpointId}/delete-intents","endpointSecretRotationIntents":"/agent/v1/endpoints/{endpointId}/secret-rotation-intents","endpointTestIntents":"/agent/v1/endpoints/{endpointId}/test-intents","eventDetail":"/agent/v1/events/{eventId}","tenantReliabilityHealth":"/agent/v1/reliability/tenant","destinationReliabilityHealth":"/agent/v1/reliability/destination","replayIntents":"/agent/v1/events/{eventId}/replay-intents","diagnosticsShareIntents":"/agent/v1/diagnostics-share-intents","supportRequestIntents":"/agent/v1/support-request-intents","expansionRequests":"/agent/v1/expansion-requests","featureRequests":"/agent/v1/feature-requests","mcp":"/agent/v1/mcp"}}