Flows | sfp server | flxbl docs

Register a child flow execution (internal use)

post

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.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

parentTaskExecutionIdstringRequired

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

Example: 01234567-89ab-cdef-0123-456789abcdef

hatchetRunIdstringOptional

This child flow's Hatchet run ID

Example: 0193f8a9-7c53-7c71-8f0d-123456789abc

taskTypestringRequired

Task type identifier for this child flow

Example: build-domain

flowPathstringRequired

Flow path / workflow name for this child

Example: build-domain

repositoryIdentifierstringRequired

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

Example: flxbl-io/sf-core

payloadobjectOptional

Optional payload data for this child execution

Example: {"domainName":"core","releaseConfig":"config/release-config-core.yaml"}

triggeredBystringOptional

Who triggered this flow (inherited from parent or specified)

Example: hatchet-child-workflow

rerunOfExecutionIdstringOptional

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

Example: 01234567-89ab-cdef-0123-456789abcdef

Responses

201

Child flow registered successfully

application/json

400

Invalid request or parent execution not found

403

Forbidden - Requires role: application

post

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

POST /sfp/api/flows/internal/register-child HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 393

{
  "parentTaskExecutionId": "01234567-89ab-cdef-0123-456789abcdef",
  "hatchetRunId": "0193f8a9-7c53-7c71-8f0d-123456789abc",
  "taskType": "build-domain",
  "flowPath": "build-domain",
  "repositoryIdentifier": "flxbl-io/sf-core",
  "payload": {
    "domainName": "core",
    "releaseConfig": "config/release-config-core.yaml"
  },
  "triggeredBy": "hatchet-child-workflow",
  "rerunOfExecutionId": "01234567-89ab-cdef-0123-456789abcdef"
}

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

Register a scheduled flow execution (internal use)

post

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.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

hatchetRunIdstringRequired

This flow's Hatchet run ID

Example: 0193f8a9-7c53-7c71-8f0d-123456789abc

taskTypestringRequired

Task type identifier for this scheduled flow

Example: monitor-pool

flowPathstringRequired

Workflow name for this scheduled flow

Example: monitor-pool

repositoryIdentifierstringRequired

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

Example: flxbl-io/sf-core

schedulePathstringRequired

Cron schedule name that triggered this flow

Example: pool-monitor-flxbl-io-sf-core-devpool

categorystring · enumOptional

Category for organization/filtering

Example: poolPossible values:

payloadobjectOptional

Optional payload data for this execution

Example: {"poolTag":"devpool","branch":"main"}

rerunOfExecutionIdstringOptional

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

Example: 01234567-89ab-cdef-0123-456789abcdef

Responses

201

Scheduled flow registered successfully

application/json

400

Invalid request

403

Forbidden - Requires role: application

post

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

POST /sfp/api/flows/internal/register-scheduled HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 330

{
  "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",
  "category": "pool",
  "payload": {
    "poolTag": "devpool",
    "branch": "main"
  },
  "rerunOfExecutionId": "01234567-89ab-cdef-0123-456789abcdef"
}

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

Update execution metadata (internal use)

patch

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.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

TaskExecution UUID

Body

resultobjectRequired

Result metadata to merge into the execution record

Example: {"checkRunId":"12345","repositoryIdentifier":"owner/repo"}

Responses

200

Metadata updated successfully

No content

403

Forbidden - Requires role: application

404

Execution not found

patch

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

PATCH /sfp/api/flows/internal/{id}/metadata HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 69

{
  "result": {
    "checkRunId": "12345",
    "repositoryIdentifier": "owner/repo"
  }
}

No content

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

post

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.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

201

Lock run tracked successfully

403

Forbidden - Requires role: application

post

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

POST /sfp/api/flows/internal/track-lock-run HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

List recent task executions

get

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

Note: Scheduled (cron-triggered) runs are excluded by default. Pass includeScheduled=true to include them.

Required Parameter

repositoryIdentifier: Scopes the query to a specific repository (e.g., owner/repo for GitHub)

Available Filters

Filter

Required

Description

Example

repositoryIdentifier

Yes

Repository to query

acme/salesforce-app

executionMode

No

Filter by execution source

flow, cicd

category

No

Filter by task category

access, environment, release

taskType

No

Filter by specific task type

request-elevated-privileges

flowPath

No

Filter by flow path (partial match)

f/sfp/access/

triggeredBy

No

Filter by trigger source

[email protected], cron

includeScheduled

No

Include scheduled (cron) 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

