Developer docs / uniform V2

Agent API V2

Preview → approve → execute → receipt. This page gives a low-capability agent a runnable first request, the evidence to check, and the next action when it fails.

Run the real campaign workflow

Create the campaign, prospects, and sequence; stop for owner approval; then verify the real launch receipt.

Before you start

Create a workspace-scoped agent key in the authenticated console. Keep it on a server or controlled worker; never expose it in a public browser bundle.

Activate & API in the console ↗

0. Set the base URL, auth, and scopes

Base URLhttps://api.synthcrew.io — do not append the discovery path.

AuthenticationSend Authorization: Bearer $SYNTHCREW_AGENT_KEY.

ScopesUse only routes returned by the key-filtered catalog; scopes are not inferred from labels.

1. Verify the connection

Run the side-effect-free self-test first. A successful response proves authentication, workspace binding, scope filtering, and contract availability—not provider readiness or delivery.

export SYNTHCREW_AGENT_KEY="replace-with-your-key"
curl --fail-with-body https://api.synthcrew.io/api/v2/agent/self-test \
  -H "Authorization: Bearer $SYNTHCREW_AGENT_KEY" -H "X-API-Version: 2"

Evidence anchor: check HTTP 200, the returned workspace binding, and the allowed scopes.

2. Discover what this key can use

Read the compact catalog before choosing a resource route. It names operation IDs, required scopes, human steps, and error recovery.

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

Next action: choose a route returned in routes; do not guess a path from a capability name.

3. Make a first read

Start with a read-only resource request. This example lists up to ten leads and does not change workspace state.

curl --fail-with-body 'https://api.synthcrew.io/api/v2/agent/prospects?limit=10' \
  -H "Authorization: Bearer $SYNTHCREW_AGENT_KEY" -H "X-API-Version: 2"

Evidence anchor: use returned IDs and status fields; do not invent missing values.

4. Mutate safely

Every mutation gets a stable run ID and idempotency key. Reuse both when recovering from a timeout; do not submit the same action with a new key.

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

Evidence anchor: preserve the operation ID, idempotency value, and terminal receipt.

5. Local operation records: preview → review → receipt

01Preview

Record a bounded local automation preview. This compatibility operation makes no provider or network call.

02Human review

A person reviews the exact preview when approval is required.

03Execute

Apply the approved local record with the same replay identifiers. Use the real campaign workflow for launch.

04Receipt

Read operation state until the final status is known and preserve the evidence.

Read the operations guide ↗

Common errors and next actions

401 / 403Check key, workspace, and scopes. Stop; do not borrow a broader credential.

409Read the conflict and existing operation. Do not retry with a new idempotency key.

429 / 5xxHonor retry headers, bound retries, and reuse mutation identifiers.

Open the full error contract ↗

Browse the API referenceFind routes by purpose, scope, side effect, and human boundary.Use a rendered SDK guideInstall the Python or TypeScript reference client and run its self-test.Download contract Markdown ↧Raw Markdown download for local review.