Developer reference

Developers

Technical reference for developers who integrate with, extend, or automate Pulse from the outside. Every capability is exposed through stable HTTP, WebSocket and standard tool-calling protocols.

Who this is for

Solution integrators

You automate Pulse from your own software, scripts, backends, CI pipelines, internal platforms.

External tool authors

You expose your own services so Pulse agents can call them via the standard tool-calling protocol.

Pipeline-as-code practitioners

You define agents and pipelines as YAML, version them in Git, and deploy through the API.

Template authors

You package reusable workflows as portable JSON artefacts for other Pulse users.

Client-library authors

You build a Pulse SDK for your language of choice on top of stable HTTP and WebSocket contracts.

What you can build

Drive Pulse programmatically, deploy agents, trigger pipelines, fetch events, approve actions, all from your own code.
Define pipelines as YAML, version them in Git and apply them via the import endpoint, integrated with your CI.
Build external tools that run anywhere, in any language, callable by Pulse agents through the standard tool-calling protocol.
Author templates: package a reusable workflow as JSON and ship it to your customers or the community.
Ingest external events through HTTP webhooks with HMAC verification, mailbox polling, RSS watchers, or filesystem triggers.
Subscribe to a real-time WebSocket stream of live events, conversation deltas and agent status changes.

Quickstart

Hit the API in 30 seconds

Authenticate, then call any resource with a bearer token.

bash

1curl -X POST http://localhost:9090/api/auth/login \
2  -H "Content-Type: application/json" \
3  -d '{"username":"alice","password":"your-password"}' \
4  | jq -r '.accessToken' > /tmp/token
5
6curl http://localhost:9090/api/pulse/agents \
7  -H "Authorization: Bearer $(cat /tmp/token)" \
8  | jq '.agents[].name'

Deploy an agent from YAML

Describe your agent declaratively and POST it to the agents endpoint.

yaml

1# agent.yaml
2name: url-shortener-watcher
3engine: llm
4inputTopic: urls.inbound
5outputTopic: urls.shortened
6systemPrompt: |
7  Extract every URL from the event payload. For each one,
8  call the short_url tool. Return a JSON array of
9  { original, shortened } pairs.
10externalTools: [url-shortener.shorten]

bash

1curl -X POST http://localhost:9090/api/pulse/agents \
2  -H "Authorization: Bearer $(cat /tmp/token)" \
3  -H "Content-Type: application/json" \
4  --data-binary @<(yq -o=json agent.yaml)

Expose an external tool

Implement a small server that speaks the standard tool-calling protocol, Pulse registers it and any agent can use it.

python

1# my_tool.py, minimal external tool server
2from tool_server import Server
3
4srv = Server("my-custom-tool")
5
6@srv.tool()
7async def greet(name: str) -> str:
8    """Greet someone by name."""
9    return f"Hello, {name}!"
10
11srv.run_stdio()

API surface at a glance

Pulse exposes a unified REST surface. Default base URL is http://localhost:9090, place TLS in front for remote access.

Resource	REST prefix	Purpose
Auth	/api/auth/*	Login, refresh, 2FA, organisation switching
Agents	/api/pulse/agents/*	Deploy, start, stop and list agents
Pipelines	/api/pulse/pipelines/*	Named workflows, YAML import / export
Templates	/api/pulse/templates/*	Pre-built pipeline catalogue
Chat	/api/pulse/chat/*	Conversational interface with streaming responses
Events	/api/pulse/events/*	Event querying and SSE stream
Topics	/api/pulse/topics	Event channels metadata
Approvals	/api/pulse/approvals/*	Human-in-the-loop decision points
Backups	/api/pulse/backups/*	Snapshots and restore
License	/api/pulse/license/*	License status and activation
Consensus	/api/pulse/pvsc/*	Validator committee, dead-letter queue, ledger
Settings	/api/pulse/settings/*	Administrative configuration
Stats	/api/pulse/stats	Dashboard metrics
Public	/health, /metrics	Liveness probe and Prometheus metrics

Five SDKs, one API

Identical capabilities in Python, JavaScript/TypeScript, Go, Rust and Java. Declare the flow once with the streams DSL — Pulse compiles and runs it server-side. Your client stays thin; your laptop never becomes the bottleneck.

Same recipe in every tab: read a Kafka topic, count orders per customer in a 1-minute window, push to a Power BI live tile.

python

1from pulse_client import PulseClient, StreamBuilder, windows, aggs
2
3flow = (
4    StreamBuilder("orders-per-customer")
5    .from_topic("orders", source_engine="kafka")
6    .key_by("customer_id")
7    .window(windows.tumbling("1m"), aggregations={"orders": aggs.count()})
8    .to_connector("powerbi", {"powerbi.push.url": "<your-push-url>"})
9)
10
11with PulseClient(base_url="https://pulse.example.com", token="…") as client:
12    client.streams.deploy(flow)

Stability guarantees

REST API

Semver-stable. Breaking changes require a major version bump and a six-month deprecation notice on affected endpoints.

WebSocket events

New event types may appear at any time; existing types remain stable. Clients should ignore unknown type values.

Tool-calling protocol

Pulse tracks the upstream open standard. Non-breaking additions can land quickly; breaking changes follow upstream pace.

Template & agent schemas

Additive changes are allowed at any time; removals require a major version bump.

Deep-dive guides

Template Authoring

Package pipelines as JSON: config wizards, placeholder substitution, prerequisites, shadow templates, and publishing.

Integration Patterns

Ten end-to-end scenarios: webhooks, GitOps, ETL, external tools, provisioning, monitoring, backfill, A/B tests, multi-tenant.

30-day Enterprise Trial

Evaluate the Enterprise edition for 30 days

Unlock the remote cluster, HA and SSO. License emailed instantly — paste it into Pulse → Settings → License. No credit card.

Start free trial

Need deeper access?

Source-level contributions, air-gapped license servers and white-label integrations are handled directly by our team.