# Flows ## Register a child flow execution (internal use) > \ > 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.\ > ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"RegisterChildFlowDto":{"type":"object","properties":{"parentTaskExecutionId":{"type":"string","description":"Parent flow's TaskExecution ID (passed from parent flow input)"},"hatchetRunId":{"type":"string","description":"This child flow's Hatchet run ID"},"taskType":{"type":"string","description":"Task type identifier for this child flow"},"flowPath":{"type":"string","description":"Flow path / workflow name for this child"},"repositoryIdentifier":{"type":"string","description":"Repository identifier (e.g., owner/repo)"},"payload":{"type":"object","description":"Optional payload data for this child execution"},"triggeredBy":{"type":"string","description":"Who triggered this flow (inherited from parent or specified)"},"rerunOfExecutionId":{"type":"string","description":"ID of the original execution this is a rerun of (for rerun detection)"},"rerunPayload":{"type":"object","description":"Full domain payload for rerunning this child flow (excludes runtime/sensitive fields like applicationToken, sfpServerUrl)"}},"required":["parentTaskExecutionId","taskType","flowPath","repositoryIdentifier"]},"RegisterChildFlowResponseDto":{"type":"object","properties":{"executionId":{"type":"string","description":"The created TaskExecution ID for this child flow"}},"required":["executionId"]}}},"paths":{"/sfp/api/flows/internal/register-child":{"post":{"operationId":"FlowsController_registerChildFlow","summary":"Register a child flow execution (internal use)","description":"\nInternal endpoint for Hatchet subflows to register themselves with the server.\n\nWhen a parent flow spawns child flows, each child calls this endpoint on startup\nto create a TaskExecution record linked to its parent.\n\n**Note**: This endpoint is designed for internal use and requires application token auth.\n ","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterChildFlowDto"}}}},"responses":{"201":{"description":"Child flow registered successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterChildFlowResponseDto"}}}},"400":{"description":"Invalid request or parent execution not found"},"403":{"description":"Forbidden - Requires role: application"}},"tags":["Flows"]}}}} ``` ## Register a scheduled flow execution (internal use) > \ > 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.\ > ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"RegisterScheduledFlowDto":{"type":"object","properties":{"hatchetRunId":{"type":"string","description":"This flow's Hatchet run ID"},"taskType":{"type":"string","description":"Task type identifier for this scheduled flow"},"flowPath":{"type":"string","description":"Workflow name for this scheduled flow"},"repositoryIdentifier":{"type":"string","description":"Repository identifier (e.g., owner/repo)"},"schedulePath":{"type":"string","description":"Cron schedule name that triggered this flow"},"category":{"type":"string","description":"Category for organization/filtering","enum":["access","environment","release","package","pool","testing","build","repository","scheduled","cascade","other"]},"payload":{"type":"object","description":"Optional payload data for this execution"},"rerunOfExecutionId":{"type":"string","description":"ID of the original execution this is a rerun of (for rerun detection)"}},"required":["hatchetRunId","taskType","flowPath","repositoryIdentifier","schedulePath"]},"RegisterScheduledFlowResponseDto":{"type":"object","properties":{"executionId":{"type":"string","description":"The created TaskExecution ID for this scheduled flow"}},"required":["executionId"]}}},"paths":{"/sfp/api/flows/internal/register-scheduled":{"post":{"operationId":"FlowsController_registerScheduledFlow","summary":"Register a scheduled flow execution (internal use)","description":"\nInternal endpoint for scheduled flows to register themselves with the server.\n\nWhen a schedule triggers a flow (cron), the flow calls this endpoint on startup\nto create a TaskExecution record.\n\n**Note**: This endpoint is designed for internal use and requires application token auth.\n ","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterScheduledFlowDto"}}}},"responses":{"201":{"description":"Scheduled flow registered successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterScheduledFlowResponseDto"}}}},"400":{"description":"Invalid request"},"403":{"description":"Forbidden - Requires role: application"}},"tags":["Flows"]}}}} ``` ## Update execution metadata (internal use) > \ > 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.\ > ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"UpdateExecutionMetadataDto":{"type":"object","properties":{"result":{"type":"object","description":"Result metadata to merge into the execution record"}},"required":["result"]}}},"paths":{"/sfp/api/flows/internal/{id}/metadata":{"patch":{"operationId":"FlowsController_updateExecutionMetadata","summary":"Update execution metadata (internal use)","description":"\nInternal endpoint for flows to store metadata on their parent task execution.\n\nMerges the provided result object into the existing execution result without replacing it.\n\n**Note**: This endpoint is designed for internal use and requires application token auth.\n ","parameters":[{"name":"id","required":true,"in":"path","description":"TaskExecution UUID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateExecutionMetadataDto"}}}},"responses":{"200":{"description":"Metadata updated successfully"},"403":{"description":"Forbidden - Requires role: application"},"404":{"description":"Execution not found"}},"tags":["Flows"]}}}} ``` ## Track a lock-to-workflow-run association (internal use) > \ > 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.\ > ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/flows/internal/track-lock-run":{"post":{"operationId":"FlowsController_trackLockRun","summary":"Track a lock-to-workflow-run association (internal use)","description":"\nInternal endpoint for Hatchet workflows to register which mutex lock they hold.\nUsed by the lock-run-cleanup cron to release orphaned locks when a workflow is cancelled.\n\n**Note**: This endpoint is designed for internal use and requires application token auth.\n ","parameters":[],"responses":{"201":{"description":"Lock run tracked successfully"},"403":{"description":"Forbidden - Requires role: application"}},"tags":["Flows"]}}}} ``` ## List recent task executions > \ > 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 | \`\`, \`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\` |\ > ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"FlowRunsListResponseDto":{"type":"object","properties":{"runs":{"description":"List of flow runs","type":"array","items":{"$ref":"#/components/schemas/FlowRunSummaryDto"}},"count":{"type":"number","description":"Number of runs returned in this page"},"totalCount":{"type":"number","description":"Total count of matching runs across all pages"},"page":{"type":"number","description":"Current page number (1-based)"}},"required":["runs","count","totalCount","page"]},"FlowRunSummaryDto":{"type":"object","properties":{"id":{"type":"string","description":"Flow job ID"},"flowPath":{"type":"string","description":"Flow path"},"status":{"type":"string","description":"Current status of the flow","enum":["Running","Waiting","Suspended","Completed","Failed","Cancelled"]},"success":{"type":"object","description":"Whether the flow completed successfully (null if still running)","nullable":true},"createdAt":{"type":"string","description":"ISO 8601 timestamp when flow was created/triggered"},"startedAt":{"type":"string","description":"ISO 8601 timestamp when flow started executing"},"durationMs":{"type":"number","description":"Duration in milliseconds (only for completed flows)"},"triggeredBy":{"type":"string","description":"What triggered the flow (schedule path or user)"},"taskType":{"type":"string","description":"Task type identifier"},"category":{"type":"string","description":"Task category for grouping","enum":["access","environment","release","package","pool","testing","other"]},"executionMode":{"type":"string","description":"Execution mode","enum":["flow","cicd"]},"cicdRunUrl":{"type":"string","description":"CI/CD run URL (for cicd mode only)"},"workItemRef":{"description":"Work item that triggered this execution (issue, PR, or ADO work item)","allOf":[{"$ref":"#/components/schemas/WorkItemRefDto"}]},"rerunOfExecutionId":{"type":"string","description":"ID of the original execution this was rerun from"},"rerunType":{"type":"string","description":"Type of rerun","enum":["rerun","restart"]}},"required":["id","flowPath","status","success","createdAt","executionMode"]},"WorkItemRefDto":{"type":"object","properties":{"type":{"type":"string","description":"Type of work item","enum":["github-issue","github-pr","github-commit","ado-workitem","ado-commit"]},"key":{"type":"string","description":"Work item key (issue number, PR number, commit SHA, or work item ID)"},"url":{"type":"string","description":"URL to the work item"},"repository":{"type":"string","description":"Repository (for GitHub)"},"organization":{"type":"string","description":"Organization (for ADO)"},"project":{"type":"string","description":"Project (for ADO)"}},"required":["type","key"]}}},"paths":{"/sfp/api/flows/runs":{"get":{"operationId":"FlowsController_listFlowRuns","summary":"List recent task executions","description":"\nReturns a unified view of recent task executions across both flow engine and CI/CD pipelines for a specific project.\n\n**Note**: Scheduled (cron-triggered) runs are excluded by default. Pass `includeScheduled=true` to include them.\n\n## Required Parameter\n- **repositoryIdentifier**: Scopes the query to a specific repository (e.g., `owner/repo` for GitHub)\n\n## Available Filters\n| Filter | Required | Description | Example |\n|--------|----------|-------------|---------|\n| `repositoryIdentifier` | **Yes** | Repository to query | `acme/salesforce-app` |\n| `executionMode` | No | Filter by execution source | `flow`, `cicd` |\n| `category` | No | Filter by task category | `access`, `environment`, `release` |\n| `taskType` | No | Filter by specific task type | `request-elevated-privileges` |\n| `flowPath` | No | Filter by flow path (partial match) | `f/sfp/access/` |\n| `triggeredBy` | No | Filter by trigger source | `user@company.com`, `cron` |\n| `includeScheduled` | No | Include scheduled (cron) runs (default: false) | `true` |\n| `since` | No | Filter by time (ISO 8601 or relative) | `24h`, `7d`, `2024-01-15T00:00:00Z` |\n| `workItemKey` | No | Filter by work item key | `123` (issue/PR number), `abc123` (commit SHA) |\n| `workItemType` | No | Filter by work item type | `github-issue`, `github-pr`, `github-commit`, `ado-commit` |\n ","parameters":[{"name":"repositoryIdentifier","required":true,"in":"query","description":"Repository identifier to scope the query (e.g., \"owner/repo\" for GitHub, \"org/project/repo\" for Azure DevOps)","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of results to return","schema":{"minimum":1,"maximum":100,"default":50,"type":"number"}},{"name":"executionMode","required":false,"in":"query","description":"Filter by execution mode. Use \"flow\" for flow engine executions, \"cicd\" for GitHub Actions/Azure Pipelines executions.","schema":{"enum":["flow","cicd"],"type":"string"}},{"name":"category","required":false,"in":"query","description":"Filter by task category. Categories group related task types together.","schema":{"enum":["access","environment","release","package","pool","testing","build","repository","scheduled","cascade","other"],"type":"string"}},{"name":"taskType","required":false,"in":"query","description":"Filter by task type identifier (e.g., \"request-elevated-privileges\", \"build-packages\")","schema":{"type":"string"}},{"name":"flowPath","required":false,"in":"query","description":"Filter by flow path (supports partial matching)","schema":{"type":"string"}},{"name":"workItemKey","required":false,"in":"query","description":"Filter by work item key (issue number, PR number, commit SHA, or ADO work item ID)","schema":{"type":"string"}},{"name":"workItemType","required":false,"in":"query","description":"Filter by work item type to show only executions triggered by specific work item sources","schema":{"enum":["github-issue","github-pr","github-commit","ado-workitem","ado-commit"],"type":"string"}},{"name":"since","required":false,"in":"query","description":"Filter executions triggered since this time. Accepts ISO 8601 format (e.g., \"2024-01-15T00:00:00Z\") or relative time (e.g., \"24h\", \"7d\").","schema":{"type":"string"}},{"name":"triggeredBy","required":false,"in":"query","description":"Filter by who/what triggered the execution (e.g., email, \"cron\", \"api\", \"app:token-name\")","schema":{"type":"string"}},{"name":"includeScheduled","required":false,"in":"query","description":"Include scheduled (cron-triggered) runs in the results. By default, scheduled runs are excluded.","schema":{"default":false,"type":"boolean"}},{"name":"page","required":false,"in":"query","description":"Page number for pagination (1-based)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"date","required":false,"in":"query","description":"Filter runs to a specific date (YYYY-MM-DD). Returns only runs created on this date.","schema":{"type":"string"}}],"responses":{"200":{"description":"List of task executions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowRunsListResponseDto"}}}},"403":{"description":"Forbidden - Requires role: owner, member, application"}},"tags":["Flows"]}}}} ``` ## Run a flow using the registry-based system > \ > 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.\ > ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"TaskRunDto":{"type":"object","properties":{"payload":{"type":"object","description":"Task payload containing the task id and parameters. Must include an \"id\" field."},"callback":{"description":"Optional callback configuration for task completion notifications","allOf":[{"$ref":"#/components/schemas/TaskCallbackDto"}]}},"required":["payload"]},"TaskCallbackDto":{"type":"object","properties":{"type":{"type":"string","description":"Callback provider type","enum":["github","slack","webhook","azure-devops","none"]},"github":{"type":"object","description":"GitHub callback configuration"},"slack":{"type":"object","description":"Slack callback configuration"},"webhook":{"type":"object","description":"Webhook callback configuration"},"azureDevOps":{"type":"object","description":"Azure DevOps callback configuration"}},"required":["type"]},"TaskRunResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"ID - use this for subsequent API calls (status, cancel, logs)"},"taskType":{"type":"string","description":"Task type from the payload id"},"status":{"type":"string","description":"Current status"},"triggeredAt":{"type":"string","description":"ISO 8601 timestamp when task was triggered"}},"required":["id","taskType","status","triggeredAt"]}}},"paths":{"/sfp/api/flows/run":{"post":{"operationId":"FlowsController_runTask","summary":"Run a flow using the registry-based system","description":"\nRuns a flow by looking up its definition from the registry and dispatching to the flow engine.\n\nThe payload must contain an 'id' field that identifies the flow type (e.g., 'request-elevated-privileges').\n\n**Important**: Unlike CLI, file-based configuration is NOT supported.\nAll configuration (e.g., accessConfig) must be provided inline in the payload.\n ","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskRunDto"}}}},"responses":{"201":{"description":"Flow started successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskRunResponseDto"}}}},"400":{"description":"Invalid payload or unknown flow type"},"403":{"description":"Forbidden - Requires role: owner, member, application"},"503":{"description":"Flow engine unavailable"}},"tags":["Flows"]}}}} ``` ## List available flow types > Returns all flow types registered in the flow definition registry. ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"TaskTypesListResponseDto":{"type":"object","properties":{"taskTypes":{"description":"Available task types","type":"array","items":{"$ref":"#/components/schemas/TaskTypeInfoDto"}},"count":{"type":"number","description":"Number of available task types"}},"required":["taskTypes","count"]},"TaskTypeInfoDto":{"type":"object","properties":{"id":{"type":"string","description":"Task type identifier"},"name":{"type":"string","description":"Human-readable name"},"description":{"type":"string","description":"Description of what the task does"},"category":{"type":"string","description":"Task category for grouping","enum":["access","environment","release","package","pool","testing","build","repository","scheduled","cascade","other"]},"executionMode":{"type":"string","description":"Execution mode - whether handled by flow system or CI/CD pipeline","enum":["flow","cicd"]},"parameters":{"description":"Parameters required for this task type","type":"array","items":{"$ref":"#/components/schemas/TaskParameterDto"}}},"required":["id","name","description","category","executionMode"]},"TaskParameterDto":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name"},"description":{"type":"string","description":"Parameter description"},"type":{"type":"string","description":"Parameter type"},"required":{"type":"boolean","description":"Whether the parameter is required"},"default":{"type":"object","description":"Default value if not provided"}},"required":["name","description","type","required"]}}},"paths":{"/sfp/api/flows/types":{"get":{"operationId":"FlowsController_listTaskTypes","summary":"List available flow types","description":"Returns all flow types registered in the flow definition registry.","parameters":[],"responses":{"200":{"description":"List of available flow types","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskTypesListResponseDto"}}}},"403":{"description":"Forbidden - Requires role: owner, member, application"}},"tags":["Flows"]}}}} ``` ## Get flow types with enabled/disabled status for a project > Returns all registered flow types with their enabled/disabled state for the specified project. ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"FlowTypesStatusResponseDto":{"type":"object","properties":{"flowTypes":{"description":"List of flow types with their status","type":"array","items":{"$ref":"#/components/schemas/FlowTypeStatusDto"}},"repositoryIdentifier":{"type":"string","description":"Repository identifier"}},"required":["flowTypes","repositoryIdentifier"]},"FlowTypeStatusDto":{"type":"object","properties":{"id":{"type":"string","description":"Flow type identifier"},"name":{"type":"string","description":"Flow type display name"},"enabled":{"type":"boolean","description":"Whether this flow type is enabled for the project"}},"required":["id","name","enabled"]}}},"paths":{"/sfp/api/flows/types/status":{"get":{"operationId":"FlowsController_getFlowTypesStatus","summary":"Get flow types with enabled/disabled status for a project","description":"Returns all registered flow types with their enabled/disabled state for the specified project.","parameters":[{"name":"repositoryIdentifier","required":true,"in":"query","description":"Repository identifier (e.g., \"owner/repo\")","schema":{"type":"string"}}],"responses":{"200":{"description":"Flow types with status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowTypesStatusResponseDto"}}}},"403":{"description":"Forbidden - Requires role: owner, member, application"}},"tags":["Flows"]}}}} ``` ## Get flow type information > Returns detailed information about a specific flow type including its parameters. ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"TaskTypeInfoDto":{"type":"object","properties":{"id":{"type":"string","description":"Task type identifier"},"name":{"type":"string","description":"Human-readable name"},"description":{"type":"string","description":"Description of what the task does"},"category":{"type":"string","description":"Task category for grouping","enum":["access","environment","release","package","pool","testing","build","repository","scheduled","cascade","other"]},"executionMode":{"type":"string","description":"Execution mode - whether handled by flow system or CI/CD pipeline","enum":["flow","cicd"]},"parameters":{"description":"Parameters required for this task type","type":"array","items":{"$ref":"#/components/schemas/TaskParameterDto"}}},"required":["id","name","description","category","executionMode"]},"TaskParameterDto":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name"},"description":{"type":"string","description":"Parameter description"},"type":{"type":"string","description":"Parameter type"},"required":{"type":"boolean","description":"Whether the parameter is required"},"default":{"type":"object","description":"Default value if not provided"}},"required":["name","description","type","required"]}}},"paths":{"/sfp/api/flows/types/{taskTypeId}":{"get":{"operationId":"FlowsController_getTaskType","summary":"Get flow type information","description":"Returns detailed information about a specific flow type including its parameters.","parameters":[{"name":"taskTypeId","required":true,"in":"path","description":"Flow type identifier (e.g., request-elevated-privileges)","schema":{"type":"string"}}],"responses":{"200":{"description":"Flow type information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskTypeInfoDto"}}}},"403":{"description":"Forbidden - Requires role: owner, member, application"},"404":{"description":"Flow type not found"}},"tags":["Flows"]}}}} ``` ## Disable a flow type for a project > Prevents the specified flow type from being triggered by webhooks or API calls for this project. ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"FlowToggleDto":{"type":"object","properties":{"repositoryIdentifier":{"type":"string","description":"Repository identifier (e.g., \"owner/repo\" for GitHub, \"org/project/repo\" for Azure DevOps)"}},"required":["repositoryIdentifier"]}}},"paths":{"/sfp/api/flows/types/{taskTypeId}/disable":{"post":{"operationId":"FlowsController_disableFlowType","summary":"Disable a flow type for a project","description":"Prevents the specified flow type from being triggered by webhooks or API calls for this project.","parameters":[{"name":"taskTypeId","required":true,"in":"path","description":"Flow type identifier (e.g., build-on-merge)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowToggleDto"}}}},"responses":{"200":{"description":"Flow type disabled"},"403":{"description":"Forbidden - Requires role: owner, application"},"404":{"description":"Project not found"}},"tags":["Flows"]}}}} ``` ## Enable a flow type for a project > Re-enables the specified flow type for this project, allowing it to be triggered by webhooks or API calls. ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"FlowToggleDto":{"type":"object","properties":{"repositoryIdentifier":{"type":"string","description":"Repository identifier (e.g., \"owner/repo\" for GitHub, \"org/project/repo\" for Azure DevOps)"}},"required":["repositoryIdentifier"]}}},"paths":{"/sfp/api/flows/types/{taskTypeId}/enable":{"post":{"operationId":"FlowsController_enableFlowType","summary":"Enable a flow type for a project","description":"Re-enables the specified flow type for this project, allowing it to be triggered by webhooks or API calls.","parameters":[{"name":"taskTypeId","required":true,"in":"path","description":"Flow type identifier (e.g., build-on-merge)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowToggleDto"}}}},"responses":{"200":{"description":"Flow type enabled"},"403":{"description":"Forbidden - Requires role: owner, application"},"404":{"description":"Project not found"}},"tags":["Flows"]}}}} ``` ## Set a flow type override for a project > 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". ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"FlowOverrideDto":{"type":"object","properties":{"repositoryIdentifier":{"type":"string","description":"Repository identifier"},"overrideFlowTypeId":{"type":"string","description":"The flow type ID to route to instead of the original"}},"required":["repositoryIdentifier","overrideFlowTypeId"]}}},"paths":{"/sfp/api/flows/types/{taskTypeId}/override":{"post":{"operationId":"FlowsController_setFlowOverride","summary":"Set a flow type override for a project","description":"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\".","parameters":[{"name":"taskTypeId","required":true,"in":"path","description":"Original flow type identifier to override (e.g., build-on-merge)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowOverrideDto"}}}},"responses":{"200":{"description":"Flow override set"},"403":{"description":"Forbidden - Requires role: owner, application"},"404":{"description":"Project not found"}},"tags":["Flows"]}}}} ``` ## Remove a flow type override for a project > Removes the override for the specified flow type, reverting to the default flow. ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"FlowToggleDto":{"type":"object","properties":{"repositoryIdentifier":{"type":"string","description":"Repository identifier (e.g., \"owner/repo\" for GitHub, \"org/project/repo\" for Azure DevOps)"}},"required":["repositoryIdentifier"]}}},"paths":{"/sfp/api/flows/types/{taskTypeId}/override":{"delete":{"operationId":"FlowsController_removeFlowOverride","summary":"Remove a flow type override for a project","description":"Removes the override for the specified flow type, reverting to the default flow.","parameters":[{"name":"taskTypeId","required":true,"in":"path","description":"Flow type identifier to remove override for","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowToggleDto"}}}},"responses":{"200":{"description":"Flow override removed"},"403":{"description":"Forbidden - Requires role: owner, application"},"404":{"description":"Project not found"}},"tags":["Flows"]}}}} ``` ## Update task execution status (for CI/CD pipelines) > \ > 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.\ > ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"UpdateExecutionStatusDto":{"type":"object","properties":{"status":{"type":"string","description":"New status for the execution","enum":["running","completed","partial","failed","cancelled"]},"result":{"type":"object","description":"Result data from the execution"},"cicdRunId":{"type":"string","description":"CI/CD run ID (for correlation)"},"cicdRunUrl":{"type":"string","description":"CI/CD run URL"}},"required":["status"]},"ExecutionStatusResponseDto":{"type":"object","properties":{"acknowledged":{"type":"boolean","description":"Whether the status update was acknowledged"},"id":{"type":"string","description":"ID that was updated"},"status":{"type":"string","description":"New status"}},"required":["acknowledged"]}}},"paths":{"/sfp/api/flows/executions/{id}/status":{"post":{"operationId":"FlowsController_updateExecutionStatus","summary":"Update task execution status (for CI/CD pipelines)","description":"\nUpdates the status of a task execution. This endpoint is primarily used by CI/CD\npipelines (GitHub Actions, Azure DevOps) to report back the status of tasks\nthat were dispatched to them via POST /flows/run.\n ","parameters":[{"name":"id","required":true,"in":"path","description":"Task execution ID (returned when task was dispatched)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateExecutionStatusDto"}}}},"responses":{"200":{"description":"Status updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecutionStatusResponseDto"}}}},"403":{"description":"Forbidden - Requires role: application"},"404":{"description":"Execution not found"}},"tags":["Flows"]}}}} ``` ## POST /sfp/api/flows/approvals > Create a pending approval request for a suspended flow ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"CreateApprovalDto":{"type":"object","properties":{"taskId":{"type":"string","description":"Job/task ID - primary identifier for the approval"},"engine":{"type":"string","description":"Workflow engine (defaults to \"hatchet\")","enum":["hatchet"],"default":"hatchet"},"hatchetRunId":{"type":"string","description":"Hatchet workflow run ID"},"hatchetEventKey":{"type":"string","description":"Hatchet event key to push approval result"},"requestedBy":{"type":"string","description":"User/system that requested the approval"},"context":{"description":"Context for the approval request","allOf":[{"$ref":"#/components/schemas/ApprovalContextDto"}]},"callback":{"description":"Optional callback configuration for notifications (GitHub, Slack, etc.)","allOf":[{"$ref":"#/components/schemas/CallbackConfigDto"}]},"approvers":{"description":"List of emails who can approve (defaults to all owners)","type":"array","items":{"type":"string"}},"timeoutHours":{"type":"number","description":"Timeout in hours before approval expires (default: 24)","default":24}},"required":["taskId","requestedBy","context"]},"ApprovalContextDto":{"type":"object","properties":{"taskType":{"type":"string","description":"Type of task requiring approval"},"username":{"type":"string","description":"Username of the requester"},"accessLevel":{"type":"string","description":"Access level requested"},"targetOrg":{"type":"string","description":"Target Salesforce org"},"durationMinutes":{"type":"number","description":"Duration in minutes for access"}}},"CallbackConfigDto":{"type":"object","properties":{"type":{"type":"string","description":"Callback provider type","enum":["github","slack","webhook","none"]},"repositoryIdentifier":{"type":"string","description":"GitHub repository (owner/repo)"},"issueNumber":{"type":"number","description":"GitHub issue number"},"channel":{"type":"string","description":"Slack channel ID"},"threadTs":{"type":"string","description":"Slack thread timestamp"},"url":{"type":"string","description":"Webhook URL for generic callbacks"}},"required":["type"]},"PendingApprovalResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"ID - use this for subsequent API calls (approve/reject)"},"requestedBy":{"type":"string","description":"User who requested the approval"},"requestedAt":{"type":"string","description":"ISO 8601 timestamp of request"},"expiresAt":{"type":"string","description":"ISO 8601 timestamp when approval expires"},"approvers":{"description":"List of authorized approvers","type":"array","items":{"type":"string"}},"context":{"type":"object","description":"Task context (includes callback config if present)"},"status":{"type":"string","description":"Current status","enum":["pending","approved","rejected","expired","cancelled","stale"]},"resolvedBy":{"type":"string","description":"Who resolved the request"},"resolvedAt":{"type":"string","description":"ISO 8601 timestamp of resolution"},"parentExecution":{"description":"Parent orchestrator execution details (for child flows)","allOf":[{"$ref":"#/components/schemas/ParentExecutionSummaryDto"}]}},"required":["id","requestedBy","requestedAt","expiresAt","approvers","context","status"]},"ParentExecutionSummaryDto":{"type":"object","properties":{"id":{"type":"string","description":"Parent task execution ID"},"taskType":{"type":"string","description":"Task type of the parent execution"},"status":{"type":"string","description":"Current status of the parent execution"},"triggeredBy":{"type":"string","description":"Who/what triggered the parent execution"},"workItemRef":{"type":"object","description":"Work item that triggered the parent execution"}},"required":["id"]}}},"paths":{"/sfp/api/flows/approvals":{"post":{"operationId":"FlowsController_createApproval","summary":"Create a pending approval request for a suspended flow","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApprovalDto"}}}},"responses":{"201":{"description":"Approval request created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PendingApprovalResponseDto"}}}},"400":{"description":"Invalid request"},"403":{"description":"Forbidden - Requires role: owner, member, application"}},"tags":["Flows"]}}}} ``` ## GET /sfp/api/flows/approvals/pending > List all pending approval requests ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/flows/approvals/pending":{"get":{"operationId":"FlowsController_listPendingApprovals","summary":"List all pending approval requests","parameters":[],"responses":{"200":{"description":"List of pending approvals"},"403":{"description":"Forbidden - Requires role: owner, member, application"}},"tags":["Flows"]}}}} ``` ## GET /sfp/api/flows/approvals/by-github/{repositoryIdentifier}/{issueNumber} > Get pending approval by GitHub repository and issue number ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"PendingApprovalResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"ID - use this for subsequent API calls (approve/reject)"},"requestedBy":{"type":"string","description":"User who requested the approval"},"requestedAt":{"type":"string","description":"ISO 8601 timestamp of request"},"expiresAt":{"type":"string","description":"ISO 8601 timestamp when approval expires"},"approvers":{"description":"List of authorized approvers","type":"array","items":{"type":"string"}},"context":{"type":"object","description":"Task context (includes callback config if present)"},"status":{"type":"string","description":"Current status","enum":["pending","approved","rejected","expired","cancelled","stale"]},"resolvedBy":{"type":"string","description":"Who resolved the request"},"resolvedAt":{"type":"string","description":"ISO 8601 timestamp of resolution"},"parentExecution":{"description":"Parent orchestrator execution details (for child flows)","allOf":[{"$ref":"#/components/schemas/ParentExecutionSummaryDto"}]}},"required":["id","requestedBy","requestedAt","expiresAt","approvers","context","status"]},"ParentExecutionSummaryDto":{"type":"object","properties":{"id":{"type":"string","description":"Parent task execution ID"},"taskType":{"type":"string","description":"Task type of the parent execution"},"status":{"type":"string","description":"Current status of the parent execution"},"triggeredBy":{"type":"string","description":"Who/what triggered the parent execution"},"workItemRef":{"type":"object","description":"Work item that triggered the parent execution"}},"required":["id"]}}},"paths":{"/sfp/api/flows/approvals/by-github/{repositoryIdentifier}/{issueNumber}":{"get":{"operationId":"FlowsController_getApprovalByGitHubIssue","summary":"Get pending approval by GitHub repository and issue number","parameters":[{"name":"repositoryIdentifier","required":true,"in":"path","description":"Repository identifier (e.g., owner/repo)","schema":{"type":"string"}},{"name":"issueNumber","required":true,"in":"path","description":"Issue or PR number","schema":{"type":"string"}}],"responses":{"200":{"description":"Approval request details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PendingApprovalResponseDto"}}}},"403":{"description":"Forbidden - Requires role: owner, member, application"},"404":{"description":"No pending approval found for this issue"}},"tags":["Flows"]}}}} ``` ## GET /sfp/api/flows/approvals/by-slack/{channel}/{threadTs} > Get pending approval by Slack channel and thread timestamp ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"PendingApprovalResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"ID - use this for subsequent API calls (approve/reject)"},"requestedBy":{"type":"string","description":"User who requested the approval"},"requestedAt":{"type":"string","description":"ISO 8601 timestamp of request"},"expiresAt":{"type":"string","description":"ISO 8601 timestamp when approval expires"},"approvers":{"description":"List of authorized approvers","type":"array","items":{"type":"string"}},"context":{"type":"object","description":"Task context (includes callback config if present)"},"status":{"type":"string","description":"Current status","enum":["pending","approved","rejected","expired","cancelled","stale"]},"resolvedBy":{"type":"string","description":"Who resolved the request"},"resolvedAt":{"type":"string","description":"ISO 8601 timestamp of resolution"},"parentExecution":{"description":"Parent orchestrator execution details (for child flows)","allOf":[{"$ref":"#/components/schemas/ParentExecutionSummaryDto"}]}},"required":["id","requestedBy","requestedAt","expiresAt","approvers","context","status"]},"ParentExecutionSummaryDto":{"type":"object","properties":{"id":{"type":"string","description":"Parent task execution ID"},"taskType":{"type":"string","description":"Task type of the parent execution"},"status":{"type":"string","description":"Current status of the parent execution"},"triggeredBy":{"type":"string","description":"Who/what triggered the parent execution"},"workItemRef":{"type":"object","description":"Work item that triggered the parent execution"}},"required":["id"]}}},"paths":{"/sfp/api/flows/approvals/by-slack/{channel}/{threadTs}":{"get":{"operationId":"FlowsController_getApprovalBySlackThread","summary":"Get pending approval by Slack channel and thread timestamp","parameters":[{"name":"channel","required":true,"in":"path","description":"Slack channel ID","schema":{"type":"string"}},{"name":"threadTs","required":true,"in":"path","description":"Thread timestamp","schema":{"type":"string"}}],"responses":{"200":{"description":"Approval request details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PendingApprovalResponseDto"}}}},"403":{"description":"Forbidden - Requires role: owner, member, application"},"404":{"description":"No pending approval found for this thread"}},"tags":["Flows"]}}}} ``` ## Get approval by Azure DevOps work item > Find a pending approval associated with an Azure DevOps work item callback. ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"PendingApprovalResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"ID - use this for subsequent API calls (approve/reject)"},"requestedBy":{"type":"string","description":"User who requested the approval"},"requestedAt":{"type":"string","description":"ISO 8601 timestamp of request"},"expiresAt":{"type":"string","description":"ISO 8601 timestamp when approval expires"},"approvers":{"description":"List of authorized approvers","type":"array","items":{"type":"string"}},"context":{"type":"object","description":"Task context (includes callback config if present)"},"status":{"type":"string","description":"Current status","enum":["pending","approved","rejected","expired","cancelled","stale"]},"resolvedBy":{"type":"string","description":"Who resolved the request"},"resolvedAt":{"type":"string","description":"ISO 8601 timestamp of resolution"},"parentExecution":{"description":"Parent orchestrator execution details (for child flows)","allOf":[{"$ref":"#/components/schemas/ParentExecutionSummaryDto"}]}},"required":["id","requestedBy","requestedAt","expiresAt","approvers","context","status"]},"ParentExecutionSummaryDto":{"type":"object","properties":{"id":{"type":"string","description":"Parent task execution ID"},"taskType":{"type":"string","description":"Task type of the parent execution"},"status":{"type":"string","description":"Current status of the parent execution"},"triggeredBy":{"type":"string","description":"Who/what triggered the parent execution"},"workItemRef":{"type":"object","description":"Work item that triggered the parent execution"}},"required":["id"]}}},"paths":{"/sfp/api/flows/approvals/by-azure-devops":{"get":{"operationId":"FlowsController_getApprovalByAzureDevOps","summary":"Get approval by Azure DevOps work item","description":"Find a pending approval associated with an Azure DevOps work item callback.","parameters":[{"name":"repositoryIdentifier","required":true,"in":"query","description":"Repository identifier in format org/project/repo","schema":{"type":"string"}},{"name":"workItemId","required":true,"in":"query","description":"Work item ID","schema":{"type":"number"}}],"responses":{"200":{"description":"Approval found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PendingApprovalResponseDto"}}}},"403":{"description":"Forbidden - Requires role: owner, member, application"},"404":{"description":"No approval found for this work item"}},"tags":["Flows"]}}}} ``` ## GET /sfp/api/flows/users/email-by-github/{username} > Get user email by GitHub username ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/flows/users/email-by-github/{username}":{"get":{"operationId":"FlowsController_getEmailByGitHubUsername","summary":"Get user email by GitHub username","parameters":[{"name":"username","required":true,"in":"path","description":"GitHub username","schema":{"type":"string"}}],"responses":{"200":{"description":"User email"},"403":{"description":"Forbidden - Requires role: owner, member, application"},"404":{"description":"User not found"}},"tags":["Flows"]}}}} ``` ## Get approval request by execution ID > Accepts TaskExecution UUID or Hatchet Run ID.\ > \ > For orchestrator flows, returns an enhanced response with approval status for each child flow.\ > ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"PendingApprovalResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"ID - use this for subsequent API calls (approve/reject)"},"requestedBy":{"type":"string","description":"User who requested the approval"},"requestedAt":{"type":"string","description":"ISO 8601 timestamp of request"},"expiresAt":{"type":"string","description":"ISO 8601 timestamp when approval expires"},"approvers":{"description":"List of authorized approvers","type":"array","items":{"type":"string"}},"context":{"type":"object","description":"Task context (includes callback config if present)"},"status":{"type":"string","description":"Current status","enum":["pending","approved","rejected","expired","cancelled","stale"]},"resolvedBy":{"type":"string","description":"Who resolved the request"},"resolvedAt":{"type":"string","description":"ISO 8601 timestamp of resolution"},"parentExecution":{"description":"Parent orchestrator execution details (for child flows)","allOf":[{"$ref":"#/components/schemas/ParentExecutionSummaryDto"}]}},"required":["id","requestedBy","requestedAt","expiresAt","approvers","context","status"]},"ParentExecutionSummaryDto":{"type":"object","properties":{"id":{"type":"string","description":"Parent task execution ID"},"taskType":{"type":"string","description":"Task type of the parent execution"},"status":{"type":"string","description":"Current status of the parent execution"},"triggeredBy":{"type":"string","description":"Who/what triggered the parent execution"},"workItemRef":{"type":"object","description":"Work item that triggered the parent execution"}},"required":["id"]}}},"paths":{"/sfp/api/flows/approvals/{id}":{"get":{"operationId":"FlowsController_getApproval","summary":"Get approval request by execution ID","description":"Accepts TaskExecution UUID or Hatchet Run ID.\n\nFor orchestrator flows, returns an enhanced response with approval status for each child flow.\n ","parameters":[{"name":"id","required":true,"in":"path","description":"ID (TaskExecution UUID or Hatchet Run ID)","schema":{"type":"string"}}],"responses":{"200":{"description":"Approval request details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PendingApprovalResponseDto"}}}},"403":{"description":"Forbidden - Requires role: owner, member, application"},"404":{"description":"Approval request not found"}},"tags":["Flows"]}}}} ``` ## Approve a pending approval request > Accepts TaskExecution UUID or Hatchet Run ID. ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"ApproveRequestDto":{"type":"object","properties":{"approver":{"type":"string","description":"Display name or identifier of the approver"},"approverEmail":{"type":"string","description":"Email of the approver for authorization"}},"required":["approver","approverEmail"]},"PendingApprovalResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"ID - use this for subsequent API calls (approve/reject)"},"requestedBy":{"type":"string","description":"User who requested the approval"},"requestedAt":{"type":"string","description":"ISO 8601 timestamp of request"},"expiresAt":{"type":"string","description":"ISO 8601 timestamp when approval expires"},"approvers":{"description":"List of authorized approvers","type":"array","items":{"type":"string"}},"context":{"type":"object","description":"Task context (includes callback config if present)"},"status":{"type":"string","description":"Current status","enum":["pending","approved","rejected","expired","cancelled","stale"]},"resolvedBy":{"type":"string","description":"Who resolved the request"},"resolvedAt":{"type":"string","description":"ISO 8601 timestamp of resolution"},"parentExecution":{"description":"Parent orchestrator execution details (for child flows)","allOf":[{"$ref":"#/components/schemas/ParentExecutionSummaryDto"}]}},"required":["id","requestedBy","requestedAt","expiresAt","approvers","context","status"]},"ParentExecutionSummaryDto":{"type":"object","properties":{"id":{"type":"string","description":"Parent task execution ID"},"taskType":{"type":"string","description":"Task type of the parent execution"},"status":{"type":"string","description":"Current status of the parent execution"},"triggeredBy":{"type":"string","description":"Who/what triggered the parent execution"},"workItemRef":{"type":"object","description":"Work item that triggered the parent execution"}},"required":["id"]}}},"paths":{"/sfp/api/flows/approvals/{id}/approve":{"post":{"operationId":"FlowsController_approveRequest","summary":"Approve a pending approval request","description":"Accepts TaskExecution UUID or Hatchet Run ID.","parameters":[{"name":"id","required":true,"in":"path","description":"ID (TaskExecution UUID or Hatchet Run ID)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApproveRequestDto"}}}},"responses":{"200":{"description":"Request approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PendingApprovalResponseDto"}}}},"403":{"description":"Forbidden - Requires role: owner, member"},"404":{"description":"Approval request not found"}},"tags":["Flows"]}}}} ``` ## Reject a pending approval request > Accepts TaskExecution UUID or Hatchet Run ID. ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"RejectRequestDto":{"type":"object","properties":{"rejector":{"type":"string","description":"Display name or identifier of the rejector"},"rejectorEmail":{"type":"string","description":"Email of the rejector for authorization"},"reason":{"type":"string","description":"Reason for rejection"}},"required":["rejector","rejectorEmail"]},"PendingApprovalResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"ID - use this for subsequent API calls (approve/reject)"},"requestedBy":{"type":"string","description":"User who requested the approval"},"requestedAt":{"type":"string","description":"ISO 8601 timestamp of request"},"expiresAt":{"type":"string","description":"ISO 8601 timestamp when approval expires"},"approvers":{"description":"List of authorized approvers","type":"array","items":{"type":"string"}},"context":{"type":"object","description":"Task context (includes callback config if present)"},"status":{"type":"string","description":"Current status","enum":["pending","approved","rejected","expired","cancelled","stale"]},"resolvedBy":{"type":"string","description":"Who resolved the request"},"resolvedAt":{"type":"string","description":"ISO 8601 timestamp of resolution"},"parentExecution":{"description":"Parent orchestrator execution details (for child flows)","allOf":[{"$ref":"#/components/schemas/ParentExecutionSummaryDto"}]}},"required":["id","requestedBy","requestedAt","expiresAt","approvers","context","status"]},"ParentExecutionSummaryDto":{"type":"object","properties":{"id":{"type":"string","description":"Parent task execution ID"},"taskType":{"type":"string","description":"Task type of the parent execution"},"status":{"type":"string","description":"Current status of the parent execution"},"triggeredBy":{"type":"string","description":"Who/what triggered the parent execution"},"workItemRef":{"type":"object","description":"Work item that triggered the parent execution"}},"required":["id"]}}},"paths":{"/sfp/api/flows/approvals/{id}/reject":{"post":{"operationId":"FlowsController_rejectRequest","summary":"Reject a pending approval request","description":"Accepts TaskExecution UUID or Hatchet Run ID.","parameters":[{"name":"id","required":true,"in":"path","description":"ID (TaskExecution UUID or Hatchet Run ID)","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RejectRequestDto"}}}},"responses":{"200":{"description":"Request rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PendingApprovalResponseDto"}}}},"403":{"description":"Forbidden - Requires role: owner, member"},"404":{"description":"Approval request not found"}},"tags":["Flows"]}}}} ``` ## List cron schedules > Returns Hatchet cron schedules with their current enabled/disabled state. Optionally filter by repositoryIdentifier. ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/flows/schedules":{"get":{"operationId":"FlowsController_listSchedules","summary":"List cron schedules","description":"Returns Hatchet cron schedules with their current enabled/disabled state. Optionally filter by repositoryIdentifier.","parameters":[{"name":"repositoryIdentifier","required":false,"in":"query","description":"Filter schedules by repository identifier","schema":{"type":"string"}}],"responses":{"200":{"description":"List of cron schedules"},"403":{"description":"Forbidden - Requires role: owner, member"}},"tags":["Flows"]}}}} ``` ## Pause a cron schedule > Disables a cron schedule without deleting it. The schedule can be resumed later. ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/flows/schedules/{cronName}/pause":{"post":{"operationId":"FlowsController_pauseSchedule","summary":"Pause a cron schedule","description":"Disables a cron schedule without deleting it. The schedule can be resumed later.","parameters":[{"name":"cronName","required":true,"in":"path","description":"The cron schedule name","schema":{"type":"string"}}],"responses":{"200":{"description":"Cron schedule paused"},"403":{"description":"Forbidden - Requires role: owner"}},"tags":["Flows"]}}}} ``` ## Resume a paused cron schedule > Re-enables a previously paused cron schedule. ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/flows/schedules/{cronName}/resume":{"post":{"operationId":"FlowsController_resumeSchedule","summary":"Resume a paused cron schedule","description":"Re-enables a previously paused cron schedule.","parameters":[{"name":"cronName","required":true,"in":"path","description":"The cron schedule name","schema":{"type":"string"}}],"responses":{"200":{"description":"Cron schedule resumed"},"403":{"description":"Forbidden - Requires role: owner"}},"tags":["Flows"]}}}} ``` ## Update a cron schedule expression > Updates the cron expression for an existing schedule. The schedule is recreated with the new expression while preserving its input. ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"UpdateScheduleDto":{"type":"object","properties":{"workflowName":{"type":"string","description":"The workflow this cron belongs to"},"expression":{"type":"string","description":"New cron expression (standard 5-field cron syntax)"}},"required":["workflowName","expression"]}}},"paths":{"/sfp/api/flows/schedules/{cronName}":{"patch":{"operationId":"FlowsController_updateSchedule","summary":"Update a cron schedule expression","description":"Updates the cron expression for an existing schedule. The schedule is recreated with the new expression while preserving its input.","parameters":[{"name":"cronName","required":true,"in":"path","description":"The cron schedule name","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateScheduleDto"}}}},"responses":{"200":{"description":"Cron schedule updated"},"400":{"description":"Invalid cron expression"},"403":{"description":"Forbidden - Requires role: owner"},"404":{"description":"Cron schedule not found"}},"tags":["Flows"]}}}} ``` ## Get child executions for an orchestrator flow > \ > Returns all child executions for an orchestrator flow with live status enrichment.\ > Children are found via parentExecutionId relationship.\ > ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/flows/{id}/children":{"get":{"operationId":"FlowsController_getChildFlows","summary":"Get child executions for an orchestrator flow","description":"\nReturns all child executions for an orchestrator flow with live status enrichment.\nChildren are found via parentExecutionId relationship.\n ","parameters":[{"name":"id","required":true,"in":"path","description":"Parent execution ID","schema":{"type":"string"}}],"responses":{"200":{"description":"List of child executions"},"403":{"description":"Forbidden - Requires role: owner, member, application"},"404":{"description":"Execution not found"}},"tags":["Flows"]}}}} ``` ## Cancel only child executions (not the parent) > \ > 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.\ > ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/flows/{id}/cancel-children":{"post":{"operationId":"FlowsController_cancelChildFlows","summary":"Cancel only child executions (not the parent)","description":"\nCancels all running child executions without affecting the parent.\nUseful for failure handlers that need to clean up children while preserving\nthe parent's error state.\n ","parameters":[{"name":"id","required":true,"in":"path","description":"Parent execution ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Children cancelled"},"403":{"description":"Forbidden - Requires role: owner, member, application"},"404":{"description":"Execution not found"}},"tags":["Flows"]}}}} ``` ## Rerun a completed/failed execution with optional payload overrides > \ > 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 (e.g., \`{ "skipApproval": true }\`).\ > \ > Only flow-mode executions in terminal states (completed, failed, cancelled) can be rerun.\ > ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"RerunRequestDto":{"type":"object","properties":{"payloadOverrides":{"type":"object","description":"Optional partial payload overrides to merge into the original payload before dispatching"}}},"RerunResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"New execution ID"},"taskType":{"type":"string","description":"Task type"},"status":{"type":"string","description":"Current status"},"triggeredAt":{"type":"string","description":"ISO 8601 timestamp"},"rerunOfExecutionId":{"type":"string","description":"ID of the original execution this was rerun from"},"restartFromStepId":{"type":"string","description":"Step ID the flow was restarted from (restart only)"}},"required":["id","taskType","status","triggeredAt","rerunOfExecutionId"]}}},"paths":{"/sfp/api/flows/{id}/rerun":{"post":{"operationId":"FlowsController_rerunExecution","summary":"Rerun a completed/failed execution with optional payload overrides","description":"\nCreates a new execution using the original payload from the specified execution.\nSupports both parent and child executions. For child executions, the rerun\nis linked to the same parent.\n\nOptional `payloadOverrides` are shallow-merged into the original payload\nbefore dispatching (e.g., `{ \"skipApproval\": true }`).\n\nOnly flow-mode executions in terminal states (completed, failed, cancelled) can be rerun.\n ","parameters":[{"name":"id","required":true,"in":"path","description":"TaskExecution UUID to rerun","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RerunRequestDto"}}}},"responses":{"201":{"description":"New execution created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RerunResponseDto"}}}},"400":{"description":"Execution cannot be rerun"},"403":{"description":"Forbidden - Requires role: owner, member, application"},"404":{"description":"Execution not found"}},"tags":["Flows"]}}}} ``` ## Get execution details by 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.\ > ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/flows/{id}":{"get":{"operationId":"FlowsController_getFlow","summary":"Get execution details by ID","description":"\nReturns execution details for a task. Accepts TaskExecution UUID or Hatchet Run ID.\n\nFor flow executions, the response is enriched with live status from the flow engine.\nFor orchestrator flows, the response includes aggregated status from all child flows.\n ","parameters":[{"name":"id","required":true,"in":"path","description":"ID (TaskExecution UUID or Hatchet Run ID)","schema":{"type":"string"}}],"responses":{"200":{"description":"Execution details with status"},"403":{"description":"Forbidden - Requires role: owner, member, application"},"404":{"description":"Execution not found"}},"tags":["Flows"]}}}} ``` ## Get execution logs > Returns logs for a flow execution.\ > \ > For orchestrator flows, returns an enhanced response with logs for each child flow.\ > ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/flows/{id}/logs":{"get":{"operationId":"FlowsController_getFlowLogs","summary":"Get execution logs","description":"Returns logs for a flow execution.\n\nFor orchestrator flows, returns an enhanced response with logs for each child flow.\n ","parameters":[{"name":"id","required":true,"in":"path","description":"ID (TaskExecution UUID or Hatchet Run ID)","schema":{"type":"string"}}],"responses":{"200":{"description":"Execution logs"},"400":{"description":"Logs only available for flow executions"},"403":{"description":"Forbidden - Requires role: owner, member, application"},"404":{"description":"Execution not found"}},"tags":["Flows"]}}}} ``` ## Stream execution logs incrementally > Returns incremental log updates for a flow execution. Use for live log streaming. ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/flows/{id}/logs/stream":{"get":{"operationId":"FlowsController_getFlowLogsStream","summary":"Stream execution logs incrementally","description":"Returns incremental log updates for a flow execution. Use for live log streaming.","parameters":[{"name":"id","required":true,"in":"path","description":"ID (TaskExecution UUID or Hatchet Run ID)","schema":{"type":"string"}},{"name":"logOffset","required":false,"in":"query","description":"Current log offset","schema":{"type":"string"}}],"responses":{"200":{"description":"Incremental log update"},"400":{"description":"Logs only available for flow executions"},"403":{"description":"Forbidden - Requires role: owner, member, application"},"404":{"description":"Execution not found"}},"tags":["Flows"]}}}} ``` ## Download execution logs as a ZIP file > 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\ > ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/flows/{id}/logs/download":{"get":{"operationId":"FlowsController_downloadFlowLogs","summary":"Download execution logs as a ZIP file","description":"Downloads all logs for a flow execution as a ZIP archive.\n\nThe archive contains:\n- **console.log** — Hatchet execution logs\n- **{source}/{group}.log** — VictoriaLogs engine logs grouped by log_source and log_group\n- For orchestrator flows: separate directories per child flow\n ","parameters":[{"name":"id","required":true,"in":"path","description":"ID (TaskExecution UUID or Hatchet Run ID)","schema":{"type":"string"}}],"responses":{"200":{"description":"ZIP file containing logs"},"400":{"description":"Logs only available for flow executions"},"403":{"description":"Forbidden - Requires role: owner, member, application"},"404":{"description":"Execution not found"}},"tags":["Flows"]}}}} ``` ## Cancel a running or suspended execution > \ > 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\ > ```json {"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/flows/{id}/cancel":{"post":{"operationId":"FlowsController_cancelFlow","summary":"Cancel a running or suspended execution","description":"\nCancels an execution by ID. Works for both flow and CI/CD executions.\n\n- **Flow executions**: Cancels the run in Hatchet and rejects any pending approval\n- **CI/CD executions**: Calls the platform's API to cancel the running workflow/pipeline\n- **Orchestrator flows**: Cancels all child flows as well\n ","parameters":[{"name":"id","required":true,"in":"path","description":"ID (TaskExecution UUID or Hatchet Run ID)","schema":{"type":"string"}}],"responses":{"200":{"description":"Execution cancelled"},"400":{"description":"Execution already completed"},"403":{"description":"Forbidden - Requires role: owner, member, application"},"404":{"description":"Execution not found"}},"tags":["Flows"]}}}} ```