Flows

Query SOX-compliant approval audit trail

GET/sfp/api/flows/approvals/compliance

Returns immutable approval events from sfp_approval_audit. Supports JSON (paged) and CSV (full dataset) formats for yearly compliance reports.

Authorization

access-token

AuthorizationBearer <token>

In: header

Query Parameters

status?string

Filter by approval lifecycle status

Value in

"requested"
"approved"
"rejected"
"expired"
"stale"

taskType?string

Filter by task type

environment?string

Filter by environment

repositoryIdentifier*string

Repository identifier used to scope the compliance query. Required — auditors must query one repository at a time to prevent cross-repo data exposure.

domain?string

Filter by domain

requestedBy?string

Filter by requester email

resolvedBy?string

Filter by resolver email

from?string

ISO 8601 date range start (inclusive)

to?string

ISO 8601 date range end (exclusive)

year?number

Shortcut for yearly reports — overrides from/to

limit?number

Max rows per page (JSON only, ignored for CSV)

Default100

offset?number

Offset into result set

Default0

format?string

Response format

Default"json"

Value in

"json"
"csv"

includeChangelog?boolean

Enrich release approvals with pre-computed changelog data

Defaultfalse

Register a child flow execution (internal use)

POST/sfp/api/flows/internal/register-child

Internal endpoint for Hatchet subflows to register themselves with the server.

When a parent flow spawns child flows, each child calls this endpoint on startup to create a TaskExecution record linked to its parent.

Note: This endpoint is designed for internal use and requires application token auth.

Authorization

access-token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

parentTaskExecutionId*string

Parent flow's TaskExecution ID (passed from parent flow input)

hatchetRunId?string

This child flow's Hatchet run ID

taskType*string

Task type identifier for this child flow

flowPath*string

Flow path / workflow name for this child

repositoryIdentifier*string

Repository identifier (e.g., owner/repo)

payload?

Optional payload data for this child execution

triggeredBy?string

Who triggered this flow (inherited from parent or specified)

rerunOfExecutionId?string

ID of the original execution this is a rerun of (for rerun detection)

rerunPayload?

Full domain payload for rerunning this child flow (excludes runtime/sensitive fields like applicationToken, sfpServerUrl)

`application/json`

curl -X POST "https://example.com/sfp/api/flows/internal/register-child" \  -H "Content-Type: application/json" \  -d '{    "parentTaskExecutionId": "01234567-89ab-cdef-0123-456789abcdef",    "taskType": "build-domain",    "flowPath": "build-domain",    "repositoryIdentifier": "flxbl-io/sf-core"  }'

{  "executionId": "01234567-89ab-cdef-0123-456789abcdef",  "approvalControls": {    "skipApproval": false,    "approvers": [      "release-manager@example.com"    ]  }}

Register a scheduled flow execution (internal use)

POST/sfp/api/flows/internal/register-scheduled

Internal endpoint for scheduled flows to register themselves with the server.

When a schedule triggers a flow (cron), the flow calls this endpoint on startup to create a TaskExecution record.

Note: This endpoint is designed for internal use and requires application token auth.

Authorization

access-token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

hatchetRunId*string

This flow's Hatchet run ID

taskType*string

Task type identifier for this scheduled flow

flowPath*string

Workflow name for this scheduled flow

repositoryIdentifier*string

Repository identifier (e.g., owner/repo)

schedulePath*string

Cron schedule name that triggered this flow

category?string

Category for organization/filtering

Value in

"access"
"environment"
"release"
"package"
"pool"
"testing"
"build"
"repository"
"scheduled"
"cascade"
"other"

payload?

Optional payload data for this execution

rerunOfExecutionId?string

ID of the original execution this is a rerun of (for rerun detection)

`application/json`

curl -X POST "https://example.com/sfp/api/flows/internal/register-scheduled" \  -H "Content-Type: application/json" \  -d '{    "hatchetRunId": "0193f8a9-7c53-7c71-8f0d-123456789abc",    "taskType": "monitor-pool",    "flowPath": "monitor-pool",    "repositoryIdentifier": "flxbl-io/sf-core",    "schedulePath": "pool-monitor-flxbl-io-sf-core-devpool"  }'

{  "executionId": "01234567-89ab-cdef-0123-456789abcdef"}

Update execution metadata (internal use)

PATCH/sfp/api/flows/internal/{id}/metadata

Internal endpoint for flows to store metadata on their parent task execution.

Merges the provided result object into the existing execution result without replacing it.

Note: This endpoint is designed for internal use and requires application token auth.

Authorization

access-token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

result*

Result metadata to merge into the execution record

