Pulse JSON API

01 · Quickstart

Discover before you write

Start with a read-write API key if the agent needs to publish. A read-only key can inspect visible data but cannot create updates, agent runs, assignments, or next steps.

BASE_URL="https://pulse.asx.wtf"
API_KEY="<your-key>"

curl -fsS "$BASE_URL/api/me/" \
  -H "Authorization: Bearer $API_KEY"

The response identifies the authenticated user and visible workspaces. Fetch each workspace to discover its visible projects, then fetch the selected project for its updates and next steps.

02 · Authentication

Bearer token or API-key header

Use one of these headers on every authenticated JSON API request:

Authorization: Bearer <your-key>
X-API-Key: <your-key>

• Keys are created in the web app at /api-keys/.
• The full key is shown only once. Store it in a secret manager or environment variable.
• Keys may be scoped to a workspace and may be read_only or read_write.
• Never put a key in an update body, source code, Git history, or an agent transcript.

03 · Discovery

Find the right workspace and project

All discovery responses are filtered to the API key's access.

WORKSPACE="product"
PROJECT="pulse"

curl -fsS "$BASE_URL/api/workspaces/$WORKSPACE/" \
  -H "Authorization: Bearer $API_KEY"

curl -fsS "$BASE_URL/api/workspaces/$WORKSPACE/projects/$PROJECT/" \
  -H "Authorization: Bearer $API_KEY"

04 · Publishing

Record a project update

Draft first, show the draft to the user, and publish only after explicit confirmation. Keep the title and body short, explain what changed and why it matters, and include next steps only when there is real follow-up work.

curl -fsS -X POST \
  "$BASE_URL/api/workspaces/$WORKSPACE/projects/$PROJECT/updates/" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "title": "Improved webhook retry handling",
    "body": "Webhook retries now handle temporary failures more reliably.",
    "kind": "progress",
    "source": "codex",
    "status_override": "",
    "next_steps": ["Verify retry behavior in staging"],
    "completed_step_ids": []
  }'

A successful write returns 201 and an update_id. Verify that ID before reporting success.

Valid status overrides are planning, active, at_risk, blocked, done, and paused. Leave it empty to preserve the current project status.

05 · Agent runs

Track and publish a run

A run can be published only once. A duplicate publish returns 409. Use the run-specific publish endpoint only when the update belongs to a tracked agent run; use the project updates endpoint for ordinary progress updates.

06 · Safety

Permissions and errors

The documentation page is public and contains no user, workspace, project, or secret data. Operational API endpoints remain authenticated and access-controlled.

07 · Codex setup

Autoconfigure an agent

A setup wizard can use this safe discovery sequence:

1. Ask the user for an API key and keep it out of the repository.
2. Call GET /api/me/ to validate the key and list workspaces.
3. Call GET /api/workspaces/<workspace>/ for each workspace to list projects.
4. Let the user choose the target workspace and project.
5. Write only non-secret settings such as the base URL, workspace slug, and project slug to AGENTS.md.
6. Store the API key as PULSE_API_KEY in the environment or a secret manager.
7. Run one authenticated read request to verify the selected project.

The current discovery API intentionally does not expose the raw API key. A future api_key or capabilities object could report access level, workspace scope, and effective project write permission without exposing the secret itself.