123 (issue/PR number), abc123 (commit SHA)

workItemType

No

Filter by work item type

github-issue, github-pr, github-commit, ado-commit

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

repositoryIdentifierstringRequired

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

Example: acme/salesforce-app

limitnumber · min: 1 · max: 100Optional

Maximum number of results to return

Default: 50Example: 50

executionModestring · enumOptional

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

Example: flowPossible values:

categorystring · enumOptional

Filter by task category. Categories group related task types together.

Example: accessPossible values:

taskTypestringOptional

Filter by task type identifier (e.g., "request-elevated-privileges", "build-packages")

Example: request-elevated-privileges

flowPathstringOptional

Filter by flow path (supports partial matching)

Example: f/sfp/sandbox-monitoring/monitor-pool

workItemKeystringOptional

Filter by work item key (issue number, PR number, commit SHA, or ADO work item ID)

Example: 123

workItemTypestring · enumOptional

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

Example: github-issuePossible values:

sincestringOptional

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

Example: 24h

triggeredBystringOptional

Filter by who/what triggered the execution (e.g., email, "cron", "api", "app:token-name")

Example: [email protected]

includeScheduledbooleanOptional

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

Default: falseExample: false

Responses

200

List of task executions

application/json

countnumberRequired

Total count of returned runs

403

Forbidden - Requires role: owner, member, application

get

/sfp/api/flows/runs

GET /sfp/api/flows/runs?repositoryIdentifier=acme%2Fsalesforce-app HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

Run a flow using the registry-based system

post

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.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

payloadobjectRequired

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

Example:

{"id":"request-elevated-privileges","username":"[email protected]","targetOrg":"[email protected]","accessLevel":"admin","durationMinutes":60,"accessConfig":{"levels":{"admin":{"permissionSets":["System_Administrator"]}}}}

Responses

201

Flow started successfully

application/json

400

Invalid payload or unknown flow type

403

Forbidden - Requires role: owner, member, application

503

Flow engine unavailable

post

/sfp/api/flows/run

POST /sfp/api/flows/run HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 531

{
  "payload": {
    "id": "request-elevated-privileges",
    "username": "[email protected]",
    "targetOrg": "[email protected]",
    "accessLevel": "admin",
    "durationMinutes": 60,
    "accessConfig": {
      "levels": {
        "admin": {
          "permissionSets": [
            "System_Administrator"
          ]
        }
      }
    }
  },
  "callback": {
    "type": "github",
    "github": {
      "repo": "acme/salesforce-app",
      "issueNumber": 123
    },
    "slack": {
      "channel": "C12345",
      "threadTs": "1234567890.123456"
    },
    "webhook": {
      "url": "https://example.com/webhook"
    },
    "azureDevOps": {
      "organizationUrl": "https://dev.azure.com/flxbl-io",
      "project": "sf-core",
      "workItemId": 123
    }
  }
}

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

List available flow types

get

Returns all flow types registered in the flow definition registry.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

List of available flow types

application/json

countnumberRequired

Number of available task types

403

Forbidden - Requires role: owner, member, application

get

/sfp/api/flows/types

GET /sfp/api/flows/types HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

Get flow types with enabled/disabled status for a project

get

Returns all registered flow types with their enabled/disabled state for the specified project.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

repositoryIdentifierstringRequired

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

Responses

200

Flow types with status

application/json

repositoryIdentifierstringRequired

Repository identifier

Example: flxbl-io/sf-core

403

Forbidden - Requires role: owner, member, application

get

/sfp/api/flows/types/status

GET /sfp/api/flows/types/status?repositoryIdentifier=text HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

Get flow type information

get

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

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

taskTypeIdstringRequired

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

Responses

200

Flow type information

application/json

idstringRequired

Task type identifier

Example: request-elevated-privileges

namestringRequired

Human-readable name

Example: Request Elevated Privileges

descriptionstringRequired

Description of what the task does

categorystring · enumRequired

Task category for grouping

Example: accessPossible values:

executionModestring · enumRequired

Execution mode - whether handled by flow system or CI/CD pipeline

Example: flowPossible values:

403

Forbidden - Requires role: owner, member, application

404

Flow type not found

get

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

GET /sfp/api/flows/types/{taskTypeId} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

Disable a flow type for a project

post

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

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

taskTypeIdstringRequired

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

Body

repositoryIdentifierstringRequired

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

Example: flxbl-io/sf-core

Responses

200

Flow type disabled

No content

403

