Run Your First Workflow

This tutorial submits a non-mutating add-certificate dry run and follows the durable execution returned by Alfred.

Prerequisites

You need:

• the Alfred API base URL;
• an Alfred API key with workflows:add-certificate;
• curl and jq.

Set local shell variables:

export ALFRED_API_URL="https://alfred.headout.com"
export ALFRED_API_KEY="pk_live_replace_me"

Check the Service

curl --fail-with-body --silent --show-error \
  "$ALFRED_API_URL/readyz" | jq

A ready service returns "ok": true. A 503 response includes the dependency checks that are not ready. This proves Postgres, migration, and Redis readiness; it does not validate AWS or vendor credentials.

Submit a Dry Run

response=$(
  curl --fail-with-body --silent --show-error \
    -X POST "$ALFRED_API_URL/v1/workflows/add-certificate" \
    -H "Authorization: Bearer $ALFRED_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: tutorial-add-certificate-001" \
    -d '{
      "domainString": "shop.example.com",
      "options": {
        "dryRun": true,
        "skipReadinessCheck": false
      }
    }'
)

printf '%s\n' "$response" | jq
export EXECUTION_ID=$(printf '%s' "$response" | jq -r '.executionId')

The first accepted submission returns 202. The body includes the execution ID, current status, expected stages, and follow-up links.

Inspect the Execution

curl --fail-with-body --silent --show-error \
  "$ALFRED_API_URL/v1/executions/$EXECUTION_ID" \
  -H "Authorization: Bearer $ALFRED_API_KEY" | jq

Inspect status, currentStage, and stages. A stage's outputJson records its durable result; errorJson records structured failure context.

Repeat this request until status is terminal. The dry run does not mutate providers, but it still executes asynchronously and can report planning or provider-read failures through the execution.

Follow Events

curl -N --fail-with-body \
  "$ALFRED_API_URL/v1/executions/$EXECUTION_ID/events" \
  -H "Accept: text/event-stream" \
  -H "Authorization: Bearer $ALFRED_API_KEY"

Because the request accepts text/event-stream, each SSE record includes an event ID, event type, and the complete outbox event as JSON data. Reconnect with Last-Event-ID if the connection closes before the execution is terminal.

Verify Replay

Run the submission command again without changing its key or body. Alfred returns the same execution with HTTP 200 and:

Idempotent-Replay: true

Changing the body while keeping the same key returns 409 idempotency_conflict.

Next Steps

• Add production polling and controls with Monitor and Control Executions.
• Add recovery handling with Recover Workflows.
• Follow the canonical procedure for readback, SSE, or webhook registration in Consume Events.