Skip to content
StackHeal

API and integrations

Trigger Runs. Read Outcomes. Connect Anything.

The StackHeal API is how other systems participate in automation: starting runs with typed inputs, reading run state, and subscribing to run events. Anything without a native connector joins through registered HTTP actions.

Read the API docsIntegration directory

Reference

Where to start

Four things cover most integration work.

Authentication

Bearer tokens bound to a tenant scope and a role, with narrow scopes per integration.

Docs

Triggering runs

Post a workflow identifier and its declared inputs. Invalid inputs fail immediately.

Docs

Generic HTTP action

Register a specific operation so workflows can call a system with no connector.

Docs

Outbound webhooks

Subscribe to run events and react to them in your own systems.

Docs

Example

Starting a run from your own system

Inputs are validated against the workflow's declared schema before the run is accepted, so a bad request fails at the boundary rather than part-way through execution.

curl -X POST https://api.stackheal.example/v1/runs \
  -H "Authorization: Bearer $STACKHEAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow": "wf.disk_reclaim",
    "tenant": "acme",
    "inputs": {
      "asset_id": "srv_web07",
      "ticket_ref": "10482"
    }
  }'

Keep tokens server-side

API tokens belong in a secret manager and in server-side code — never in a browser bundle, a mobile app or a repository.

Run states

queued
Accepted and waiting for an execution runner.
running
Executing steps.
awaiting_approval
Paused at an approval step. The approver and deadline are on the record.
verified
Completed and the verification assertion passed.
unverified
Completed, but the assertion did not pass. Needs a human decision.
failed
A step failed and the retry policy was exhausted.
abandoned
Stopped by policy, suppression, or an approval timeout.

Webhook events

  • run.started
  • run.awaiting_approval
  • run.approved
  • run.step_failed
  • run.verified
  • run.unverified
  • run.failed
  • run.abandoned
Triggering runs and reading status

Documentation status

What is written and what is not

The pages below are published. The full endpoint reference is still being written, and we would rather say so than publish a stub.

Building an integration now? Ask us for the current draft specification and we will send what exists.

API questions

Something not covered here? Ask our team.

Integrating StackHeal with something specific?

Tell us the system and how you want it used in a workflow. We will tell you whether it needs a connector or whether its API is enough.

Talk to our teamIntegration directory