Forbidden - Requires role: owner, application

404

Project not found

post

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

POST /sfp/api/flows/types/{taskTypeId}/disable HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 43

{
  "repositoryIdentifier": "flxbl-io/sf-core"
}

No content

Enable a flow type for a project

post

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

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

taskTypeIdstringRequired

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

Body

repositoryIdentifierstringRequired

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

Example: flxbl-io/sf-core

Responses

200

Flow type enabled

No content

403

Forbidden - Requires role: owner, application

404

Project not found

post

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

POST /sfp/api/flows/types/{taskTypeId}/enable HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 43

{
  "repositoryIdentifier": "flxbl-io/sf-core"
}

No content

Set a flow type override for a project

post

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".

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

taskTypeIdstringRequired

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

Body

repositoryIdentifierstringRequired

Repository identifier

Example: flxbl-io/sf-core

overrideFlowTypeIdstringRequired

The flow type ID to route to instead of the original

Example: build-on-merge-custom

Responses

200

Flow override set

No content

403

Forbidden - Requires role: owner, application

404

Project not found

post

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

POST /sfp/api/flows/types/{taskTypeId}/override HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 88

{
  "repositoryIdentifier": "flxbl-io/sf-core",
  "overrideFlowTypeId": "build-on-merge-custom"
}

No content

Remove a flow type override for a project

delete

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

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

taskTypeIdstringRequired

Flow type identifier to remove override for

Body

repositoryIdentifierstringRequired

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

Example: flxbl-io/sf-core

Responses

200

Flow override removed

No content

403

Forbidden - Requires role: owner, application

404

Project not found

delete

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

DELETE /sfp/api/flows/types/{taskTypeId}/override HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 43

{
  "repositoryIdentifier": "flxbl-io/sf-core"
}

No content

Update task execution status (for CI/CD pipelines)

post

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.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

Task execution ID (returned when task was dispatched)

Body

statusstring · enumRequired

New status for the execution

Possible values:

resultobjectOptional

Result data from the execution

Example: {"output":"Deployment successful","artifactUrl":"https://..."}

cicdRunIdstringOptional

CI/CD run ID (for correlation)

Example: 12345678

cicdRunUrlstringOptional

CI/CD run URL

Example: https://github.com/owner/repo/actions/runs/12345678

Responses

200

Status updated successfully

application/json

acknowledgedbooleanRequired

Whether the status update was acknowledged

idstringOptional

ID that was updated

statusstringOptional

New status

403

Forbidden - Requires role: application

404

Execution not found

post

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

POST /sfp/api/flows/executions/{id}/status HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 182

{
  "status": "running",
  "result": {
    "output": "Deployment successful",
    "artifactUrl": "https://..."
  },
  "cicdRunId": "12345678",
  "cicdRunUrl": "https://github.com/owner/repo/actions/runs/12345678"
}

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

Create a pending approval request for a suspended flow

post

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

taskIdstringRequired

Job/task ID - primary identifier for the approval

Example: 01234567-89ab-cdef-0123-456789abcdef

enginestring · enumOptional

Workflow engine (defaults to "hatchet")

Default: hatchetPossible values:

hatchetRunIdstringOptional

Hatchet workflow run ID

Example: 01234567-89ab-cdef-0123-456789abcdef

hatchetEventKeystringOptional

Hatchet event key to push approval result

Example: approval:01234567-89ab-cdef-0123-456789abcdef

requestedBystringRequired

User/system that requested the approval

Example: [email protected]

approversstring[]Optional

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

Example: ["[email protected]","[email protected]"]

timeoutHoursnumberOptional

Timeout in hours before approval expires (default: 24)

Default: 24

Responses

201

Approval request created

application/json

400

Invalid request

403

Forbidden - Requires role: owner, member, application

post

/sfp/api/flows/approvals

POST /sfp/api/flows/approvals HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 544

{
  "taskId": "01234567-89ab-cdef-0123-456789abcdef",
  "engine": "hatchet",
  "hatchetRunId": "01234567-89ab-cdef-0123-456789abcdef",
  "hatchetEventKey": "approval:01234567-89ab-cdef-0123-456789abcdef",
  "requestedBy": "[email protected]",
  "context": {
    "taskType": "text",
    "username": "text",
    "accessLevel": "text",
    "targetOrg": "text",
    "durationMinutes": 1
  },
  "callback": {
    "type": "github",
    "repositoryIdentifier": "acme/salesforce-app",
    "issueNumber": 123,
    "channel": "text",
    "threadTs": "text",
    "url": "text"
  },
  "approvers": [
    "[email protected]",
    "[email protected]"
  ],
  "timeoutHours": 24
}

