SynthCrew

Agent API V2 / real execution

Run real campaign work

Persisted steps · human launch approval · durable receipt

Use prepare_and_launch_campaign when an AI should build the real campaign, prospects, and sequence, stop for an owner, and launch only what that owner approved.

Start is not completion

Starting persists a validated run. Each advance queues one durable step. A 201 or 202 response means accepted—not finished. Completion requires status: succeeded and a terminal receipt.

Before starting

The workflow does not invent safety or legal evidence. Confirm active workspace access; connected, approved, healthy sender mailboxes with capacity; and truthful campaign compliance evidence recorded by a person. Recipients and copy must be real and authorized.

What happens

  1. Prepare real workspace resources.SynthCrew creates the campaign, prospects, and ordered sequence.
  2. Check real launch readiness.Connected sender, compliance metadata, sequence, and campaign state must pass.
  3. Stop for a person.An owner or admin reviews the immutable launch preview in the console.
  4. Launch and verify.After approval, the worker calls the real launch handler and verifies the durable receipt.

1. Read the live workflow contract

curl --fail-with-body 'https://api.synthcrew.io/api/v2/agent/workflow-runtime' \
  -H "Authorization: Bearer $SYNTHCREW_AGENT_KEY" \
  -H 'X-API-Version: 2'

The response gives the exact input schema, required scopes, states, mutation headers, and recovery rule for the current release.

2. Start a persisted run

Supply a connected sender mailbox, real authorized prospects, ordered copy, your real postal address, and an HTTPS unsubscribe URL. Never use placeholder recipients in live work.

curl --fail-with-body -X POST \
  'https://api.synthcrew.io/api/v2/agent/workflow-runs' \
  -H "Authorization: Bearer $SYNTHCREW_AGENT_KEY" \
  -H 'X-API-Version: 2' \
  -H "Idempotency-Key: $SYNTHCREW_IDEMPOTENCY_KEY" \
  -H "X-Agent-Run-Id: $SYNTHCREW_RUN_ID" \
  -H 'Content-Type: application/json' --data @workflow.json

Reuse both identifiers if this exact start request times out.

3. Advance exactly the current step

Read data.current_step.id. Submit that value as expected_step_id with a stable operation key for this step.

curl --fail-with-body -X POST \
  'https://api.synthcrew.io/api/v2/agent/workflow-runs/RUN_UUID/advance' \
  -H "Authorization: Bearer $SYNTHCREW_AGENT_KEY" \
  -H 'X-API-Version: 2' \
  -H "Idempotency-Key: $STEP_OPERATION_KEY" \
  -H "X-Agent-Run-Id: $SYNTHCREW_RUN_ID" \
  -H 'Content-Type: application/json' \
  --data '{"expected_step_id":"create_campaign"}'

While the run is queued or running, inspect it instead of submitting duplicate work.

4. Understand every state

readyQueue the exact current step.
queued / runningInspect with bounded backoff.
blockedRead the error, fix it, retry the same run.
waiting_for_humanAn owner/admin decides the launch preview.
succeededLaunch and terminal receipt are verified.
cancelledNo unfinished step will run.

When readiness is blocked

Keep the same run ID. Ask an owner or administrator to resolve the listed mailbox, legal, consent, sender, suppression, unsubscribe, or DKIM evidence in the console. Retry only check_readiness after they confirm the evidence. Never fabricate a passing value.

5. Keep the approval boundary human

When operation_id appears, the agent waits. An owner or admin opens Console → Agent API → Needs approval, reviews the exact fingerprint and preview, then approves or rejects. The API has no agent approval tool. Approval is bound to the workspace, Agent API key, workflow run, campaign, fingerprint, and expiry. After approval, advance execute_launch.

If approval expires, SynthCrew cancels only the old preview and returns the same run to request_approval. It does not duplicate the campaign, prospects, or sequence.

Data and secret handling

Successful and cancelled runs clear their original workflow input. Incomplete runs follow the workspace retention period. Worker jobs carry persisted identifiers, never your Agent API key secret.

Completion checklist

  • Workflow status is succeeded.
  • The verify_receipt step succeeded.
  • The operation receipt is terminal and succeeded.
  • The returned campaign state is the real launch result.

Read errors and retry rules ↗ · Use the SDK or MCP methods ↗