---
title: "Agent Workflow Lifecycle - Documentation"
description: "Create a paused workflow, preview rows safely, test one action, publish explicitly, and inspect production runs."
canonical: "https://www.aifordatabase.com/docs/agent-workflow-lifecycle/"
---

# Agent Workflow Lifecycle

advanced 9 min read

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

```http
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:

```json
{
  "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

```bash
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:

```bash
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

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

NoteDo not use a manual run as a preview. Manual runs have real delivery side effects.

Source: https://www.aifordatabase.com/docs/agent-workflow-lifecycle/