{
  "id": "text",
  "requestedBy": "text",
  "requestedAt": "text",
  "expiresAt": "text",
  "approvers": [
    "text"
  ],
  "context": {},
  "status": "pending",
  "resolvedBy": "text",
  "resolvedAt": "text"
}

List all pending approval requests

get

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

List of pending approvals

No content

403

Forbidden - Requires role: owner, member, application

get

/sfp/api/flows/approvals/pending

GET /sfp/api/flows/approvals/pending HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Get pending approval by GitHub repository and issue number

get

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

repositoryIdentifierstringRequired

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

issueNumberstringRequired

Issue or PR number

Responses

200

Approval request details

application/json

idstringRequired

ID - use this for subsequent API calls (approve/reject)

requestedBystringRequired

User who requested the approval

requestedAtstringRequired

ISO 8601 timestamp of request

expiresAtstringRequired

ISO 8601 timestamp when approval expires

approversstring[]Required

List of authorized approvers

contextobjectRequired

Task context (includes callback config if present)

statusstring · enumRequired

Current status

Possible values:

resolvedBystringOptional

Who resolved the request

resolvedAtstringOptional

ISO 8601 timestamp of resolution

403

Forbidden - Requires role: owner, member, application

404

No pending approval found for this issue

get

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

GET /sfp/api/flows/approvals/by-github/{repositoryIdentifier}/{issueNumber} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "text",
  "requestedBy": "text",
  "requestedAt": "text",
  "expiresAt": "text",
  "approvers": [
    "text"
  ],
  "context": {},
  "status": "pending",
  "resolvedBy": "text",
  "resolvedAt": "text"
}

Get pending approval by Slack channel and thread timestamp

get

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

channelstringRequired

Slack channel ID

threadTsstringRequired

Thread timestamp

Responses

200

Approval request details

application/json

idstringRequired

ID - use this for subsequent API calls (approve/reject)

requestedBystringRequired

User who requested the approval

requestedAtstringRequired

ISO 8601 timestamp of request

expiresAtstringRequired

ISO 8601 timestamp when approval expires

approversstring[]Required

List of authorized approvers

contextobjectRequired

Task context (includes callback config if present)

statusstring · enumRequired

Current status

Possible values:

resolvedBystringOptional

Who resolved the request

resolvedAtstringOptional

ISO 8601 timestamp of resolution

403

Forbidden - Requires role: owner, member, application

404

No pending approval found for this thread

get

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

GET /sfp/api/flows/approvals/by-slack/{channel}/{threadTs} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "text",
  "requestedBy": "text",
  "requestedAt": "text",
  "expiresAt": "text",
  "approvers": [
    "text"
  ],
  "context": {},
  "status": "pending",
  "resolvedBy": "text",
  "resolvedAt": "text"
}

Get approval by Azure DevOps work item

get

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

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

repositoryIdentifierstringRequired

Repository identifier in format org/project/repo

Example: flxbl-io/sf-core/sf-core

workItemIdnumberRequired

Work item ID

Example: 123

Responses

200

Approval found

application/json

idstringRequired

ID - use this for subsequent API calls (approve/reject)

requestedBystringRequired

User who requested the approval

requestedAtstringRequired

ISO 8601 timestamp of request

expiresAtstringRequired

ISO 8601 timestamp when approval expires

approversstring[]Required

List of authorized approvers

contextobjectRequired

Task context (includes callback config if present)

statusstring · enumRequired

Current status

Possible values:

resolvedBystringOptional

Who resolved the request

resolvedAtstringOptional

ISO 8601 timestamp of resolution

403

Forbidden - Requires role: owner, member, application

404

No approval found for this work item

get

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

GET /sfp/api/flows/approvals/by-azure-devops?repositoryIdentifier=flxbl-io%2Fsf-core%2Fsf-core&workItemId=123 HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "text",
  "requestedBy": "text",
  "requestedAt": "text",
  "expiresAt": "text",
  "approvers": [
    "text"
  ],
  "context": {},
  "status": "pending",
  "resolvedBy": "text",
  "resolvedAt": "text"
}

Get user email by GitHub username

get

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

usernamestringRequired

GitHub username

Responses

200

User email

No content

403

Forbidden - Requires role: owner, member, application

404

User not found

get

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

