Review Environments

Assign a review environment from pool

POST/sfp/api/review/environments/assign

Fetches an available environment from the specified pool and assigns it to a PR, issue, user, or custom identifier. If an active assignment already exists, it will be reused.

Authorization

access-token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

assignmentType*string

Type of assignment for the review environment

Value in

"pr"
"issue"
"user"
"custom"

assignmentId*string

Unique identifier for the assignment (e.g., "123" for PR number)

Match^[a-zA-Z0-9@._-]+$

repositoryIdentifier*string

Repository identifier in format owner/repo or org/project/repo

Match^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+(\/[a-zA-Z0-9_.-]+)?$

poolTag?string

Tag of the pool to fetch from. If not provided, resolved via branch/domain patterns

Match^[a-z0-9_-]+$

branch?string

Git branch name for automatic pool resolution

domains?array<string>

Domain names for automatic pool resolution (supports multiple domains)

domain?string

Specific domain for multi-domain assignments

expirationHours?integer

Hours before expiration (1-720). If not provided, uses pool default

Range1 <= value <= 720

isImmortal?boolean

If true, the environment will never expire

Defaultfalse

metadata*

Additional metadata for the assignment

override?boolean

Force reassignment even if an environment is already assigned

Defaultfalse

`application/json`

curl -X POST "https://example.com/sfp/api/review/environments/assign" \  -H "Content-Type: application/json" \  -d '{    "assignmentType": "pr",    "assignmentId": "string",    "repositoryIdentifier": "string",    "metadata": {      "property1": null,      "property2": null    }  }'

Empty

Resolve review environment(s) by org instance name

GET/sfp/api/review/environments/by-instance

Returns the assignment(s) referencing the given org instance (incl. expired), for a legacy link that carries only the instance name.

Authorization

access-token

AuthorizationBearer <token>

In: header

Query Parameters

target*string

Org instance name (sandbox/scratch name)

domain?string

Optional domain scope

Get review environment details

GET/sfp/api/review/environments/{assignmentType}/{assignmentId}

Retrieves the details of a specific review environment assignment

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

assignmentType*string

Type of assignment

Value in

"pr"
"issue"
"user"
"custom"

assignmentId*string

Assignment identifier

Query Parameters

repositoryIdentifier?string

Repository identifier (owner/repo). Optional — derived from the assignment when omitted.

domain?string

Specific domain for multi-domain assignments

`application/json`

curl -X GET "https://example.com/sfp/api/review/environments/pr/string"

Empty

Extend review environment expiration

POST/sfp/api/review/environments/extend

Extends the expiration time of a review environment assignment. Can also be used to make an environment immortal or remove immortal status.

Authorization

access-token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

assignmentType*string

Type of assignment for the review environment

Value in

"pr"
"issue"
"user"
"custom"

assignmentId*string

Unique identifier for the assignment

repositoryIdentifier*string

Repository identifier in format owner/repo

extensionHours?number

Number of hours to extend the expiration by. If not provided, uses pool default.

Range1 <= value <= 168

isImmortal?boolean

If true, makes the environment immortal (never expires). If false, removes immortal status.

domain?string

Specific domain to extend. If not provided, extends the default domain.

`application/json`

curl -X POST "https://example.com/sfp/api/review/environments/extend" \  -H "Content-Type: application/json" \  -d '{    "assignmentType": "pr",    "assignmentId": "123",    "repositoryIdentifier": "flxbl-io/sf-core"  }'

Empty

Unassign review environment

POST/sfp/api/review/environments/unassign

Releases a review environment assignment and optionally returns it to the pool

Authorization

access-token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

assignmentType*string

Type of assignment for the review environment

Value in

"pr"
"issue"
"user"
"custom"

assignmentId*string

Unique identifier for the assignment

repositoryIdentifier*string

Repository identifier in format owner/repo

returnToPool?boolean

Whether to return the environment to the pool as available (true) or mark it expired (false). Explicit values always win. If omitted, the server falls back to each instance's pool config returnToPoolOnUnassign (default false). Multi-domain unassigns resolve per-instance, so each domain can take a different decision based on its own pool. Scratch-org pools always delete the org regardless of this flag.

domain?string

Specific domain to unassign. If not provided, unassigns all domains.

Response Body

`application/json`

curl -X POST "https://example.com/sfp/api/review/environments/unassign" \  -H "Content-Type: application/json" \  -d '{    "assignmentType": "pr",    "assignmentId": "123",    "repositoryIdentifier": "flxbl-io/sf-core"  }'

