Programmatic API Quickstart

Use the DripPulse HTTP API from scripts, backends, or CI. All examples use curl; any HTTP client works the same way. After each call, check status and JSON body—below are illustrative shapes; your tenant may include extra fields.

1. Authentication

You can authenticate with either:

• Organization API key (recommended for automation) — create one under Dashboard → API Keys. Keys look like adcrm_live_… (production) or adcrm_test_… (non-production).
• Session JWT — same Bearer header after you sign in through the app (OAuth or admin login).

For admin / fixture scripts only, you can obtain a JWT with:

curl -s -X POST "https://drippulse.io/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"YOUR_ADMIN_USER","password":"YOUR_ADMIN_PASS"}'

Expected (shape)

{
  "token": "eyJ...",
  "admin": {
    "id": 1,
    "username": "admin",
    "email": "admin@example.com",
    "organization_id": 1
  }
}

Next: export TOKEN=… from token (or your client’s JSON parser). Rotate passwords and never commit tokens.

2. Environment variables

export API_BASE="https://drippulse.io"
export TOKEN="adcrm_live_your_key_here"

3. Workflows

List workflows

curl -s "$API_BASE/api/v1/workflows" \
  -H "Authorization: Bearer $TOKEN"

Create a workflow

You may send a top-level JSON body or wrap fields in workflow. Minimal example:

curl -s -X POST "$API_BASE/api/v1/workflows" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API workflow",
    "description": "Created via API",
    "status": "draft",
    "steps": [
      {"type":"trigger","name":"Start","config":{"frequency":"hourly"}},
      {"type":"log","name":"Done","config":{"message":"ok","level":"info"}}
    ],
    "integrations": []
  }'

Expected

201 Created or 200 OK — body includes the new workflow id, name, and persisted steps. Save the id as WORKFLOW_ID.

Next: run a dry run with /workflows/:id/test before activating.

Step config vs top-level: Field names for each type come from GET /api/v1/workflows/step_types. Prefer nesting them under config (e.g. email: subject, body, to, integration_id; wait: duration, unit). Top-level duplicates are accepted for compatibility but are stored under config on save so the dashboard matches the API.

Test a workflow (dry run)

Optional body keys: sample_data, input, or runtime_payload (merged into the test run).

curl -s -X POST "$API_BASE/api/v1/workflows/WORKFLOW_ID/test" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sample_data":{"email":"demo@example.com"}}'

4. Agents

Deploy from a template

curl -s -X POST "$API_BASE/api/v1/agents/spawn" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lead scorer from API",
    "type": "template",
    "template_id": 123,
    "configuration": { "min_score_threshold": 0.75 }
  }'

Replace 123 with a real template id from GET /api/v1/agent_templates. Some clients nest under agent; both shapes work.

Expected

{
  "id": 456,
  "name": "Lead scorer from API",
  "status": "active",
  "template_id": 123
}

Next: call execute, inference, or score_lead on id (save as AGENT_ID).

Deploy from a workflow

curl -s -X POST "$API_BASE/api/v1/agents/spawn" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Workflow runner",
    "type": "workflow",
    "workflow_id": WORKFLOW_ID
  }'

Execute an agent

Send your payload as input or as a JSON object (reserved keys are stripped). Response includes parsed and output where applicable.

curl -s -X POST "$API_BASE/api/v1/agents/AGENT_ID/execute" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input":{"company":"Acme","industry":"SaaS"},"idempotency_key":"demo-001"}'

Expected

200 OK — JSON with output, parsed, or action fields depending on agent type. Repeating the same idempotency_key returns the stored outcome for that agent.

Next: inspect GET /api/v1/agents/AGENT_ID/executions for history.

Score a lead (canonical)

curl -s -X POST "$API_BASE/api/v1/agents/AGENT_ID/score_lead" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "lead": {"email":"buyer@acme.test","company":"Acme"},
    "idempotency_key": "evt-inbound-001"
  }'

Expected

Structured score / tier / reasoning fields per template; see recipe for a full narrative.

Template inference (structured JSON)

curl -s -X POST "$API_BASE/api/v1/agents/AGENT_ID/inference" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input":{"company":"Acme"},"required_keys":["score","reasoning"]}'

Agent metrics

curl -s "$API_BASE/api/v1/agents/AGENT_ID/metrics" \
  -H "Authorization: Bearer $TOKEN"

Includes execution counts, cost aliases, success rate, and average response time when executions have started_at / ended_at.

5. Data sources & agent batch

Sources store tabular input for batch runs (CSV uploaded to the API, or Postgres via env + query). The dashboard does not run agents on the Sources page—use AI Agents → Batch or the API below. See Sources & batch data.

Create a CSV source

curl -s -X POST "$API_BASE/api/v1/data_sources" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Webinar leads",
    "source_type": "csv_import",
    "csv_filename": "leads.csv",
    "csv_data": "company,industry\nAcme,SaaS\n",
    "config": { "default_mapping": { "fields": { "company": "company", "industry": "industry" } } }
  }'

Preview rows

curl -s -X POST "$API_BASE/api/v1/data_sources/SOURCE_ID/preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"limit": 20}'

Submit agent batch (after building items from preview)

curl -s -X POST "$API_BASE/api/v1/agents/AGENT_ID/batch_executions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "item_id": "row-1", "input": { "company": "Acme", "industry": "SaaS" } }
    ]
  }'

Poll GET .../batch_executions/:id and .../items; subscribe to agent.batch.completed webhooks.

6. Common JSON patterns

7. Next steps

• External agents guide — where to fetch skills Markdown, sessions vs enrollments, what API to call when.
• Full API reference — request/response patterns for workflows, agents, webhooks, keys.
• Production readiness — keys, retries, webhook verification.
• Sign in → Dashboard → API Keys — create a key and use it as Bearer.
• Workflow builder guide — design flows you later drive via API.
• Event bridge — receive webhooks on your server, then call enrollments/bulk or agents.
• Operator instant quickstart — built-in dashboard path without API first.
• Sources & batch data — dashboard flow for saved CSV/Postgres + agent Batch tab.

DripPulse · drippulse.io