GET /sfp/api/flows/users/email-by-github/{username} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Get approval request by execution ID

get

Accepts TaskExecution UUID or Hatchet Run ID.

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

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

ID (TaskExecution UUID or Hatchet Run ID)

Responses

200

Approval request details

application/json

idstringRequired

ID - use this for subsequent API calls (approve/reject)

requestedBystringRequired

User who requested the approval

requestedAtstringRequired

ISO 8601 timestamp of request

expiresAtstringRequired

ISO 8601 timestamp when approval expires

approversstring[]Required

List of authorized approvers

contextobjectRequired

Task context (includes callback config if present)

statusstring · enumRequired

Current status

Possible values:

resolvedBystringOptional

Who resolved the request

resolvedAtstringOptional

ISO 8601 timestamp of resolution

403

Forbidden - Requires role: owner, member, application

404

Approval request not found

get

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

GET /sfp/api/flows/approvals/{id} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "text",
  "requestedBy": "text",
  "requestedAt": "text",
  "expiresAt": "text",
  "approvers": [
    "text"
  ],
  "context": {},
  "status": "pending",
  "resolvedBy": "text",
  "resolvedAt": "text"
}

Approve a pending approval request

post

Accepts TaskExecution UUID or Hatchet Run ID.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

ID (TaskExecution UUID or Hatchet Run ID)

Body

approverstringRequired

Display name or identifier of the approver

Example: John Doe

approverEmailstringRequired

Email of the approver for authorization

Example: [email protected]

Responses

200

Request approved

application/json

idstringRequired

ID - use this for subsequent API calls (approve/reject)

requestedBystringRequired

User who requested the approval

requestedAtstringRequired

ISO 8601 timestamp of request

expiresAtstringRequired

ISO 8601 timestamp when approval expires

approversstring[]Required

List of authorized approvers

contextobjectRequired

Task context (includes callback config if present)

statusstring · enumRequired

Current status

Possible values:

resolvedBystringOptional

Who resolved the request

resolvedAtstringOptional

ISO 8601 timestamp of resolution

403

Forbidden - Requires role: owner, member

404

Approval request not found

post

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

POST /sfp/api/flows/approvals/{id}/approve HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 62

{
  "approver": "John Doe",
  "approverEmail": "[email protected]"
}

{
  "id": "text",
  "requestedBy": "text",
  "requestedAt": "text",
  "expiresAt": "text",
  "approvers": [
    "text"
  ],
  "context": {},
  "status": "pending",
  "resolvedBy": "text",
  "resolvedAt": "text"
}

Reject a pending approval request

post

Accepts TaskExecution UUID or Hatchet Run ID.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

ID (TaskExecution UUID or Hatchet Run ID)

Body

rejectorstringRequired

Display name or identifier of the rejector

Example: Jane Smith

rejectorEmailstringRequired

Email of the rejector for authorization

Example: [email protected]

reasonstringOptional

Reason for rejection

Example: Not authorized for production access

Responses

200

Request rejected

application/json

idstringRequired

ID - use this for subsequent API calls (approve/reject)

requestedBystringRequired

User who requested the approval

requestedAtstringRequired

ISO 8601 timestamp of request

expiresAtstringRequired

ISO 8601 timestamp when approval expires

approversstring[]Required

List of authorized approvers

contextobjectRequired

Task context (includes callback config if present)

statusstring · enumRequired

Current status

Possible values:

resolvedBystringOptional

Who resolved the request

resolvedAtstringOptional

ISO 8601 timestamp of resolution

403

Forbidden - Requires role: owner, member

404

Approval request not found

post

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

POST /sfp/api/flows/approvals/{id}/reject HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 114

{
  "rejector": "Jane Smith",
  "rejectorEmail": "[email protected]",
  "reason": "Not authorized for production access"
}

{
  "id": "text",
  "requestedBy": "text",
  "requestedAt": "text",
  "expiresAt": "text",
  "approvers": [
    "text"
  ],
  "context": {},
  "status": "pending",
  "resolvedBy": "text",
  "resolvedAt": "text"
}

Get child executions for an orchestrator flow

get

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

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

Parent execution ID

Responses

200

List of child executions

No content

403

Forbidden - Requires role: owner, member, application

404

Execution not found

get

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

GET /sfp/api/flows/{id}/children HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Cancel only child executions (not the parent)

post

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.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

Parent execution ID

Responses

200

Children cancelled

No content

403

Forbidden - Requires role: owner, member, application

404

Execution not found

post

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