Empty

Transition environment between assignments

POST/sfp/api/review/environments/transition

Moves a review environment from one assignment to another (e.g., from PR to issue)

Authorization

access-token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

repositoryIdentifier*string

Repository identifier in format owner/repo

fromAssignmentType*string

Current assignment type

Value in

"pr"
"issue"
"user"
"custom"

fromAssignmentId*string

Current assignment identifier

toAssignmentType*string

New assignment type

Value in

"pr"
"issue"
"user"
"custom"

toAssignmentId*string

New assignment identifier

metadata?

Additional metadata for the new assignment

Response Body

`application/json`

curl -X POST "https://example.com/sfp/api/review/environments/transition" \  -H "Content-Type: application/json" \  -d '{    "repositoryIdentifier": "flxbl-io/sf-core",    "fromAssignmentType": "pr",    "fromAssignmentId": "123",    "toAssignmentType": "issue",    "toAssignmentId": "456"  }'

Empty

Acquire environment for use

POST/sfp/api/review/environments/acquire

Marks an assigned environment as in-use for a specified duration. Uses optimistic locking to handle concurrent requests.

Authorization

access-token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

assignmentType*string

Type of assignment

Value in

"pr"
"issue"
"user"
"custom"

assignmentId*string

Unique identifier for the assignment

repositoryIdentifier*string

Repository identifier in format owner/repo

duration*number

Duration in minutes for which the environment is needed

Range1 <= value <= 480

usedBy*string

Identifier of the process or user acquiring the environment

domain?string

Specific domain to acquire (for multi-domain assignments)

lock?boolean

Whether to take the exclusive usage lease (default true). Set false to mint fresh credentials WITHOUT locking the environment — for read/observe callers (e.g. opening a browser session) that must coexist with a running validation rather than block it.

Defaulttrue

Response Body

`application/json`

curl -X POST "https://example.com/sfp/api/review/environments/acquire" \  -H "Content-Type: application/json" \  -d '{    "assignmentType": "pr",    "assignmentId": "123",    "repositoryIdentifier": "flxbl-io/sf-core",    "duration": 30,    "usedBy": "ci-pipeline-123 or user@example.com"  }'

{  "status": "environment_acquired",  "message": "Environment successfully acquired for 30 minutes",  "timestamp": "2019-08-24T14:15:22Z",  "assignment": {}}

Release environment from use

POST/sfp/api/review/environments/release

Marks an environment as idle, making it available for other processes to acquire

Authorization

access-token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

assignmentType*string

Type of assignment

Value in

"pr"
"issue"
"user"
"custom"

assignmentId*string

Unique identifier for the assignment

Length1 <= length

repositoryIdentifier*string

Repository identifier in format owner/repo or org/project/repo

Match^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+(\/[a-zA-Z0-9_.-]+)?$

domain?string

Specific domain to release (for multi-domain assignments)

Response Body

`application/json`

curl -X POST "https://example.com/sfp/api/review/environments/release" \  -H "Content-Type: application/json" \  -d '{    "assignmentType": "pr",    "assignmentId": "string",    "repositoryIdentifier": "string"  }'

{  "status": "environment_released",  "message": "Environment successfully released",  "timestamp": "2019-08-24T14:15:22Z",  "assignment": {}}

List review environment assignments

GET/sfp/api/review/environments/list

Retrieves a list of review environment assignments with optional filters

Authorization

access-token

AuthorizationBearer <token>

In: header

Query Parameters

repositoryIdentifier?string

Filter by repository identifier

assignmentType?string

Filter by assignment type

Value in

"pr"
"issue"
"user"
"custom"

assignmentId?string

Filter by assignment ID

poolTag?string

Filter by pool tag

instanceName?string

Filter by the org INSTANCE NAME (sandbox/scratch name, e.g. 754944). Resolves a legacy link that carries only the org instance, across whatever assignment(s) reference it (incl. expired/recycled).

status?string

Filter by assignment status

Value in

"active"
"expired"
"released"
"unassigned"

assignedBy?string

Filter by who assigned the environment

includeExpired?boolean

Include expired assignments in the results. By default, expired assignments are excluded unless explicitly requested

Defaultfalse

Response Body

`application/json`

curl -X GET "https://example.com/sfp/api/review/environments/list"

Empty

403

defaultapplication/json

403

403

defaultapplication/json

403

defaultapplication/json

403

defaultapplication/json

403

defaultapplication/json

200application/json

403

404

409application/json

200application/json

403

404

409

403

defaultapplication/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`