Reconcile an orchestrator GitHub check after a child rerun (internal use)

POST/sfp/api/flows/internal/{id}/reconcile-check

Internal endpoint a rerun child flow calls when it reaches a terminal state.

Re-running a single failed child domain in isolation does NOT re-run the parent orchestrator's finalize step, so the parent's GitHub check, PR label, and persisted status stay stale. This endpoint re-derives the aggregated outcome from the parent's latest-in-lineage children — the same derivation the UI shows — and writes it back to all three. No-op when the children are not all terminal.

Note: Designed for internal use and requires application token auth.

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Parent (orchestrator) TaskExecution UUID

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

reportingExecutionId*string

Reporting child's own TaskExecution ID. Required — the server verifies it is a real latest-in-lineage child of the target parent before applying any status override.

domainName*string

Domain name the reporting child validated

status*string

Reporting child's terminal validation result

Value in

"success"
"failed"

Response Body

curl -X POST "https://example.com/sfp/api/flows/internal/string/reconcile-check" \  -H "Content-Type: application/json" \  -d '{    "reportingExecutionId": "5925f421-24dd-4337-bc5e-f625f27c7701",    "domainName": "orde-origination-lwc",    "status": "success"  }'

Empty

Render the parent PR Validation GitHub check from finalize results (internal use)

POST/sfp/api/flows/internal/{id}/render-validation-check

Internal endpoint the pr-validate finalize step calls to write the parent "PR Validation" check. The worker passes its authoritative per-domain results (including the review environment each domain validated against) and the server builds the rich check body (review-env rollup + status banner) — the same builder the isolated-rerun reconcile path uses, so the two never drift.

Writes the CHECK only; the worker still owns PR labels, persisted execution status, and the callback.

Note: Designed for internal use and requires application token auth.

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Parent (orchestrator) TaskExecution UUID

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

domainResults*array<>

Per-domain validation results from the finalize step

validationError?string

Overall validation error message, when the run failed outside an individual domain

Response Body

curl -X POST "https://example.com/sfp/api/flows/internal/string/render-validation-check" \  -H "Content-Type: application/json" \  -d '{    "domainResults": [      {        "domainName": "core",        "status": "success"      }    ]  }'

Empty

Reconcile a build-on-merge commit check after a build-domain/execute-release child rerun (internal use)

POST/sfp/api/flows/internal/{id}/reconcile-build-check

Internal endpoint a rerun build-domain or execute-release child flow calls when it reaches a terminal state.

Re-running a single child in isolation does NOT re-run the parent build-on-merge orchestrator's summarize step, so the "Build on Merge" commit check and the persisted status stay stale. This endpoint re-derives the outcome from the parent's latest-in-lineage children's stored result payloads (per-domain build results + deployment results) and writes the check + persisted status. No-op when the children are not all terminal. No PR labels — build-on-merge is a commit check.

