Work Items

Update IssueOps request from workflow callback

POST/sfp/api/work-items/requests/callback

Called by the workflow callback flow to update the IssueOps request status. Maps callback events to request statuses:

started → in_progress
completed → completed (or closed if work item was closed)
failed → failed
rejected → completed
cancelled → closed

Uses findOrCreate reconciliation — if the request was not tracked at creation time, it will be backfilled.

Authorization

access-token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

event*string

Callback event type

Value in

"started"
"completed"
"failed"
"rejected"
"cancelled"

platform*string

Callback provider type

Value in

"github"
"azure-devops"

workItemKey*string

Work item key (issue number for GitHub, work item ID for Azure DevOps)

projectIdentifier*string

Project identifier (owner/repo)

closed?boolean

Whether the work item was closed as part of this callback

List IssueOps requests

GET/sfp/api/work-items/requests

List and filter IssueOps requests. projectIdentifier is optional — when omitted, the response spans every project the caller can access (tenant-wide view).

Key Use Cases

Tenant-wide in-flight queue: ?status=open,in_progress
In-flight requests for a project: ?projectIdentifier=x&status=open,in_progress
Requests for a release candidate: ?releaseCandidate=core:RC-JAN25-01
Failed release requests: ?taskType=execute-release&status=failed

The status parameter supports comma-separated values for filtering multiple statuses at once.

Authorization

access-token

AuthorizationBearer <token>

In: header

Query Parameters

projectIdentifier?string

Project identifier to scope results. When omitted, returns requests across every project the caller can access.

status?string

Filter by status. Comma-separated for multiple: open,in_progress

platform?string

Filter by platform

Value in

"jira"
"github"
"azure-devops"

taskType?string

Filter by task type (e.g., execute-release, request-sandbox-create)

releaseCandidate?string

Filter by release candidate (e.g., core:RC-JAN25-01). Returns all requests targeting this RC.

repositoryIdentifier?string

Filter by target repository identifier

createdBy?string

Filter by actor email

since?string

Only requests created after this ISO 8601 timestamp

limit?number

Maximum number of results

Default50

offset?number

Offset for pagination

Default0

Create work item with embedded task payload

POST/sfp/api/work-items/with-payload

Creates a work item (GitHub Issue or Azure DevOps Work Item) with an embedded task payload for IssueOps automation.

How It Works

Provider Detection: The provider is determined by the project's configuration.workItems.provider setting
Authentication: The signed-in user's provider OAuth token is used from the authToken field (required)
Payload Embedding: The task payload is embedded in the work item body for later extraction by automation

Prerequisites

1. Project Configuration

The project must have workItems.provider configured:

# Set via CLIsfp server project update -r flxbl-io/sf-core \  -p configuration.workItems \  -v '{"provider": "azure-devops"}'# Or via APIPATCH /projects/flxbl-io%2Fsf-core{  "property": "configuration.workItems",  "value": { "provider": "azure-devops" }}

2. Authentication - Signed-In User Provider Token Required

The authToken field is mandatory. Work items are created using the signed-in user's provider OAuth token to ensure proper attribution and audit trail.

Why a user token is required:

Work items show the actual user as the creator
Clear audit trail of who initiated each request
Proper attribution for compliance and tracking

Token Requirements:

GitHub: OAuth provider token from login
Azure DevOps: OAuth provider token from login, sent to Azure DevOps as Authorization: Bearer <token>

Note: Server-stored credentials (GitHub App or Azure DevOps service principal) are not used for user-submitted work item creation to ensure proper user attribution.

Valid Task Types

Task Type	Description
`request-elevated-privileges`	Request temporary elevated access
`request-freeze-users`	Freeze users in an environment
`request-unfreeze-users`	Unfreeze users in an environment
`request-sandbox-create`	Create a new sandbox
`request-sandbox-refresh`	Refresh sandbox from source
`request-sandbox-delete`	Delete a sandbox
`install-packages`	Install managed/unlocked packages
`install-artifacts`	Install build artifacts
`install-changeset`	Install or validate a changeset artifact
`create-patch-branch`	Create a patch branch
`run-apex-tests`	Execute Apex tests

Flow Triggering

When triggerFlow: true is set, the endpoint will:

Create the work item as usual
Trigger the associated Hatchet workflow with the payload
Pass the created work item as the callback destination for flow notifications
Return both work item details and flow trigger results

This enables end-to-end IssueOps automation where creating a work item immediately kicks off the associated workflow.

Payload Embedding

The payload is embedded in the work item body in a format that can be extracted by automation:

GitHub: Embedded as HTML comment 
Azure DevOps: Embedded in collapsible section (Azure strips HTML comments)

Authorization

access-token

AuthorizationBearer <token>

In: header

Request Body

application/json

Work item creation parameters

TypeScript Definitions

Use the request body type in TypeScript.

projectIdentifier*string

Project identifier as registered in sfp server. Must match the project's workItems.provider configuration.

title*string

Work item title. Use a descriptive prefix like [Request] for IssueOps workflows.

body?string

Work item body/description. The task payload will be appended to this.

