External agents: how they learn DripPulse
This page is for customer-built agents (Claude, OpenClaw, custom LLM stacks, Zapier/Make glue, or plain backends) that call https://drippulse.io/api/v1 with an organization API key. It explains where instructions live, what people mean by sessions, and which API to use when—mirroring what the dashboard can do for enrollments.
1. Where instructions live (nothing is implicit)
Models do not automatically know DripPulse. Your agent runtime should fetch or bundle the canonical artifacts below and inject them into context (system prompt, tool descriptions, or RAG corpus).
| Artifact | Stable URL | Use |
|---|---|---|
| Agent skills pack (Markdown) | /docs/skills/drippulse-agent-skills-v1.md |
Single-file contract: auth, golden paths, workflows, CRM, errors. Version is in the filename (v1). |
| OpenAPI (machine-readable) | /docs/skills/drippulse-openapi-v1.json |
Codegen, validators, and agent tools that prefer schema-first definitions. |
| Human overview + downloads | /docs/agent-skills.html |
Explains the pattern; links skills + OpenAPI. |
| API reference (workflows & enrollments) | /docs/api-reference.html#workflow-enrollments-visibility |
Endpoint tables, payloads, and enrollment list/detail fields. |
| Event bridge | /docs/event-bridge-workflows.html |
No hosted inbound workflow URL: your server receives events, then calls DripPulse. |
Recommended bootstrap: On agent startup (or on a schedule),
GET the Markdown skills URL with Accept: text/markdown, cache the body, and treat it as the authoritative integration brief. For reproducible builds, pin the URL that includes v1 and upgrade deliberately when v2 ships.
2. “Sessions” — what customers have vs what is internal
2.1 Durable automation state (what you actually integrate)
Start here: these are the tenant API surfaces for long-running work. They are separate from browser login and from the internal LLM gateway.
- Workflow enrollment — one row per contact running a saved workflow. Create with
POST /api/v1/workflows/:workflow_id/enrollments/bulk; list and funnel withGET .../enrollments; drill in withGET .../enrollments/:id(timeline, deliveries, nurture events). - Agent executions — when you run
POST /api/v1/agents/:id/execute, useGET /api/v1/agents/:id/executions(and related status/logs endpoints) for run history.
2.2 Other meanings of “session” (not your /api/v1 contract)
| Kind | What it is | As an integrator |
|---|---|---|
| Browser / dashboard session | Cookie or token after a human logs into the web app. | Do not use for automation. Use an organization API key as Authorization: Bearer …. |
| OpenClaw gateway sessions | Internal LLM tool gateway (sessions_spawn, sessions_list, sessions_history) used inside DripPulse when a step or agent needs inference. |
Not exposed as a customer HTTP API on drippulse.io. DripPulse calls it server-side; you do not obtain gateway tokens to drive it directly. |
If your product needs a “conversation id” for your own LLM, keep that in your datastore and map it to enrollment_id or lead_ref when you call DripPulse.
3. What to use when (detailed)
| Your goal | Preferred surface | Why |
|---|---|---|
| Run a multi-step sequence per person over time (waits, scheduled email, branches), with per-contact ops visibility. | POST /api/v1/workflows/:workflow_id/enrollments/bulk + list/detail GETs |
Each contact gets an enrollment row; a background job runner advances steps on schedule; you can audit in API or UI. |
| Validate workflow logic without live email or vendor calls. | POST /api/v1/workflows/:id/test |
Fixtures + shallow merge; [test] stubs for side effects. |
| One-shot or tool-driven run, with safe retries. | Workflow-type agent: POST /api/v1/agents/:id/execute with idempotency_key |
Same workflow graph can back an agent; execution dedupes on your key. |
| CRM only — create or update leads, opportunities, activities with no timed sequence. | /api/v1/crm/... |
No enrollment required until you explicitly start a workflow. |
| Inbound lead from a form, Stripe, or partner webhook. | Your HTTPS endpoint → normalize → enrollments/bulk and/or agents/execute |
See event bridge; dedupe before bulk enroll. |
| Org-wide report, batch scoring, or cron with no per-row schedule in DripPulse. | CRM + reports endpoints, or a template agent — not enrollments by default | Enrollments are for per-contact runners, not generic batch jobs. |
4. Dashboard (GUI) vs API for enrollments
The product UI is aligned with the same backend you call from code:
- Open Workflows, select a saved workflow, then open the Enrollments tab.
- List view shows the same summary fields exposed on
GET .../enrollments(contact, current step, progress, wait time, errors). The index response also includesstep_funnelfor “how many contacts are on each step” (see API reference). - Add enrollments supports: one contact (+ optional JSON extras), bulk JSON, or picking CRM contacts / CRM leads, plus timezone and optional workflow agent binding — equivalent to
POST .../enrollments/bulk(includingagent_idwhen selected). - Drilling into one enrollment matches the intent of
GET .../enrollments/:id(timeline, deliveries, nurture events, runtime state).
5. Enrollment API behavior to code against
- 422 when
contactsis missing, empty, or contains non-objects; when the workflow is archived; or when no rows could be created — the API returnserror/message(not a silent201with zero creates). - Optional body shape
{ "enrollment": { "contacts": [ ... ] } }is accepted. - Each successful bulk creates new rows — dedupe in your bridge or delete mistaken rows with
DELETE .../enrollments/:id. - List endpoint returns up to 500 recent rows plus
totalfor the workflow.
See also: Programmatic quickstart · Workflow builder guide