Agent Quickstart

Minimal commands and environment variables for agents running Dolphinflow workflows.

Environment

Use these names when an agent needs to run API calls or trigger workflows from a script.

export DOLPHINFLOW_API_URL="https://dolphinflow.xyz"
export DOLPHINFLOW_API_KEY="dk_live_..."
export DOLPHINFLOW_WEBHOOK_URL="https://dolphinflow.xyz/webhooks/example-webhook-id"
export DOLPHINFLOW_WEBHOOK_KEY="df_local_example_key"

For local development, use http://localhost:3001 for DOLPHINFLOW_API_URL and http://localhost:3001/webhooks/<webhook-id> for DOLPHINFLOW_WEBHOOK_URL.

DOLPHINFLOW_API_KEY is created from Dashboard -> API keys. It is used for protected app API routes such as workflows and executions.

DOLPHINFLOW_WEBHOOK_KEY is not a global platform key. It is a simple shared secret you configure on a webhook trigger by enabling auth and setting:

Header name: Authorization
Header value: Bearer df_local_example_key

Health Check

Before touching workflows, verify the API is alive:

curl "$DOLPHINFLOW_API_URL/health"

List Workflows

Protected API routes expect Authorization: Bearer <api-key>.

curl "$DOLPHINFLOW_API_URL/workflows" \
  -H "Authorization: Bearer $DOLPHINFLOW_API_KEY"

Agents should read the workflow capability document before creating or editing workflow graphs. It returns supported node types, config fields, validation rules, webhook paths, and example graph payloads.

curl "$DOLPHINFLOW_API_URL/workflows/agent/capabilities" \
  -H "Authorization: Bearer $DOLPHINFLOW_API_KEY"

For the full prompt-to-workflow process, request body, validation response, and examples, use Agent Workflow Creation.

To inspect one workflow in an agent-friendly shape, fetch its graph, diagnostics, node summaries, webhook trigger paths, and update hints:

curl "$DOLPHINFLOW_API_URL/workflows/<workflow-id>/agent" \
  -H "Authorization: Bearer $DOLPHINFLOW_API_KEY"

Create workflows with the existing graph endpoint:

Validate the same body first:

curl -X POST "$DOLPHINFLOW_API_URL/workflows/validate" \
  -H "Authorization: Bearer $DOLPHINFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d @workflow-draft.json

curl -X POST "$DOLPHINFLOW_API_URL/workflows" \
  -H "Authorization: Bearer $DOLPHINFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hourly Discord heartbeat",
    "description": "Runs once an hour and sends a Discord notification.",
    "graph": {
      "nodes": [
        {
          "id": "trigger-1",
          "type": "trigger",
          "position": { "x": 0, "y": 0 },
          "data": {
            "nodeType": "trigger",
            "triggerType": "cron",
            "config": { "schedule": "0 * * * *", "timezone": "UTC" }
          }
        },
        {
          "id": "notify-1",
          "type": "notify",
          "position": { "x": 320, "y": 0 },
          "data": {
            "nodeType": "notify",
            "notifications": [
              {
                "notifyType": "discord",
                "webhookUrl": "https://discord.com/api/webhooks/...",
                "template": "default"
              }
            ]
          }
        }
      ],
      "edges": [
        {
          "id": "edge-trigger-1-notify-1",
          "source": "trigger-1",
          "target": "notify-1",
          "type": "smoothstep"
        }
      ]
    }
  }'

Trigger a Webhook Workflow

Webhook triggers only run enabled workflows. If auth is enabled on the trigger, send the exact configured header value.

curl -X POST "$DOLPHINFLOW_WEBHOOK_URL" \
  -H "Authorization: Bearer $DOLPHINFLOW_WEBHOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_address": "ExampleWallet111111111111111111111111111111",
    "change_lamports": 1000000,
    "source": "agent"
  }'

Successful webhook requests return 202 with an executionId.

Suggested Agent Flow

Check /health.
Read /workflows/agent/capabilities.
Use /workflows/<workflow-id>/agent before changing an existing workflow.
Create or patch workflows through /workflows.
Use webhook triggers for safe end-to-end tests.
Keep sample keys in environment variables.
Never paste real wallet tokens, bot tokens, webhook secrets, or private keys into docs or logs.