payload*

Task payload with id matching a registered task type. Valid types:

request-elevated-privileges - Request temporary elevated access
request-freeze-users - Freeze users in an environment
request-unfreeze-users - Unfreeze users
request-sandbox-create - Create a new sandbox
request-sandbox-refresh - Refresh sandbox from source
request-sandbox-delete - Delete a sandbox
install-packages - Install managed/unlocked packages
install-artifacts - Install build artifacts
install-changeset - Install or validate a changeset artifact
create-patch-branch - Create a patch branch
run-apex-tests - Execute Apex tests
request-a-release-to-release-envs - Request release deployment to environments (orchestrator)
execute-release - Execute release to a single environment
unbundle-release-candidate - Remove commits from a release candidate branch

authToken?string

Provider OAuth access token for user attribution. Optional.

Pass it when the signed-in user already holds a provider token (social-login). When omitted, the server resolves the caller's linked provider identity (device flow) and acts as them — the token stays server-side. If the caller has no usable linked identity — or the token it resolved is rejected by the provider (expired / revoked / refresh failed) — the request fails with HTTP 428 PROVIDER_IDENTITY_RELINK_REQUIRED; the client should run the device flow (/user/provider-identity/device/start → device/poll) and retry.

GitHub: OAuth provider token from login Azure DevOps: OAuth provider token from login, sent to Azure DevOps as Authorization: Bearer <token>

labels?array<string>

Labels/tags to apply to the work item. Used for filtering and automation triggers.

assignees?array<string>

Assignees for the work item.

GitHub: Array of GitHub usernames Azure DevOps: Array of email addresses

milestone?string

GitHub only: Milestone number or title to associate with the issue

workItemType?string

Azure DevOps only: Work item type. Common types depend on the process template:

Basic: Issue, Epic, Task
Agile: Bug, User Story, Task, Epic
Scrum: Bug, Product Backlog Item, Task, Epic

areaPath?string

Azure DevOps only: Area path for categorization. Use backslashes to separate hierarchy.

iterationPath?string

Azure DevOps only: Iteration path for sprint assignment. Use backslashes to separate hierarchy.

priority?number

Azure DevOps only: Priority level (1 = highest, 4 = lowest)

Range1 <= value <= 4

organizationUrl?string

Azure DevOps only: Organization URL.

Optional if configured in project settings. The server first checks the project's configuration.workItems.organizationUrl. Only provide this to override the project configuration or if not configured at the project level.

Configure at project level via:

PATCH /projects/{identifier}{ "property": "configuration.workItems", "value": { "organizationUrl": "https://dev.azure.com/org", "project": "proj" } }

project?string

Azure DevOps only: Project name within the organization.

Optional if configured in project settings. The server first checks the project's configuration.workItems.project. Only provide this to override the project configuration or if not configured at the project level.

triggerFlow?boolean

Controls whether to trigger the Hatchet workflow immediately after creating the work item.

When to set triggerFlow: true:

You want to trigger the flow immediately without waiting for webhook events
The work item is being created programmatically (e.g., from a UI or automation)
You don't have IssueOps webhooks configured for label-based triggering

When to set triggerFlow: false (default):

You're using the IssueOps pattern where GitHub/Azure DevOps webhooks trigger flows based on labels
You want manual control over when the flow starts (e.g., after review)
The work item is for tracking purposes only

When true:

The flow is triggered synchronously after work item creation
The work item becomes the callback destination for flow notifications
The response includes flowExecution details with the execution ID

When false (default):

Only the work item is created
Flow must be triggered separately (via webhook, label, or manual API call)

Defaultfalse

Response Body

`application/json`

curl -X POST "https://example.com/sfp/api/work-items/with-payload" \  -H "Content-Type: application/json" \  -d '{    "projectIdentifier": "flxbl-io/sf-core",    "title": "[Request] Create Developer Sandbox",    "body": "Requesting a new developer sandbox for sprint work.",    "payload": {      "id": "request-sandbox-create",      "env": "dev",      "duration": "14",      "sourceSandbox": "production"    },    "labels": [      "sandbox",      "automation"    ],    "authToken": "azure-devops-oauth-provider-token"  }'