POST /sfp/api/flows/{id}/cancel-children HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Rerun a completed/failed execution with the same payload

post

Creates a new execution using the original payload from the specified execution. Only flow-mode executions in terminal states (completed, failed, cancelled) can be rerun.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

TaskExecution UUID to rerun

Responses

201

New execution created

application/json

400

Execution cannot be rerun

403

Forbidden - Requires role: owner, member, application

404

Execution not found

post

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

POST /sfp/api/flows/{id}/rerun HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

Get execution details by ID

get

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.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

ID (TaskExecution UUID or Hatchet Run ID)

Responses

200

Execution details with status

No content

403

Forbidden - Requires role: owner, member, application

404

Execution not found

get

/sfp/api/flows/{id}

GET /sfp/api/flows/{id} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Get execution logs

get

Returns logs for a flow execution.

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

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

ID (TaskExecution UUID or Hatchet Run ID)

Responses

200

Execution logs

No content

400

Logs only available for flow executions

403

Forbidden - Requires role: owner, member, application

404

Execution not found

get

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

GET /sfp/api/flows/{id}/logs HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Stream execution logs incrementally

get

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

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

ID (TaskExecution UUID or Hatchet Run ID)

Query parameters

logOffsetstringOptional

Current log offset

Responses

200

Incremental log update

No content

400

Logs only available for flow executions

403

Forbidden - Requires role: owner, member, application

404

Execution not found

get

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

GET /sfp/api/flows/{id}/logs/stream HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Download execution logs as a ZIP file

get

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

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

ID (TaskExecution UUID or Hatchet Run ID)

Responses

200

ZIP file containing logs

No content

400

Logs only available for flow executions

403

Forbidden - Requires role: owner, member, application

404

Execution not found

get

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

GET /sfp/api/flows/{id}/logs/download HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Cancel a running or suspended execution

post

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

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

ID (TaskExecution UUID or Hatchet Run ID)

Responses

200

Execution cancelled

No content

400

Execution already completed

403

Forbidden - Requires role: owner, member, application

404

Execution not found

post

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

POST /sfp/api/flows/{id}/cancel HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Good afternoon

hashtagRegister a child flow execution (internal use)

hashtagRegister a scheduled flow execution (internal use)

hashtagUpdate execution metadata (internal use)

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

hashtagList recent task executions

hashtagRequired Parameter

hashtagAvailable Filters

hashtagRun a flow using the registry-based system

hashtagList available flow types

hashtagGet flow types with enabled/disabled status for a project

hashtagGet flow type information

hashtagDisable a flow type for a project

hashtagEnable a flow type for a project

hashtagSet a flow type override for a project

hashtagRemove a flow type override for a project

hashtagUpdate task execution status (for CI/CD pipelines)

hashtagCreate a pending approval request for a suspended flow

hashtagList all pending approval requests

hashtagGet pending approval by GitHub repository and issue number

hashtagGet pending approval by Slack channel and thread timestamp

hashtagGet approval by Azure DevOps work item

hashtagGet user email by GitHub username

hashtagGet approval request by execution ID

hashtagApprove a pending approval request

hashtagReject a pending approval request

hashtagGet child executions for an orchestrator flow

hashtagCancel only child executions (not the parent)

hashtagRerun a completed/failed execution with the same payload

hashtagGet execution details by ID

hashtagGet execution logs

hashtagStream execution logs incrementally

hashtagDownload execution logs as a ZIP file

hashtagCancel a running or suspended execution

Register a child flow execution (internal use)

Register a scheduled flow execution (internal use)

Update execution metadata (internal use)

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

List recent task executions

Required Parameter

Available Filters

Run a flow using the registry-based system

List available flow types

Get flow types with enabled/disabled status for a project

Get flow type information

Disable a flow type for a project

Enable a flow type for a project

Set a flow type override for a project

Remove a flow type override for a project

Update task execution status (for CI/CD pipelines)

Create a pending approval request for a suspended flow

List all pending approval requests

Get pending approval by GitHub repository and issue number

Get pending approval by Slack channel and thread timestamp

Get approval by Azure DevOps work item

Get user email by GitHub username

Get approval request by execution ID

Approve a pending approval request

Reject a pending approval request

Get child executions for an orchestrator flow

Cancel only child executions (not the parent)

Rerun a completed/failed execution with the same payload

Get execution details by ID

Get execution logs

Stream execution logs incrementally

Download execution logs as a ZIP file

Cancel a running or suspended execution