Agent Workflow Lifecycle

Agent Workflow Lifecycle

Agents can create complete database workflows through the REST API. The lifecycle is deliberately staged so creating a definition never silently starts a schedule.

Required scopes

Use connections, query, and workflows. Add workflow_credentials with an organization admin role when the action needs authenticated delivery.

1. Create a paused draft

POST /api/v1/workflows
Authorization: Bearer afd_your_key
Content-Type: application/json

Supply the source connectionId, schedule, query steps, conditions, and actions. Creation returns an inactive draft even if the submitted body requests activation.

2. Revise without overwriting another editor

Read the workflow and include its current draftRevision when updating:

{
  "expectedDraftRevision": 3,
  "name": "Customers crossing the renewal window",
  "steps": [],
  "actions": []
}

Send the body to PATCH /api/v1/workflows/{id}. A stale revision is rejected instead of silently replacing a newer draft.

3. Preview source rows

curl -X POST \
  https://app.aifordatabase.com/api/v1/workflows/WORKFLOW_ID/preview \
  -H "Authorization: Bearer afd_your_key"

Preview executes draft queries and returns bounded raw rows, condition state, and wouldRunActions. It never contacts the action destination and does not create a workflow run.

4. Test one live action

After reviewing preview rows:

curl -X POST \
  https://app.aifordatabase.com/api/v1/workflows/WORKFLOW_ID/actions/0/test \
  -H "Authorization: Bearer afd_your_key" \
  -H "Content-Type: application/json" \
  -d '{"confirmDelivery":true}'

This is a real external request. The response contains sanitized HTTP attempts, status codes, retry timing, and a bounded credential-redacted response body.

5. Publish explicitly

curl -X PATCH \
  https://app.aifordatabase.com/api/v1/workflows/WORKFLOW_ID \
  -H "Authorization: Bearer afd_your_key" \
  -H "Content-Type: application/json" \
  -d '{"isActive":true,"expectedDraftRevision":3}'

Publishing validates the draft and activates an immutable version for future scheduled runs. If validation returns warnings, review them and resend their exact values in acknowledgedWarnings.

6. Inspect or stop production

• GET /api/v1/workflows/{id}/runs returns paginated run history.
• PATCH /api/v1/workflows/{id} with isActive:false stops future scheduled runs.
• POST /api/v1/workflows/{id}/run runs the current draft, including live actions.