{  "id": "12345",  "key": "42",  "url": "https://github.com/flxbl-io/sf-core/issues/42",  "platform": "github",  "createdAt": "2025-01-20T12:00:00.000Z",  "flowExecution": {    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",    "taskType": "request-a-release-to-release-envs",    "status": "running",    "triggeredAt": "2025-01-20T12:00:01.000Z"  }}

Update a work item

PATCH/sfp/api/work-items/{platform}/{id}

Update a work item on the specified platform.

Supported Platforms

Platform	Requirements
`github`	Requires `projectIdentifier` (owner/repo format)
`azure-devops`	Uses configured integration credentials
`jira`	Not yet implemented

Available Updates

title: Update the work item title
body: Update the description/body
state: Change the state (e.g., "open", "closed" for GitHub)
labels: Set labels/tags
assignees: Set assignees

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

platform*string

Platform where the work item exists

Value in

"jira"
"github"
"azure-devops"

id*string

Work item ID or key

Response Body

curl -X PATCH "https://example.com/sfp/api/work-items/jira/string"

Empty

Close a work item

POST/sfp/api/work-items/{platform}/{id}/close

Close a work item on the specified platform.

Supported Platforms

Platform	Close Behavior
`github`	Sets issue state to "closed". Optional comment.
`azure-devops`	Sets state to "Closed" with optional reason.
`jira`	Not yet implemented

Options

comment: Add a comment when closing
reason: Close reason (Azure DevOps only: "Completed", "Resolved", "Removed", etc.)

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

platform*string

Platform where the work item exists

Value in

"jira"
"github"
"azure-devops"

id*string

Work item ID or key

Response Body

curl -X POST "https://example.com/sfp/api/work-items/jira/string/close"

Empty

Get work item by ID

GET/sfp/api/work-items/{id}

Fetch a work item by its ID. The platform is automatically determined from the project's configuration.workItems.provider setting.

ID Formats by Platform

Platform	ID Format	Example
`jira`	Project key + number	`DP-6`, `PROJ-123`
`github`	Issue number	`42`, `123`
`azure-devops`	Work item ID	`456`, `789`

Prerequisites

The project must have workItems.provider configured:

sfp server project update -r owner/repo \  -p configuration.workItems \  -v '{"provider": "jira"}'

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Work item ID or key

Query Parameters

projectIdentifier*string

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

Response Body

`application/json`

curl -X GET "https://example.com/sfp/api/work-items/DP-6?projectIdentifier=flxbl-io%2Fsf-core"

{  "id": "10042",  "key": "DP-6",  "title": "Implement user authentication",  "description": "Add OAuth 2.0 authentication flow",  "type": "story",  "status": "In Progress",  "priority": "High",  "assignee": {    "id": "user123",    "name": "John Doe",    "email": "john@example.com",    "avatarUrl": "https://example.com/avatar.png"  },  "reporter": {    "id": "user456",    "name": "Jane Smith",    "email": "jane@example.com"  },  "labels": [    "backend",    "security"  ],  "createdAt": "2025-01-10T08:00:00.000Z",  "updatedAt": "2025-01-11T14:30:00.000Z",  "platform": "jira",  "url": "https://flxbl-demo.atlassian.net/browse/DP-6",  "parent": {    "id": "10040",    "key": "DP-1",    "title": "Authentication Epic"  },  "customFields": {    "projectKey": "DP",    "projectName": "Demo Project",    "issueTypeId": "10001",    "statusId": "3"  }}

List work items

GET/sfp/api/work-items

List work items with optional filters. The platform is automatically determined from the project's configuration.workItems.provider setting.

Prerequisites

The project must have workItems.provider configured. Optionally configure boards to filter by specific boards/projects:

# Configure provider and boards (Jira project keys)sfp server project update -r owner/repo \  -p configuration.workItems \  -v '{"provider": "jira", "boards": ["DP", "PROJ"]}'# Configure provider and boards (Azure DevOps area paths)sfp server project update -r owner/repo \  -p configuration.workItems \  -v '{"provider": "azure-devops", "boards": ["MyProject\\Team1"]}'

Filter Examples

# List work items (uses boards from project config)GET /work-items?projectIdentifier=owner/repo# Filter by statusGET /work-items?projectIdentifier=owner/repo&status=In Progress# Filter by assigneeGET /work-items?projectIdentifier=owner/repo&assignee=john.doe# Filter by type with limitGET /work-items?projectIdentifier=owner/repo&type=bug&maxResults=10

Authorization

access-token

AuthorizationBearer <token>

In: header

Query Parameters

projectIdentifier*string

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

status?string

Filter by work item status (e.g., "To Do", "In Progress", "Done")

assignee?string

Filter by assignee username or email

type?string

Filter by work item type (e.g., "bug", "story", "task", "epic")

maxResults?number

Maximum number of results to return (1-100, default: 50)

Response Body

`application/json`

curl -X GET "https://example.com/sfp/api/work-items?projectIdentifier=flxbl-io%2Fsf-core"

[  {    "id": "10042",    "key": "DP-6",    "title": "Implement user authentication",    "type": "story",    "status": "In Progress",    "priority": "High",    "platform": "jira",    "url": "https://example.atlassian.net/browse/DP-6"  },  {    "id": "10043",    "key": "DP-7",    "title": "Add password reset functionality",    "type": "story",    "status": "To Do",    "priority": "Medium",    "platform": "jira",    "url": "https://example.atlassian.net/browse/DP-7"  }]

200

403

Key Use Cases

200

403

200

403

404

How It Works

Prerequisites

1. Project Configuration

2. Authentication - Signed-In User Provider Token Required

Valid Task Types

Flow Triggering

Payload Embedding

201application/json

400application/json

401application/json

403

404application/json

Supported Platforms

Available Updates

200

400

403

404

Supported Platforms

Options

200

400

403

404

ID Formats by Platform

Prerequisites

200application/json

403

404application/json

Prerequisites

Filter Examples

200application/json

403

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`