API Reference

Pulse is scriptable today through the CLI: every command that produces data emits it as JSON, and that JSON is the same projection every page in the product reads. This page is the reference for programmatic access — what you can read, what you can write, and the rules that govern both.

Programmatic access is a read interface over the engineering graph plus a narrow write path for the same events the CLI can record. It is not a database over your record: it reads projections, exactly as every page in the product does, and it is subject to the same visibility and masking rules as a human viewer.

Programmatic access exists for the work that happens without a person at a keyboard: a dashboard that shows a team's open BLOCKs, a hiring workflow that verifies a candidate's record, a deployment system that reports what it shipped, a script that asks what changed this week.

It would be simpler to expose the event log directly, and we will not. Two constraints make that a mistake, and they are the same two that shape the rest of the platform.

The first is masking. The mask is applied when a projection is built, per viewer — so an API that read the raw graph would be an API that bypassed it, and every privacy guarantee in Pulse would have a hole in it shaped like an access token. The second is stability. Projections are versioned, disposable and rebuildable; the internal graph is free to change shape as the engines evolve. An integration built on a projection keeps working. An integration built on internal structure breaks the first time we improve something.

• Projection-backed reads — every read serves a derived read model, not the raw log.
• Mask-aware — responses are built for the caller. A token scoped to the public sees exactly what the public sees.
• Append-only writes — the write surface records events. There is no update and no delete, because there is none in the model.
• Signed webhooks — outbound delivery is signed and idempotent, so a consumer can verify origin and safely retry.
• Eventual consistency — a freshly recorded event is in the log immediately and in a projection shortly after.

Every capability below is available through the CLI today. The HTTP column is the same contract over a different transport, and it is reserved — it is listed so integrations can be designed against the resource model they will meet.

1. A caller authenticates — PULSE_TOKEN in a pipeline, a machine credential on a workstation. The token determines the viewer class.
2. Reads are served from a projection, built for that viewer with masking applied.
3. Writes append events to the log. They are verified exactly as any other event is.
4. Changes are published to the outbox, which drives projections and signed webhooks.
5. Consumers receive delivery at least once, with an idempotency key, so retries are safe.

Every integration path runs through the CLI, authenticated by PULSE_TOKEN.

1. Recording deployments from a pipeline — pulse deploy.
2. Recording events from a service — pulse event.
3. Reading a timeline in a script — pulse logs --json.
4. Checking capture and trust levels — pulse status --json.

A dashboard that shows a team's open incidents reads them like this.

pulse logs --project atlas-gateway --kind BLOCK --unresolved --json

{
  "project": "atlas-gateway",
  "events": [
    {
      "id": "evt_atlas_pool_block",
      "kind": "BLOCK",
      "title": "Connection-pool exhaustion under deploy stampede",
      "actor": "@aria",
      "occurred_at": "2026-07-03T22:04:00Z",
      "resolved": false,
      "verification": { "status": "verified", "level": "L2", "method": "github_webhook" }
    }
  ],
  "count": 1
}

• Build integrations on pulse --json rather than scraping pages. It is the same projection, and it is stable.
• Treat reads as eventually consistent. Do not write an event and immediately assert it appears in a projection.
• Scope tokens to the least a consumer needs. A dashboard that reads open BLOCKs does not need a write path.
• Assume masking applies to you. If an integration depends on seeing sealed detail, it depends on something it will not be granted.
• Design against the resource model in the table above. The CLI and the HTTP transport serve the same contract, so an integration written once does not need rewriting.

• Scraping the web UI for data that pulse logs --json already returns, cleanly and stably.
• Designing an integration that needs to edit or delete events. Nothing in Pulse allows it.
• Expecting to set a Build Cred score programmatically. It is derived; there is no write path.
• Assuming a token grants raw graph access. Every read is masked for its caller — a token is a viewer, not an exemption.
• Polling a projection immediately after a write and treating an empty result as failure. Reads are eventually consistent; the log already has it.

• --json is available wherever a command's output is data, and it is the supported integration contract.
• Webhooks are signed, at-least-once delivery with idempotency keys — consumers must be idempotent, not merely hopeful.
• Reserved capabilities are listed in the release notes. A reserved transport is not a callable one, and the table above marks which is which.
• Projections are versioned, which is what lets the contract stay stable while the engines underneath it evolve.