This is the result-based counterpart to /reconcile-check (pr-validate, #1274).

Note: Designed for internal use and requires application token auth.

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Parent (build-on-merge orchestrator) TaskExecution UUID

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

reportingExecutionId?string

Reporting child's own TaskExecution ID (used to match it precisely)

domainName?string

Domain name, when the reporting child is a build-domain

environment?string

Environment name, when the reporting child is an execute-release (deploy)

status?string

Reporting child's terminal result (rich per-row status is read from the children)

Value in

"success"
"failed"

Response Body

curl -X POST "https://example.com/sfp/api/flows/internal/string/reconcile-build-check" \  -H "Content-Type: application/json" \  -d '{}'

Empty

Track a lock-to-workflow-run association (internal use)

POST/sfp/api/flows/internal/track-lock-run

Internal endpoint for Hatchet workflows to register which mutex lock they hold. Used by the lock-run-cleanup cron to release orphaned locks when a workflow is cancelled.

Note: This endpoint is designed for internal use and requires application token auth.

Authorization

access-token

AuthorizationBearer <token>

In: header

Response Body

curl -X POST "https://example.com/sfp/api/flows/internal/track-lock-run"

Empty

Mark an approval as expired (internal use)

POST/sfp/api/flows/internal/approvals/{id}/expire

Called by Hatchet workers when the approval gate's waitFor times out. Records the expiry in the audit trail immediately rather than waiting for cron cleanup.

Note: This endpoint is designed for internal use and requires application token auth.

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Task ID (Hatchet Run ID)

Response Body

curl -X POST "https://example.com/sfp/api/flows/internal/approvals/string/expire"

Empty

List recent task executions

GET/sfp/api/flows/runs

Returns a unified view of recent task executions across both flow engine and CI/CD pipelines.

Note: Scheduled (cron-triggered) runs are excluded by default. Pass includeScheduled=true to include them. Internal runs — the ones the server dispatches to serve a UI request, such as build-impact previews — are likewise excluded; pass includeInternal=true to include them.

Scoping

repositoryIdentifier is optional. When supplied, the query is scoped to that project; when omitted, it spans every project the caller can access (tenant-wide view, used by the cross-project Ops surface).

Available Filters

Filter	Required	Description	Example
`repositoryIdentifier`	No	Repository to query (omit for tenant-wide)	`acme/salesforce-app`
`executionMode`	No	Filter by execution source	`flow`, `cicd`
`category`	No	Filter by task category (comma-separated for multiple)	`access`, `environment,release`
`taskType`	No	Filter by specific task type (comma-separated for multiple)	`request-elevated-privileges`
`status`	No	Filter by run status (comma-separated for multiple)	`Failed,Cancelled`
`flowPath`	No	Filter by flow path (partial match)	`f/sfp/access/`
`triggeredBy`	No	Filter by trigger source (comma-separated for multiple)	`user@company.com`, `cron`
`includeScheduled`	No	Include scheduled (cron) runs (default: false)	`true`
`includeInternal`	No	Include internal, server-dispatched runs (default: false)	`true`
`since`	No	Filter by time (ISO 8601 or relative)	`24h`, `7d`, `2024-01-15T00:00:00Z`
`workItemKey`	No	Filter by work item key; accepts comma-separated values	`123,456` (issue/PR numbers), `abc123` (commit SHA)
`workItemType`	No	Filter by work item type	`github-issue`, `github-pr`, `github-commit`, `ado-commit`

All filters are applied at the database level, so totalCount and pagination reflect the filtered result set.

Authorization

access-token

AuthorizationBearer <token>

In: header

Query Parameters

repositoryIdentifier?string

Repository identifier to scope the query (e.g., "owner/repo" for GitHub, "org/project/repo" for Azure DevOps). Omit to list runs across every project the caller can access — used by cross-project Ops surfaces.

limit?number

Maximum number of results to return

Range1 <= value <= 100

Default50

executionMode?string

Filter by execution mode. Use "flow" for flow engine executions, "cicd" for GitHub Actions/Azure Pipelines executions.

Value in

"flow"
"cicd"

category?string

Filter by task category. Categories group related task types together. Accepts a comma-separated list for multi-value filtering (e.g., "access,release").

Value in

"access"
"environment"
"release"
"package"
"pool"
"testing"
"build"
"repository"
"scheduled"
"cascade"
"other"

taskType?string

Filter by task type identifier (e.g., "request-elevated-privileges", "build-packages"). Accepts a comma-separated list for multi-value filtering.

status?string

Filter by run status. Accepts display statuses ("Waiting", "Running", "Completed", "Partial", "Failed", "Cancelled") or raw statuses ("dispatched", "running", ...). Accepts a comma-separated list for multi-value filtering.

flowPath?string

Filter by flow path (supports partial matching)

workItemKey?string

Filter by work item key (issue number, PR number, commit SHA, or ADO work item ID). Accepts a comma-separated list for multi-value filtering.

workItemType?string

Filter by work item type to show only executions triggered by specific work item sources

Value in

"github-issue"
"github-pr"
"github-commit"
"ado-workitem"
"ado-commit"
"gitlab-commit"

since?string

Filter executions triggered since this time. Accepts ISO 8601 format (e.g., "2024-01-15T00:00:00Z") or relative time (e.g., "24h", "7d").

triggeredBy?string

Filter by who/what triggered the execution (e.g., email, "cron", "api", "app:token-name"). Accepts a comma-separated list for multi-value filtering.

includeScheduled?boolean

Include scheduled (cron-triggered) runs in the results. By default, scheduled runs are excluded.

Defaultfalse

includeInternal?boolean

Include internal runs the server dispatches to serve a UI request (e.g. build-impact previews). By default, internal runs are excluded.

Defaultfalse

page?number

Page number for pagination (1-based)

Range1 <= value

Default1

date?string

Filter runs to a specific date (YYYY-MM-DD). Returns only runs created on this date.

Response Body

`application/json`

curl -X GET "https://example.com/sfp/api/flows/runs"

{  "runs": [    {      "id": "01234567-89ab-cdef-0123-456789abcdef",      "projectIdentifier": "flxbl-io/sf-core",      "flowPath": "f/sfp/sandbox-monitoring/monitor-pool",      "status": "Running",      "success": {},      "createdAt": "string",      "startedAt": "string",      "durationMs": 0,      "triggeredBy": "string",      "taskType": "request-elevated-privileges",      "category": "access",      "executionMode": "flow",      "cicdRunUrl": "string",      "workItemRef": {        "type": "github-issue",        "key": "123",        "url": "https://github.com/owner/repo/issues/123",        "repository": "owner/repo",        "organization": "string",        "project": "string"      },      "rerunOfExecutionId": "string",      "rerunType": "rerun"    }  ],  "count": 0,  "totalCount": 0,  "page": 0}

Run a flow using the registry-based system

POST/sfp/api/flows/run

Runs a flow by looking up its definition from the registry and dispatching to the flow engine.

The payload must contain an 'id' field that identifies the flow type (e.g., 'request-elevated-privileges').

Important: Unlike CLI, file-based configuration is NOT supported. All configuration (e.g., accessConfig) must be provided inline in the payload.

Authorization

access-token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

payload*

Task payload containing the task id and parameters. Must include an "id" field.

callback?

Optional callback configuration for task completion notifications

Response Body

`application/json`

curl -X POST "https://example.com/sfp/api/flows/run" \  -H "Content-Type: application/json" \  -d '{    "payload": {      "id": "request-elevated-privileges",      "username": "user@company.com",      "targetOrg": "prod@company.com",      "accessLevel": "admin",      "durationMinutes": 60,      "accessConfig": {        "levels": {          "admin": {            "permissionSets": [              "System_Administrator"            ]          }        }      }    }  }'

{  "id": "01234567-89ab-cdef-0123-456789abcdef",  "taskType": "request-elevated-privileges",  "status": "started",  "triggeredAt": "string"}

List available flow types

GET/sfp/api/flows/types

Returns the flow types registered in the flow definition registry. Internal flow types — the ones the server dispatches to serve a UI request rather than on a user action — are excluded unless includeInternal=true is passed.

Authorization

access-token

AuthorizationBearer <token>

In: header

Query Parameters

includeInternal?boolean

Include internal, server-dispatched flow types (default: false)

Response Body

`application/json`

curl -X GET "https://example.com/sfp/api/flows/types"

{  "taskTypes": [    {      "id": "request-elevated-privileges",      "name": "Request Elevated Privileges",      "description": "string",      "category": "access",      "executionMode": "flow",      "internal": false,      "parameters": [        {          "name": "username",          "description": "The username of the user to elevate",          "type": "string",          "required": true,          "default": {},          "enum": [            "string"          ],          "properties": [            {}          ],          "items": {            "type": "string",            "description": "string",            "enum": [              "string"            ],            "properties": [              {}            ],            "items": {}          }        }      ]    }  ],  "count": 0}

Get flow types with enabled/disabled status for a project

GET/sfp/api/flows/types/status

Returns the registered flow types with their enabled/disabled state for the specified project. Internal flow types are omitted — they are dispatched by the server as part of another feature, so there is nothing for a project to enable or disable.

Authorization

access-token

AuthorizationBearer <token>

In: header

Query Parameters

repositoryIdentifier*string

Repository identifier (e.g., "owner/repo")

Response Body

`application/json`

curl -X GET "https://example.com/sfp/api/flows/types/status?repositoryIdentifier=string"

{  "flowTypes": [    {      "id": "build-on-merge",      "name": "Build on Merge",      "enabled": true    }  ],  "repositoryIdentifier": "flxbl-io/sf-core"}

Get flow type information

GET/sfp/api/flows/types/{taskTypeId}

Returns detailed information about a specific flow type including its parameters.

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

taskTypeId*string

Flow type identifier (e.g., request-elevated-privileges)

Response Body

`application/json`

curl -X GET "https://example.com/sfp/api/flows/types/string"

{  "id": "request-elevated-privileges",  "name": "Request Elevated Privileges",  "description": "string",  "category": "access",  "executionMode": "flow",  "internal": false,  "parameters": [    {      "name": "username",      "description": "The username of the user to elevate",      "type": "string",      "required": true,      "default": {},      "enum": [        "string"      ],      "properties": [        {}      ],      "items": {        "type": "string",        "description": "string",        "enum": [          "string"        ],        "properties": [          {}        ],        "items": {}      }    }  ]}

Disable a flow type for a project

POST/sfp/api/flows/types/{taskTypeId}/disable

Prevents the specified flow type from being triggered by webhooks or API calls for this project.

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

taskTypeId*string

Flow type identifier (e.g., build-on-merge)

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

repositoryIdentifier*string

Repository identifier (e.g., "owner/repo" for GitHub, "org/project/repo" for Azure DevOps)

Response Body

curl -X POST "https://example.com/sfp/api/flows/types/string/disable" \  -H "Content-Type: application/json" \  -d '{    "repositoryIdentifier": "flxbl-io/sf-core"  }'

Empty

Enable a flow type for a project

POST/sfp/api/flows/types/{taskTypeId}/enable

Re-enables the specified flow type for this project, allowing it to be triggered by webhooks or API calls.

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

taskTypeId*string

Flow type identifier (e.g., build-on-merge)

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

repositoryIdentifier*string

Repository identifier (e.g., "owner/repo" for GitHub, "org/project/repo" for Azure DevOps)

Response Body

curl -X POST "https://example.com/sfp/api/flows/types/string/enable" \  -H "Content-Type: application/json" \  -d '{    "repositoryIdentifier": "flxbl-io/sf-core"  }'

Empty

Set a flow type override for a project

POST/sfp/api/flows/types/{taskTypeId}/override

Routes the specified flow type to a different flow type for this project. For example, override "build-on-merge" to route to "build-on-merge-custom".

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

taskTypeId*string

Original flow type identifier to override (e.g., build-on-merge)

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

repositoryIdentifier*string

Repository identifier

overrideFlowTypeId*string

The flow type ID to route to instead of the original

Response Body

curl -X POST "https://example.com/sfp/api/flows/types/string/override" \  -H "Content-Type: application/json" \  -d '{    "repositoryIdentifier": "flxbl-io/sf-core",    "overrideFlowTypeId": "build-on-merge-custom"  }'

Empty

Remove a flow type override for a project

DELETE/sfp/api/flows/types/{taskTypeId}/override

Removes the override for the specified flow type, reverting to the default flow.

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

taskTypeId*string

Flow type identifier to remove override for

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

repositoryIdentifier*string

Repository identifier (e.g., "owner/repo" for GitHub, "org/project/repo" for Azure DevOps)

Response Body

curl -X DELETE "https://example.com/sfp/api/flows/types/string/override" \  -H "Content-Type: application/json" \  -d '{    "repositoryIdentifier": "flxbl-io/sf-core"  }'

Empty

Update task execution status (for CI/CD pipelines)

POST/sfp/api/flows/executions/{id}/status

Updates the status of a task execution. This endpoint is primarily used by CI/CD pipelines (GitHub Actions, Azure DevOps) to report back the status of tasks that were dispatched to them via POST /flows/run.

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Task execution ID (returned when task was dispatched)

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

status*string

New status for the execution

Value in

"running"
"completed"
"partial"
"failed"
"cancelled"

result?

Result data from the execution

cicdRunId?string

CI/CD run ID (for correlation)

cicdRunUrl?string

CI/CD run URL

Response Body

`application/json`

curl -X POST "https://example.com/sfp/api/flows/executions/string/status" \  -H "Content-Type: application/json" \  -d '{    "status": "running"  }'

{  "acknowledged": true,  "id": "string",  "status": "string"}

Create a pending approval request for a suspended flow

POST/sfp/api/flows/approvals

Authorization

access-token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

taskId*string

Job/task ID - primary identifier for the approval

engine?"hatchet"

Workflow engine (defaults to "hatchet")

Default"hatchet"

Value in

"hatchet"

hatchetRunId?string

Hatchet workflow run ID

hatchetEventKey?string

Hatchet event key to push approval result

requestedBy*string

User/system that requested the approval

context*

Context for the approval request

callback?

Optional callback configuration for notifications (GitHub, Slack, etc.)

approvers?array<string>

List of emails who can approve (defaults to all owners)

timeoutHours?number

Timeout in hours before approval expires. Defaults to project configuration, then 60.

Default60

Response Body

`application/json`

curl -X POST "https://example.com/sfp/api/flows/approvals" \  -H "Content-Type: application/json" \  -d '{    "taskId": "01234567-89ab-cdef-0123-456789abcdef",    "requestedBy": "john.doe@example.com",    "context": {}  }'

{  "id": "string",  "requestedBy": "string",  "requestedAt": "string",  "expiresAt": "string",  "timeoutHours": 0,  "approvers": [    "string"  ],  "approverMentions": [    "string"  ],  "context": {},  "status": "pending",  "resolvedBy": "string",  "resolvedAt": "string",  "parentExecution": {    "id": "string",    "taskType": "request-a-release-to-release-envs",    "status": "string",    "triggeredBy": "string",    "workItemRef": {}  }}

List all pending approval requests

GET/sfp/api/flows/approvals/pending

Authorization

access-token

AuthorizationBearer <token>

In: header

Query Parameters

repositoryIdentifier?string

Repository identifier used to scope pending requests

Response Body

curl -X GET "https://example.com/sfp/api/flows/approvals/pending"

Empty

List approved requests from the last 30 days

GET/sfp/api/flows/approvals/history

Returns repository-scoped approval history from the authoritative operational approval store.

Authorization

access-token

AuthorizationBearer <token>

In: header

Query Parameters

repositoryIdentifier*string

Repository identifier used to scope approved requests

limit?number

Maximum number of rows to return

Range1 <= value <= 100

Default50

offset?number

Number of rows to skip

Range0 <= value

Default0

Response Body

`application/json`

curl -X GET "https://example.com/sfp/api/flows/approvals/history?repositoryIdentifier=acme%2Fsalesforce-app"

{  "approvals": [    {      "id": "string",      "requestedBy": "string",      "requestedAt": "string",      "expiresAt": "string",      "timeoutHours": 0,      "approvers": [        "string"      ],      "approverMentions": [        "string"      ],      "context": {},      "status": "pending",      "resolvedBy": "string",      "resolvedAt": "string",      "parentExecution": {        "id": "string",        "taskType": "request-a-release-to-release-envs",        "status": "string",        "triggeredBy": "string",        "workItemRef": {}      }    }  ],  "totalCount": 0,  "limit": 0,  "offset": 0,  "windowDays": 30}

Get pending approval by GitHub repository and issue number

GET/sfp/api/flows/approvals/by-github/{repositoryIdentifier}/{issueNumber}

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

repositoryIdentifier*string

Repository identifier (e.g., owner/repo)

issueNumber*string

Issue or PR number

Response Body

`application/json`

curl -X GET "https://example.com/sfp/api/flows/approvals/by-github/string/string"

{  "id": "string",  "requestedBy": "string",  "requestedAt": "string",  "expiresAt": "string",  "timeoutHours": 0,  "approvers": [    "string"  ],  "approverMentions": [    "string"  ],  "context": {},  "status": "pending",  "resolvedBy": "string",  "resolvedAt": "string",  "parentExecution": {    "id": "string",    "taskType": "request-a-release-to-release-envs",    "status": "string",    "triggeredBy": "string",    "workItemRef": {}  }}

Get pending approval by Slack channel and thread timestamp

GET/sfp/api/flows/approvals/by-slack/{channel}/{threadTs}

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

channel*string

Slack channel ID

threadTs*string

Thread timestamp

Response Body

`application/json`

curl -X GET "https://example.com/sfp/api/flows/approvals/by-slack/string/string"

{  "id": "string",  "requestedBy": "string",  "requestedAt": "string",  "expiresAt": "string",  "timeoutHours": 0,  "approvers": [    "string"  ],  "approverMentions": [    "string"  ],  "context": {},  "status": "pending",  "resolvedBy": "string",  "resolvedAt": "string",  "parentExecution": {    "id": "string",    "taskType": "request-a-release-to-release-envs",    "status": "string",    "triggeredBy": "string",    "workItemRef": {}  }}

Get approval by Azure DevOps work item

GET/sfp/api/flows/approvals/by-azure-devops

Find a pending approval associated with an Azure DevOps work item callback.

Authorization

access-token

AuthorizationBearer <token>

In: header

Query Parameters

repositoryIdentifier*string

Repository identifier in format org/project/repo

workItemId*number

Work item ID

Response Body

`application/json`

curl -X GET "https://example.com/sfp/api/flows/approvals/by-azure-devops?repositoryIdentifier=flxbl-io%2Fsf-core%2Fsf-core&workItemId=123"

{  "id": "string",  "requestedBy": "string",  "requestedAt": "string",  "expiresAt": "string",  "timeoutHours": 0,  "approvers": [    "string"  ],  "approverMentions": [    "string"  ],  "context": {},  "status": "pending",  "resolvedBy": "string",  "resolvedAt": "string",  "parentExecution": {    "id": "string",    "taskType": "request-a-release-to-release-envs",    "status": "string",    "triggeredBy": "string",    "workItemRef": {}  }}

Get user email by GitHub username

GET/sfp/api/flows/users/email-by-github/{username}

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

username*string

GitHub username

Response Body

curl -X GET "https://example.com/sfp/api/flows/users/email-by-github/string"

Empty

Get approval request by execution ID

GET/sfp/api/flows/approvals/{id}

Accepts TaskExecution UUID or Hatchet Run ID.

For orchestrator flows, returns an enhanced response with approval status for each child flow.

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

id*string

ID (TaskExecution UUID or Hatchet Run ID)

Response Body

`application/json`

curl -X GET "https://example.com/sfp/api/flows/approvals/string"

{  "id": "string",  "requestedBy": "string",  "requestedAt": "string",  "expiresAt": "string",  "timeoutHours": 0,  "approvers": [    "string"  ],  "approverMentions": [    "string"  ],  "context": {},  "status": "pending",  "resolvedBy": "string",  "resolvedAt": "string",  "parentExecution": {    "id": "string",    "taskType": "request-a-release-to-release-envs",    "status": "string",    "triggeredBy": "string",    "workItemRef": {}  }}

Approve a pending approval request

POST/sfp/api/flows/approvals/{id}/approve

Accepts TaskExecution UUID or Hatchet Run ID.

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

id*string

ID (TaskExecution UUID or Hatchet Run ID)

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

approver*string

Display name or identifier of the approver

approverEmail*string

Email of the approver for authorization

Response Body

`application/json`

curl -X POST "https://example.com/sfp/api/flows/approvals/string/approve" \  -H "Content-Type: application/json" \  -d '{    "approver": "John Doe",    "approverEmail": "john.doe@example.com"  }'

{  "id": "string",  "requestedBy": "string",  "requestedAt": "string",  "expiresAt": "string",  "timeoutHours": 0,  "approvers": [    "string"  ],  "approverMentions": [    "string"  ],  "context": {},  "status": "pending",  "resolvedBy": "string",  "resolvedAt": "string",  "parentExecution": {    "id": "string",    "taskType": "request-a-release-to-release-envs",    "status": "string",    "triggeredBy": "string",    "workItemRef": {}  }}

Reject a pending approval request

POST/sfp/api/flows/approvals/{id}/reject

Accepts TaskExecution UUID or Hatchet Run ID.

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

id*string

ID (TaskExecution UUID or Hatchet Run ID)

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

rejector*string

Display name or identifier of the rejector

rejectorEmail*string

Email of the rejector for authorization

reason?string

Reason for rejection

Response Body

`application/json`

curl -X POST "https://example.com/sfp/api/flows/approvals/string/reject" \  -H "Content-Type: application/json" \  -d '{    "rejector": "Jane Smith",    "rejectorEmail": "jane.smith@example.com"  }'

{  "id": "string",  "requestedBy": "string",  "requestedAt": "string",  "expiresAt": "string",  "timeoutHours": 0,  "approvers": [    "string"  ],  "approverMentions": [    "string"  ],  "context": {},  "status": "pending",  "resolvedBy": "string",  "resolvedAt": "string",  "parentExecution": {    "id": "string",    "taskType": "request-a-release-to-release-envs",    "status": "string",    "triggeredBy": "string",    "workItemRef": {}  }}

List cron schedules

GET/sfp/api/flows/schedules

Returns Hatchet cron schedules with their current enabled/disabled state. Optionally filter by repositoryIdentifier. System schedules are hidden by default.

Authorization

access-token

AuthorizationBearer <token>

In: header

Query Parameters

repositoryIdentifier?string

Filter schedules by repository identifier

includeSystem?unknown

Include system-level schedules hidden from normal schedule management

Response Body

curl -X GET "https://example.com/sfp/api/flows/schedules"

Empty

Pause a cron schedule

POST/sfp/api/flows/schedules/{cronName}/pause

Disables a cron schedule without deleting it. The schedule can be resumed later.

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

cronName*string

The cron schedule name

Response Body

curl -X POST "https://example.com/sfp/api/flows/schedules/string/pause"

Empty

Resume a paused cron schedule

POST/sfp/api/flows/schedules/{cronName}/resume

Re-enables a previously paused cron schedule.

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

cronName*string

The cron schedule name

Response Body

curl -X POST "https://example.com/sfp/api/flows/schedules/string/resume"

Empty

Update a cron schedule expression

PATCH/sfp/api/flows/schedules/{cronName}

Updates the cron expression for an existing schedule. The schedule is recreated with the new expression while preserving its input.

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

cronName*string

The cron schedule name

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

workflowName*string

The workflow this cron belongs to

expression*string

New cron expression (standard 5-field cron syntax)

Response Body

curl -X PATCH "https://example.com/sfp/api/flows/schedules/string" \  -H "Content-Type: application/json" \  -d '{    "workflowName": "monitor-pool",    "expression": "*/15 * * * *"  }'

Empty

Get child executions for an orchestrator flow

GET/sfp/api/flows/{id}/children

Returns all child executions for an orchestrator flow with live status enrichment. Children are found via parentExecutionId relationship.

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Parent execution ID

Response Body

curl -X GET "https://example.com/sfp/api/flows/string/children"

Empty

Cancel only child executions (not the parent)

POST/sfp/api/flows/{id}/cancel-children

Cancels all running child executions without affecting the parent. Useful for failure handlers that need to clean up children while preserving the parent's error state.

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Parent execution ID

Response Body

curl -X POST "https://example.com/sfp/api/flows/string/cancel-children"

Empty

Rerun a completed/failed execution with optional payload overrides

POST/sfp/api/flows/{id}/rerun

Creates a new execution using the original payload from the specified execution. Supports both parent and child executions. For child executions, the rerun is linked to the same parent.

Optional payloadOverrides are shallow-merged into the original payload before dispatching. Task-level generic-dispatch authorization is re-applied to the authenticated caller before any rerun is dispatched.

Pass debug: true to rerun with debug logging enabled — the dispatched flow (and, for orchestrators, its child flows) run sfp at TRACE verbosity, mirroring GitHub Actions' "Re-run with debug logging". Debug is not persisted onto the execution payload, so a later rerun is normal unless debug is requested again.

Only flow-mode executions in terminal states (completed, failed, cancelled) can be rerun.

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

id*string

TaskExecution UUID to rerun

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

payloadOverrides?

Optional partial payload overrides shallow-merged into the original payload before dispatching. A key set to null is REMOVED from the merged payload instead of being written as null — the supported way to drop a value the original run recorded and fall back to whatever the flow resolves on its own (e.g. a cascade edge's configured AI-merge thresholds). Omitting a key keeps the original value.

debug?boolean

Rerun with debug logging enabled. When true, the dispatched flow (and, for orchestrators, its child flows) run sfp at TRACE verbosity (SFP_DEBUG=1) — the same behaviour as GitHub Actions' "Re-run with debug logging". Not persisted: a subsequent rerun is normal unless debug is requested again.

Defaultfalse

Response Body

`application/json`

curl -X POST "https://example.com/sfp/api/flows/string/rerun" \  -H "Content-Type: application/json" \  -d '{}'

{  "id": "string",  "taskType": "string",  "status": "string",  "triggeredAt": "string",  "rerunOfExecutionId": "string",  "restartFromStepId": "string"}

Get execution details by ID

GET/sfp/api/flows/{id}

Returns execution details for a task. Accepts TaskExecution UUID or Hatchet Run ID.

For flow executions, the response is enriched with live status from the flow engine. For orchestrator flows, the response includes aggregated status from all child flows.

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

id*string

ID (TaskExecution UUID or Hatchet Run ID)

Response Body

curl -X GET "https://example.com/sfp/api/flows/string"

Empty

Get execution logs

GET/sfp/api/flows/{id}/logs

Returns logs for a flow execution.

For orchestrator flows, returns an enhanced response with logs for each child flow.

Authorization

access-token

AuthorizationBearer <token>

In: header

curl -X GET "https://example.com/sfp/api/flows/string/logs"

Empty

Stream execution logs incrementally

GET/sfp/api/flows/{id}/logs/stream

Returns incremental log updates for a flow execution. Use for live log streaming.

Authorization

access-token

AuthorizationBearer <token>

In: header

curl -X GET "https://example.com/sfp/api/flows/string/logs/stream"

Empty

Download execution logs as a ZIP file

GET/sfp/api/flows/{id}/logs/download

Downloads all logs for a flow execution as a ZIP archive.

The archive contains:

console.log — Hatchet execution logs
{source}/{group}.log — VictoriaLogs engine logs grouped by log_source and log_group
For orchestrator flows: separate directories per child flow

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

id*string

ID (TaskExecution UUID or Hatchet Run ID)

Response Body

curl -X GET "https://example.com/sfp/api/flows/string/logs/download"

Empty

Cancel a running or suspended execution

POST/sfp/api/flows/{id}/cancel

Cancels an execution by ID. Works for both flow and CI/CD executions.

Flow executions: Cancels the run in Hatchet and rejects any pending approval
CI/CD executions: Calls the platform's API to cancel the running workflow/pipeline
Orchestrator flows: Cancels all child flows as well

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

id*string

ID (TaskExecution UUID or Hatchet Run ID)

Response Body

curl -X POST "https://example.com/sfp/api/flows/string/cancel"

Empty

200

403

201application/json

400

403

201application/json

400

403

200

403

404

201

403

404

201

403

404

201

403

404

201

403

200

403

404

Scoping

Available Filters

200application/json

403

201application/json

400

403

503

200application/json

403

200application/json

403

200application/json

403

404

200

403

404

200

403

404

200

403

404

200

403

404

200application/json

403

404

201application/json

400

403

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`