Workflow Audit API
The Workflow Audit API runs the same workflow audit you can run in the app, from your own scripts, pipelines or agents. You start an audit on a connected HubSpot portal, poll it until it finishes, then page through the results: the workflow inventory, findings, direct dependencies, enrollment paths, referenced assets and health scores. You can also save notes, finding dispositions and workflow decisions back to the audit.
If you are new to workflow audits, start with the Workflow Audit Overview. Every endpoint, parameter and response schema is in the interactive API reference.
Before You Start
Section titled “Before You Start”- An API key with the right scopes. Create one in the app under Settings → Access Tokens. Reading needs
audit:read. Starting an audit and saving a review needaudit:write. The read-only preset includesaudit:read; the operator and full-access presets include both. - A connected HubSpot portal. The portal must be connected to your organization, and its HubSpot connection must grant the
automationscope. If it doesn’t, starting an audit returns400withWORKFLOW_AUDIT_HUBSPOT_FETCH_FAILED. Reconnect the portal after granting the scope. - The base URL is
https://api.jetstack.ai. Send your key asAuthorization: Bearer jsai_…. If your organization runs on a dedicated Jetstack instance, also sendX-Instance-Idwith the value shown in Settings → Access Tokens → Connection Details. Everyone else leaves it out.
See Authentication for key management, scopes and rate limits.
The examples below assume:
export JETSTACK_API_KEY="jsai_your_api_key"Endpoints
Section titled “Endpoints”All paths are relative to https://api.jetstack.ai.
| Method | Path | Scope | What it does |
|---|---|---|---|
POST | /v1/workflow-audits | audit:write | Start an audit |
GET | /v1/workflow-audits | audit:read | List runs, newest first |
GET | /v1/workflow-audits/{runId} | audit:read | Status, progress and headline numbers |
GET | /v1/workflow-audits/{runId}/summary | audit:read | Totals, portfolio score and coverage |
GET | /v1/workflow-audits/{runId}/workflows | audit:read | The workflow inventory, paginated and searchable |
GET | /v1/workflow-audits/{runId}/workflows/{workflowId} | audit:read | One workflow in full, with a plain-language brief and its score |
GET | /v1/workflow-audits/{runId}/workflows/{workflowId}/dependencies | audit:read | Direct relationships, with evidence |
GET | /v1/workflow-audits/{runId}/workflows/{workflowId}/paths | audit:read | Upstream and downstream enrollment paths |
GET | /v1/workflow-audits/{runId}/assets | audit:read | Every referenced asset, with reader and writer counts |
GET | /v1/workflow-audits/{runId}/asset?assetKey=… | audit:read | The workflow references for one asset |
GET | /v1/workflow-audits/{runId}/findings | audit:read | Configuration findings |
GET | /v1/workflow-audits/{runId}/reviews | audit:read | Notes, finding dispositions and decisions |
PUT | /v1/workflow-audits/{runId}/reviews | audit:write | Save a note, disposition or decision |
GET | /v1/workflow-audits/{runId}/evidence?kind=… | audit:read | Bounded pages of stored evidence |
GET | /v1/workflow-audits/{runId}/result | audit:read | The full result in one response |
Use these paths exactly. A trailing slash, an unknown sub-path or an unsupported method returns 404 with REST_API_NOT_FOUND.
Run an Audit
Section titled “Run an Audit”-
Start the audit.
portalIdaccepts the HubSpot portal ID or the Jetstack portal ID fromGET /v1/portals.nameis required, up to 200 characters.scope.objectTypeslimits the audit to some HubSpot object types (up to 50, such as0-1for contacts and0-2for companies); leavescopeout to audit every supported object type.Terminal window curl -X POST https://api.jetstack.ai/v1/workflow-audits \-H "Authorization: Bearer $JETSTACK_API_KEY" \-H "Content-Type: application/json" \-H "Idempotency-Key: $(uuidgen)" \-d '{"name": "Inherited portal review","portalId": "244840437","scope": { "objectTypes": ["0-1", "0-2"] }}'The response is
202 Acceptedwith the new run:{"data": {"id": "Xk3p9QwZr2mB7nT1aLc4","name": "Inherited portal review","portalId": "244840437","portalName": "Acme Corp","status": "PROCESSING","progress": { "stage": "fetching", "percent": 0 },"createdAt": "2026-10-14T09:12:44.118Z"}}Jetstack works out the portal’s name and checks that it belongs to your organization. Organization or portal details you put in the body are ignored. The audit may use AI for naming checks and insights.
-
Poll until it finishes.
Terminal window curl https://api.jetstack.ai/v1/workflow-audits/Xk3p9QwZr2mB7nT1aLc4 \-H "Authorization: Bearer $JETSTACK_API_KEY"progress.stagemoves throughfetching,parsing,building_graph,detecting_conflicts,scoringandgenerating_insights. Stop whenstatusisCOMPLETEDorFAILED. A completed run also carriessummary: the workflow count, health score, conflict count, a healthy/warning/critical breakdown and, when the portal has been audited before, the previous score and the change.Poll every few seconds rather than in a tight loop. A failed run never turns into an empty report: every results endpoint returns
409for it. -
Read the results. Start with the summary, then page through what you need.
Terminal window curl https://api.jetstack.ai/v1/workflow-audits/Xk3p9QwZr2mB7nT1aLc4/summary \-H "Authorization: Bearer $JETSTACK_API_KEY"The summary has the workflow and finding counts, the portfolio score as it was calculated when the audit ran, and coverage: how much of the inventory was captured and whether the analysis and AI steps completed.
To find earlier runs, list them. Filter with portalId (the HubSpot portal ID) and status, and page with limit (1–100, default 25) and startAfter: pass the previous page’s lastId while hasMore is true.
curl "https://api.jetstack.ai/v1/workflow-audits?portalId=244840437&status=COMPLETED&limit=10" \ -H "Authorization: Bearer $JETSTACK_API_KEY"Page Through Results
Section titled “Page Through Results”The inventory, findings, assets, dependencies, paths and reviews all page the same way:
| Parameter | Default | Limit |
|---|---|---|
offset | 0 | Any non-negative integer |
limit | 25 | 100 |
search | none | 200 characters, case-insensitive, applied before paging |
Each page returns rows, total (after search), offset and nextOffset. Keep requesting with offset=nextOffset until nextOffset is null. A page is also capped at 512 KiB, so it can hold fewer rows than limit. Don’t treat a short page as the end; only a null nextOffset is.
Every page also carries auditRunId, capturedAt (when the audit captured the portal), schemaVersion, basis and runtimeExecutionAssessed.
curl "https://api.jetstack.ai/v1/workflow-audits/Xk3p9QwZr2mB7nT1aLc4/findings?limit=50" \ -H "Authorization: Bearer $JETSTACK_API_KEY"A few things to know about each view:
- Workflows. The list leaves out each workflow’s full definition (
snapshot) and its reference evidence (references) to stay compact.GET .../workflows/{workflowId}returns both, plus a plain-language brief and the workflow’s health score. Disabled workflows are included. - Findings. Each finding has a
type,severity, the workflows involved, evidence and a recommendation. AddworkflowIdto see only the findings that involve one workflow. A finding’sfingerprintstays the same across runs, so you can track it over time. - Assets. Every property, list, form, email, workflow, owner, team and pipeline the workflows reference, with a readable
labeland the number of distinct workflows that use, read and write it. To see the references for one asset, pass itskeytoGET .../asset?assetKey=. URL-encode the key exactly as returned. Keys include the object type, so a property with the same name on contacts and on companies stays separate. - Reviews. Add
workflowIdto see the reviews for one workflow, including dispositions of findings that involve it.
If a single item is larger than 512 KiB, the request returns 413. The item hasn’t been dropped. Read it through the workflow detail or the full result instead.
Dependencies and Enrollment Paths
Section titled “Dependencies and Enrollment Paths”GET .../workflows/{workflowId}/dependencies returns the direct relationships between one workflow and others. Each connection names its relationship and carries the evidence behind it: the workflow, the kind of reference, where it was found (surface, locator) and the action ID where one was captured. Filter with relationship:
| Relationship | Meaning |
|---|---|
explicit-enrollment | An action in one workflow enrolls records into another. This shows how they are configured, not that records are eligible or that it ran. |
potential-handoff | One workflow writes a property that another reads on the same object. Whether the same records, conditions and timing line up is not checked. |
shared-writer | Both workflows write the same property. This is not a conflict by itself. |
shared-usage | Both workflows use the same asset, with no direction between them. |
GET .../workflows/{workflowId}/paths follows explicit-enrollment links only. Filter with direction=upstream (workflows that lead into this one) or direction=downstream (workflows this one leads to). For each workflow it can reach, you get one shortest path per direction, up to 20 steps. A path with cycle: true is one example that loops back to the selected workflow, not every loop in the portal.
Both responses include coverage: workflows that are referenced but missing from the captured inventory, whether the analysis is complete, and pathsTruncated when the 20-step limit was reached. Coverage describes the captured inventory. Missing targets, custom code, webhooks and incomplete definitions stay visible as unknowns rather than being left out.
Save Reviews
Section titled “Save Reviews”Reviews let your team record what it decided about a workflow or a finding. They belong to the portal, not to one run, so they carry over to the next audit of the same portal. They never change the audit’s evidence, its scores or anything in HubSpot.
There are three kinds:
kind | entityId | Other fields |
|---|---|---|
note | A workflow id | text, required for a new note |
finding | The finding’s fingerprint | status: open, resolved or ignored. text is optional. |
decision | A workflow id | decision, decisionStatus, owner and a rationale in text (all required) |
Decisions are keep, improve, investigate or retirement-candidate. decisionStatus is proposed or agreed. It records where your team’s review stands; it doesn’t approve any change. owner is a label of up to 200 characters; send an empty string for no owner. text can be up to 8,000 characters. A decision never approves deleting a workflow.
curl -X PUT https://api.jetstack.ai/v1/workflow-audits/Xk3p9QwZr2mB7nT1aLc4/reviews \ -H "Authorization: Bearer $JETSTACK_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "kind": "decision", "entityId": "4924872395", "decision": "investigate", "owner": "Sales operations", "decisionStatus": "proposed", "text": "Check seasonal use and downstream dependencies with the owner.", "expectedVersion": 0 }'The response is the saved entry with its new version.
Versions protect concurrent edits. Send expectedVersion: 0 only when creating an entry. After that, send the last version you received. If someone else saved in between, the request returns 409 and nothing is overwritten. Read the reviews again and retry.
Only completed audits can be annotated, and only workflows and findings analysed by the current audit engine are valid targets. An unknown target returns 400.
When you read reviews, two fields tell you what has changed since a review was saved:
- A finding marked
resolvedthat shows up again in a later run comes back withreopened: trueandeffectiveStatus: "open". Your saved disposition is kept. - A decision has
needsRevalidation: truewhen the workflow’s definition in this run differs from the one that was reviewed, or can’t be compared.
Export Large Audits
Section titled “Export Large Audits”For a complete export, you have two options:
GET .../evidence?kind=…reads stored evidence one kind at a time:workflow,finding,node,edge,cluster,scoreorinsight. Pages hold up to 20 items (limit, default 20) and follow the sameoffsetandnextOffsetpattern. Any item over 64 KiB comes back as arequires-detailmarker with its size, so you know to fetch it through the workflow detail or the full result.snapshotIdidentifies the stored snapshot the page came from.GET .../resultreturns the whole report in one response: every workflow with its definition, the dependency graph, findings, health scores, the portfolio score and insights, plus the portal’s current reviews and a benchmark against other portals your organization has audited. On large portals this response is big; prefer the paginated endpoints or/evidence.
Audits from before indexed evidence was introduced return 409 with WORKFLOW_AUDIT_RESULT_NOT_FOUND from /evidence. Use /result for those.
Retries and Idempotency
Section titled “Retries and Idempotency”Send an Idempotency-Key header (a UUID is a good choice, up to 256 characters) when you start an audit. That makes a retry safe:
- The key is reserved for 24 hours and bound to the request body.
- The first response, success or error, is saved. A retry with the same key and body gets that response back with
Idempotent-Replayed: true, and no second scan starts. - Reusing the key with a different body returns
409. So does retrying while the first request is still running, or if its outcome is unknown. In that case, list your audits to see whether the run was created before you start a new one with a fresh key. - A replay still needs a key that carries
audit:write.
If you correct a mistake in the body after an error, use a new key.
Errors
Section titled “Errors”Errors are RFC 7807 problem documents sent as application/problem+json, with a stable code and a requestId. Match on code, not on the wording of detail.
{ "type": "https://api.jetstack.ai/errors/workflow-audit-run-invalid-status", "title": "Invalid Workflow Audit Status", "status": 409, "detail": "Audit results are not yet published", "instance": "/v1/workflow-audits/Xk3p9QwZr2mB7nT1aLc4/summary", "code": "WORKFLOW_AUDIT_RUN_INVALID_STATUS", "requestId": "req_7f3a9c2e"}| Status | Code | When |
|---|---|---|
400 | API_INVALID_INPUT | A missing or invalid field or query parameter, or a review target that isn’t in the audit |
400 | WORKFLOW_AUDIT_HUBSPOT_FETCH_FAILED | The portal’s HubSpot connection is missing the automation scope |
401 | AUTH_TOKEN_MISSING, AUTH_TOKEN_INVALID, API_KEY_NOT_FOUND, API_KEY_REVOKED, API_KEY_EXPIRED | The API key is missing, malformed, unknown, revoked or expired |
403 | API_KEY_INSUFFICIENT_SCOPE | The key doesn’t carry audit:read or audit:write |
403 | WORKFLOW_AUDIT_RUN_ACCESS_DENIED | The run belongs to another organization (run status and full result) |
404 | WORKFLOW_AUDIT_RUN_NOT_FOUND | No such run in your organization |
404 | PORTAL_NOT_FOUND | The portal isn’t connected to your organization |
404 | WORKFLOW_AUDIT_RESULT_NOT_FOUND | The run completed but has no stored result |
404 | API_INVALID_INPUT | The workflow or asset you asked for isn’t in this audit |
404 | REST_API_NOT_FOUND | Not a workflow audit route: wrong path, trailing slash or unsupported method |
409 | WORKFLOW_AUDIT_RUN_INVALID_STATUS | The run hasn’t completed, so results and reviews aren’t available yet |
409 | API_INVALID_INPUT | An idempotency key conflict, or a review expectedVersion that is out of date |
409 | WORKFLOW_AUDIT_RESULT_NOT_FOUND | /evidence on an older audit; use /result |
413 | API_INVALID_INPUT | A single item is over the 512 KiB page budget |
429 | API_KEY_RATE_LIMITED | Rate limit reached; wait for the seconds in Retry-After |
500 | API_INTERNAL_ERROR | Something went wrong on our side; contact support with the requestId if it persists |
What the API Doesn’t Do
Section titled “What the API Doesn’t Do”- It doesn’t change HubSpot. There is no endpoint to enable, disable, edit or delete a workflow.
- It doesn’t report execution history, verified last-run times or proof that a workflow is unused, and it doesn’t say whether a workflow is safe to retire. Use the brief, dependencies and findings to guide that conversation with the portal owner.
- Scheduling audits, PDF export and the audit chat are not available over the API.