Human approvals for AI agents (human in the loop)

Your agent asks a person to approve or reject one action. A signed-in person decides in the Flowyn dashboard. Your runtime reads the decision and decides how to continue.

How approvals work

Your runtime creates an approval request for a running run.
A signed-in member of your workspace approves or rejects it in the dashboard, with an optional reason.
Your runtime polls the approval, reads the decision, and continues or stops in its own code.

Flowyn is the durable decision service. It does not block, pause, resume, cancel, or execute anything, and it cannot verify that your agent honoured the decision. approved means a person recorded an approval; it does not mean the action ran.

Create a request

curl -X POST https://api.flowyn.dev/v1/agent-approvals \
  -H "Authorization: Bearer $FLOWYN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: approval-refund-1042" \
  -d '{
    "run_id": "3b9d2f7a-8c41-4e0b-a5d6-0f1e2d3c4b5a",
    "title": "Refund order 1042",
    "description": "Refund 19.99 USD to the original card.",
    "expires_in_seconds": 3600,
    "request_key": "refund-1042"
  }'

title (up to 80 characters) and description (up to 240) are plain text shown to the reviewer.
expires_in_seconds is 60 to 604,800 (7 days); the default is 24 hours.
request_key is optional and unique per run. Repeating it with the same content returns the existing approval with HTTP 200, so retries are safe.

Wait for the decision

Poll GET /v1/agent-approvals/{id} with backoff: start near 2 seconds, double up to about 30 seconds, add jitter, and stop at expires_at. Flowyn does not push or long-poll.

bash

curl https://api.flowyn.dev/v1/agent-approvals/5c1f7a52-0d2e-4b6a-8a4f-2b7c9d1e3f40 \
  -H "Authorization: Bearer $FLOWYN_API_KEY"

status	Meaning
pending	Waiting for a person.
approved	A person recorded an approval.
rejected	A person recorded a rejection.
expired	Nobody decided before `expires_at`.

Who can decide

Only a signed-in person with the member, admin, or owner role, through the dashboard or a user session. An API key can never decide. A live decision also needs a verified email. The first decision is final; a different later decision is 409 approval_decided. People see the reviewer's name and email; API keys see decided_by: null.

Acting on the decision

Use the approval id as the idempotency key for whatever your agent does next, because Flowyn cannot know whether or how often it acted.

Limits

Up to 10 pending requests per run and 500 pending requests per environment
The run must be running when the request is created

Next step

Provider connections.