# Agent Operations API Reference

Canonical: https://docs.flowrelay.app/reference/api/
Markdown: https://docs.flowrelay.app/reference/api.md

Agent Operations API as the canonical machine access contract for scoped reads and action previews.

## 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: GET /agent/v1/manifest; Use it for: Edition identity, capability metadata, docs URLs, and safety boundaries.
- Route: GET /agent/v1/plan-usage; Use it for: Exact published usage meters, remaining capacity, and enforcement state before loops or high-volume work.
- Route: https://docs.flowrelay.app/llms.txt; Use it for: Canonical human and Markdown docs discovery.
- Route: https://docs.flowrelay.app/reference/openapi/agent-operations.openapi.json; Use it for: Exact request and response contract discovery.
- Route: https://docs.flowrelay.app/setup/trigger-variants-and-event-mapping/; Use it for: Product meaning for triggerVariant, resourceIdPath, relatedResourceIdPath, and mapping fields.
- Route: https://docs.flowrelay.app/agent-access/agent-mission-playbooks/; Use it for: Translate an operator mission into context reads, allowed actions, and escalation boundaries.
- Route: https://docs.flowrelay.app/agent-access/availability-and-refusals/; Use it for: 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.

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

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

```sh
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.

```sh
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.

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

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

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

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

```sh
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.

```sh
curl -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. Public examples must never include real bearer tokens, grant tokens, authentication headers, Shopify tokens, sessions, or private endpoint material.

- Signal: scope; How to use it: Confirms whether the grant permits the read, preview, or execution.
- Signal: actor; How to use it: Preserves human or authorized-agent attribution.
- Signal: refusal; How to use it: 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: Setup and endpoints; Purpose: Explain how the sender, event type, authentication mode, and Shopify Flow trigger are configured.
- Read area: Events and receipts; Purpose: Find what FlowRelay accepted, where the handoff stopped, and what recovery options exist.
- Read area: Diagnostics and plan state; Purpose: Prepare redacted support collaboration and understand published usage limits.

## 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.

## 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.

## Example Surface
- `curl https://api.flowrelay.app/agent/v1/manifest`
- `curl -H "Authorization: Bearer $FLOWRELAY_AGENT_TOKEN" https://api.flowrelay.app/agent/v1/plan-usage`
- `curl -H "Authorization: Bearer $FLOWRELAY_AGENT_TOKEN" https://api.flowrelay.app/agent/v1/events?limit=25`
- `POST /agent/v1/endpoints`
- `POST /agent/v1/events/{eventId}/replay-intents`

## Safety Boundary
Do not include raw event bodies, endpoint secrets, authentication headers, HMAC values, Shopify tokens, Shopify sessions, database URLs, customer data, merchant incidents, or copied private logs in public examples.