Pools

Get all pool configurations

GET/sfp/api/pools/configs

Retrieve all pool configurations (both sandbox and scratch org pools), optionally filtered by repository and/or pool type

Authorization

access-token

AuthorizationBearer <token>

In: header

Query Parameters

repositoryIdentifier?string

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

poolType?string

Filter by pool type (SANDBOX or SCRATCH_ORG)

Value in

"SANDBOX"
"SCRATCH_ORG"

hasAssignmentRules?boolean

Filter by assignment rules: true = only pools with rules, false = only pools without rules (no branchPattern or domainPatterns)

`application/json`

curl -X GET "https://example.com/sfp/api/pools/configs"

[  {    "repositoryIdentifier": "flxbl-io/sf-core",    "name": "Development Pool",    "poolTag": "dev-pool",    "branchPattern": "feature/*",    "devHubUsername": "sandbox-manager@example.com",    "sandboxDefinition": {      "autoActivate": true,      "licenseType": "Developer",      "description": "Dev sandbox for feature development",      "sandboxName": [        "DEV",        "QA"      ]    },    "sourceSandboxName": "TEMPLATE_SB",    "daysToKeepUnassignedAvailable": 30,    "isActive": true,    "additionalConfig": {},    "lastMonitoredAt": "2025-01-01T12:00:00Z",    "currentProvisionRunId": "run-123456",    "currentMonitorRunId": "mon-123456",    "defaultExpirationHours": 168,    "extendedExpirationHours": 336,    "averageOrgCreationTime": 45,    "lastProvisionedAt": "2025-01-01T12:00:00Z",    "minAvailableInstances": 3,    "maxTotalInstances": 10,    "refreshOrDeleteStrategy": "DELETE_EXPIRED",    "refreshStrategy": "ALWAYS",    "refreshIntervalHours": 24,    "minActiveInstances": 3,    "maxActiveInstances": 10,    "minRetentionDays": 7,    "returnToPoolOnUnassign": false,    "metadata": {      "environment": "dev",      "team": "platform",      "region": "us-west"    },    "monitoringCronPattern": "*/30 * * * *",    "poolStatus": "ACTIVE",    "cleanupJobId": "string"  }]

Create a new pool configuration

POST/sfp/api/pools/configs

Create a new configuration for a sandbox or scratch org pool. Use poolType=SCRATCH_ORG for scratch org pools.

Authorization

access-token

AuthorizationBearer <token>

In: header

Query Parameters

poolType?string

Pool type: SANDBOX (default) or SCRATCH_ORG

Value in

"SANDBOX"
"SCRATCH_ORG"

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

repositoryIdentifier*string

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

name*string

User-friendly display name for the pool

poolTag*string

Unique machine-readable tag for this pool. Must be lowercase.

branchPattern?string

Optional Git branch pattern this pool serves

devHubUsername*Parent production connection

Registered parent production username used throughout sandbox lifecycle operations and review-environment authentication. Dev Hub enablement is not required; the user needs sandbox-management permissions and available licenses.

sandboxDefinition?

Sandbox definition configuration. Either specify licenseType to create from production OR sourceSandboxName to clone an existing sandbox

sourceSandboxName?string

Deprecated

Source sandbox name for cloning (deprecated - use sandboxDefinition.sourceSandboxName)

minAvailableInstances*number

Target number of AVAILABLE sandboxes

maxTotalInstances*number

Hard cap for total sandboxes in this pool

daysToKeepUnassignedAvailable*number

TTL in days for available sandboxes before refresh/delete

refreshOrDeleteStrategy*string

Strategy for handling expired sandboxes

Value in

"DELETE_EXPIRED"
"AUTO_REFRESH_EXPIRED"
"FLAG_EXPIRED"
"NOTIFY_ONLY"

isActive*boolean

Whether this pool configuration is active for monitoring

additionalConfig?

Additional configuration for user activation and data seeding

defaultExpirationHours?number

Default expiration hours for assigned sandboxes

Default24

extendedExpirationHours?number

Extended expiration hours for assigned sandboxes

averageOrgCreationTime?number

Average time in minutes it takes to create a sandbox

returnToPoolOnUnassign?boolean

When true, unassigned sandboxes return to pool as AVAILABLE. When false, they are marked as EXPIRED

Defaultfalse

monitoringCronPattern?string

Cron pattern for monitoring schedule (5-field standard cron)

Default"*/30 * * * *"

metadata?

Additional metadata for the pool configuration for custom filtering and tagging

Response Body

`application/json`

curl -X POST "https://example.com/sfp/api/pools/configs" \  -H "Content-Type: application/json" \  -d '{    "repositoryIdentifier": "flxbl-io/sf-core",    "name": "Development Pool",    "poolTag": "dev-pool",    "devHubUsername": "sandbox-manager@example.com",    "minAvailableInstances": 3,    "maxTotalInstances": 10,    "daysToKeepUnassignedAvailable": 30,    "refreshOrDeleteStrategy": "DELETE_EXPIRED",    "isActive": true  }'

Empty

Get a pool configuration

GET/sfp/api/pools/configs/{poolTag}

Retrieve a specific pool configuration (sandbox or scratch org) by tag and repository

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

poolTag*string

The tag of the pool to retrieve

Query Parameters

repositoryIdentifier*string

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

poolType?string

Pool type hint for faster lookup (SANDBOX or SCRATCH_ORG). If not specified, both types are checked

Value in

"SANDBOX"
"SCRATCH_ORG"

Response Body

`application/json`

curl -X GET "https://example.com/sfp/api/pools/configs/string?repositoryIdentifier=flxbl-io%2Fsf-core"

{  "repositoryIdentifier": "flxbl-io/sf-core",  "name": "Development Pool",  "poolTag": "dev-pool",  "branchPattern": "feature/*",  "devHubUsername": "sandbox-manager@example.com",  "sandboxDefinition": {    "autoActivate": true,    "licenseType": "Developer",    "description": "Dev sandbox for feature development",    "sandboxName": [      "DEV",      "QA"    ]  },  "sourceSandboxName": "TEMPLATE_SB",  "daysToKeepUnassignedAvailable": 30,  "isActive": true,  "additionalConfig": {},  "lastMonitoredAt": "2025-01-01T12:00:00Z",  "currentProvisionRunId": "run-123456",  "currentMonitorRunId": "mon-123456",  "defaultExpirationHours": 168,  "extendedExpirationHours": 336,  "averageOrgCreationTime": 45,  "lastProvisionedAt": "2025-01-01T12:00:00Z",  "minAvailableInstances": 3,  "maxTotalInstances": 10,  "refreshOrDeleteStrategy": "DELETE_EXPIRED",  "refreshStrategy": "ALWAYS",  "refreshIntervalHours": 24,  "minActiveInstances": 3,  "maxActiveInstances": 10,  "minRetentionDays": 7,  "returnToPoolOnUnassign": false,  "metadata": {    "environment": "dev",    "team": "platform",    "region": "us-west"  },  "monitoringCronPattern": "*/30 * * * *",  "poolStatus": "ACTIVE",  "cleanupJobId": "string"}

Update a pool configuration

PATCH/sfp/api/pools/configs/{poolTag}

Update an existing configuration for a sandbox or scratch org pool

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

poolTag*string

The tag of the pool to update

Query Parameters

repositoryIdentifier*string

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

poolType?string

Pool type hint for routing (SANDBOX or SCRATCH_ORG)

Value in

"SANDBOX"
"SCRATCH_ORG"

Response Body

`application/json`

curl -X PATCH "https://example.com/sfp/api/pools/configs/string?repositoryIdentifier=flxbl-io%2Fsf-core"

Empty

Delete a pool configuration

DELETE/sfp/api/pools/configs/{poolTag}

Delete an existing pool configuration. For sandbox pools, deletes the configuration and all sandboxes. For scratch org pools, deletes all scratch orgs in the pool from Salesforce.

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

poolTag*string

The tag of the pool to delete

Query Parameters

repositoryIdentifier*string

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

Response Body

`application/json`

curl -X DELETE "https://example.com/sfp/api/pools/configs/string?repositoryIdentifier=flxbl-io%2Fsf-core"

Empty

Get a pool's provisioning origin

GET/sfp/api/pools/configs/{poolTag}/provisioning-origin

Resolve what a pool provisions its instances from: a scratch org pool returns its base snapshot (read from the snapshot key in the scratch def file) or scratchDefinition when built fresh; a sandbox pool returns its source sandbox or production license.

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

poolTag*string

The tag of the pool

Query Parameters

repositoryIdentifier*string

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

poolType?string

Pool type hint for faster lookup. If not specified, both types are checked

Value in

"SANDBOX"
"SCRATCH_ORG"

Response Body

curl -X GET "https://example.com/sfp/api/pools/configs/string/provisioning-origin?repositoryIdentifier=flxbl-io%2Fsf-core"

Empty

List pool tag collisions

GET/sfp/api/pools/collisions

Report pool tags claimed by more than one pool type in a repository. A tag is unique only within a pool type, so a sandbox pool and a scratch org pool can share one — in which case tag-only lookups resolve to the sandbox pool and the other becomes unreachable. Read-only; never repairs.

Authorization

access-token

AuthorizationBearer <token>

In: header

Query Parameters

repositoryIdentifier*string

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

Response Body

curl -X GET "https://example.com/sfp/api/pools/collisions?repositoryIdentifier=flxbl-io%2Fsf-core"

Empty

Get pool status

GET/sfp/api/pools/status

Retrieve current status of pools (sandbox or scratch org) and their instances. Supports filtering by status, pool type, and entity assignment.

Authorization

access-token

AuthorizationBearer <token>

In: header

Query Parameters

repositoryIdentifier?string

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

poolTag?string

Optional. If provided, returns detailed status for the specified pool.

instanceStatus?string

Optional. Filter instances by status (used with poolTag).

Value in

"REQUESTED"
"PROVISIONING"
"ACTIVATING"
"AVAILABLE"
"ASSIGNED"
"EXPIRED"
"FLAGGED_FOR_REFRESH"
"REFRESHING"
"DELETING"
"ORPHANED"
"ERROR"
"UNKNOWN"

assignmentId?string

Optional. Filter by assignment UUID (sandbox pools only).

poolType?string

Optional. Pool type hint for faster lookup (SANDBOX or SCRATCH_ORG).

Value in

"SANDBOX"
"SCRATCH_ORG"

refresh?boolean

Optional. Force refresh of cached data for scratch org pools.

Response Body

`application/json`

curl -X GET "https://example.com/sfp/api/pools/status"

Empty

Cleanup zombie sandbox instances

POST/sfp/api/pools/cleanup-zombies

Identify and optionally cleanup sandbox instances that exist in the database but not in Salesforce

Authorization

access-token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

devHubUsername*string

DevHub username to check for zombies

dryRun?boolean

If true, only identify zombies without deleting them

Response Body

`application/json`

curl -X POST "https://example.com/sfp/api/pools/cleanup-zombies" \  -H "Content-Type: application/json" \  -d '{    "devHubUsername": "devhub_main_org"  }'

Empty

Get current sandbox service mode

GET/sfp/api/pools/mode

Returns whether the system is using mock or real Salesforce sandbox service. All authenticated users can view the service mode.

Authorization

access-token

AuthorizationBearer <token>

In: header

Response Body

`application/json`

curl -X GET "https://example.com/sfp/api/pools/mode"

{  "mode": "mock",  "description": "string",  "mockModeEnvVar": "string"}

Get pool monitoring status

GET/sfp/api/pools/monitoring-jobs

Retrieve information about all repository-specific pool monitoring jobs. All authenticated users can view monitoring job status.

Authorization

access-token

AuthorizationBearer <token>

In: header

Response Body

`application/json`

curl -X GET "https://example.com/sfp/api/pools/monitoring-jobs"

{  "totalJobs": 3,  "jobs": [    {      "jobName": "pool-monitor-flxbl-io-sf-core-dev",      "repositoryIdentifier": "flxbl-io/sf-core",      "poolTag": "dev",      "poolType": "SANDBOX",      "taskType": "monitor-pool",      "description": "Sandbox pool monitoring — flxbl-io/sf-core/dev",      "pattern": "*/30 * * * *",      "enabled": true,      "nextRun": "2024-01-01T12:30:00Z",      "lastRun": "2024-01-01T12:00:00Z",      "running": false,      "lastRunUrl": "https://sfp.example.com/workflows/runs/550e8400-e29b-41d4-a716-446655440000?repo=flxbl-io%2Fsf-core",      "lastRunExecutionId": "550e8400-e29b-41d4-a716-446655440000"    }  ]}

Pause a pool monitoring job

POST/sfp/api/pools/monitoring-jobs/{jobName}/pause

Disables a pool monitoring cron schedule without deleting it.

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

jobName*string

The monitoring job name (cron name)

Response Body

curl -X POST "https://example.com/sfp/api/pools/monitoring-jobs/string/pause"

Empty

Resume a paused pool monitoring job

POST/sfp/api/pools/monitoring-jobs/{jobName}/resume

Re-enables a previously paused pool monitoring cron schedule.

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

jobName*string

The monitoring job name (cron name)

Response Body

curl -X POST "https://example.com/sfp/api/pools/monitoring-jobs/string/resume"

Empty

List pool instances

GET/sfp/api/pools/{poolTag}/instances

Get a list of all instances in a specific pool (sandbox or scratch org)

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

poolTag*string

Pool tag to get instances for (works with both sandbox and scratch org pools)

Query Parameters

repositoryIdentifier*string

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

poolType?string

Optional pool type hint for faster lookup (SANDBOX or SCRATCH_ORG). If not specified, the pool type is auto-detected

Value in

"SANDBOX"
"SCRATCH_ORG"

refresh?boolean

Optional. Force refresh of cached data for scratch org pools (ignored for sandbox pools).

Response Body

`application/json`

curl -X GET "https://example.com/sfp/api/pools/core_dev or ci/instances?repositoryIdentifier=flxbl-io%2Fsf-core"

[  {}]

Drain all instances from a pool (keeps pool config)

DELETE/sfp/api/pools/{poolTag}/instances

Dispatches the cleanup Hatchet workflow with skipFinalize=true — drops all instances but preserves the pool configuration. Pass poolTag=all to drain every active pool in the repository.

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

poolTag*string

Pool tag to drain, or "all" to drain every active pool

Query Parameters

repositoryIdentifier*string

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

Response Body

curl -X DELETE "https://example.com/sfp/api/pools/core_dev/instances?repositoryIdentifier=flxbl-io%2Fsf-core"

Empty

Fetch and assign sandbox from pool

POST/sfp/api/pools/{poolTag}/fetch

Assign an available sandbox from the pool using a unique assignment ID. If a sandbox is already assigned to the provided assignment ID, it will be reused.

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

poolTag*string

Pool tag to fetch sandbox from

Query Parameters

repositoryIdentifier*string

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

Request Body

application/json

Assignment configuration

TypeScript Definitions

Use the request body type in TypeScript.

assignmentId?string

UUID identifying the assignment. If not provided, a new UUID will be generated.

alias?string

User-selected alias for the sandbox assignment

Lengthlength <= 8

isImmortal?boolean

If true, the sandbox will not expire automatically

Defaultfalse

assignedToUserEmail?string

Email of the user to assign the sandbox to. Only applicable when using application tokens. If not provided, defaults to app:<token_creator>

createUser?boolean

If true, creates a Salesforce user in the assigned sandbox and sends a password reset email. Sandbox pools only.

Defaultfalse

Response Body

`application/json`

curl -X POST "https://example.com/sfp/api/pools/core_dev/fetch?repositoryIdentifier=flxbl-io%2Fsf-core" \  -H "Content-Type: application/json" \  -d '{}'

Empty

Unassign instance from user

POST/sfp/api/pools/{poolTag}/unassign

Release an assigned instance (sandbox or scratch org) and return it to the available pool. Provide either instanceId for direct unassignment, or assignmentId to find and unassign the instance. The user must own the instance or have Owner role.

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

poolTag*string

Pool tag where the instance belongs (works with both sandbox and scratch org pools)

Query Parameters

repositoryIdentifier*string

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

Request Body

application/json

Unassignment details: either sandboxId OR assignmentId

TypeScript Definitions

Use the request body type in TypeScript.

sandboxId?string

ID of the sandbox to unassign (required if assignmentId is not provided)

assignmentId?string

UUID of the assignment to unassign (required if sandboxId is not provided)

returnToPool?boolean

When true (default), the sandbox returns to the AVAILABLE pool with a reset timer. When false, the sandbox is marked as EXPIRED.

Defaulttrue

Response Body

`application/json`

curl -X POST "https://example.com/sfp/api/pools/core_dev or ci/unassign?repositoryIdentifier=flxbl-io%2Fsf-core" \  -H "Content-Type: application/json" \  -d '{}'

Empty

Provision users into a sandbox

POST/sfp/api/pools/{poolTag}/instances/{instanceName}/users

Dispatch durable user provisioning for an existing pool sandbox through Hatchet.

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

poolTag*string

Sandbox pool tag

instanceName*string

Sandbox instance name

Query Parameters

repositoryIdentifier*string

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

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

sandboxName*string

Name of the sandbox to provision users into

configName?string

Named stored developer configuration the access levels belong to; defaults to 'default'. A repository stores one configuration per devconfig file (persona).

users*array<>

Users to provision with their individual access and password reset policy

Response Body

`application/json`

curl -X POST "https://example.com/sfp/api/pools/core_dev/instances/dev1/users?repositoryIdentifier=flxbl-io%2Fsf-core" \  -H "Content-Type: application/json" \  -d '{    "sandboxName": "dev1",    "users": [      {        "email": "developer@example.com",        "accessLevel": "developer",        "sendPasswordReset": true      }    ]  }'

{  "taskExecutionId": "string",  "taskType": "provision-pool-users",  "status": "running",  "triggeredAt": "string"}

Regenerate sandbox SFDX auth URL

POST/sfp/api/pools/{poolTag}/regenerate-auth-url

Regenerate and persist a fresh SFDX auth URL for a sandbox pool instance. Owners and application tokens may regenerate any sandbox in the pool; members may regenerate only their own assigned sandbox.

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

poolTag*string

Sandbox pool tag where the instance belongs

Query Parameters

repositoryIdentifier*string

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

Request Body

application/json

Regeneration target: provide exactly one of sandboxId, sandboxName, or assignmentId

TypeScript Definitions

Use the request body type in TypeScript.

sandboxId?string

ID of the sandbox instance to regenerate auth URL for (required if sandboxName and assignmentId are not provided)

sandboxName?string

Name of the sandbox to regenerate auth URL for (required if sandboxId and assignmentId are not provided)

assignmentId?string

UUID of the assignment to regenerate auth URL for (required if sandboxId and sandboxName are not provided)

Response Body

`application/json`

curl -X POST "https://example.com/sfp/api/pools/core_dev/regenerate-auth-url?repositoryIdentifier=flxbl-io%2Fsf-core" \  -H "Content-Type: application/json" \  -d '{}'

{  "status": "auth_url_regenerated",  "message": "SFDX auth URL for sandbox dev1 has been regenerated.",  "timestamp": "2026-07-07T08:00:00.000Z",  "details": {    "sandboxId": "sb-123456",    "sandboxName": "dev1",    "poolTag": "core_dev",    "assignmentId": "550e8400-e29b-41d4-a716-446655440000",    "instanceUrl": "https://dev1.sandbox.salesforce.com",    "sfdxAuthUrl": "force://PlatformCLI::refresh-token@dev1.sandbox.salesforce.com",    "regeneratedAt": "2026-07-07T08:00:00.000Z"  }}

Extend sandbox expiration time

POST/sfp/api/pools/{poolTag}/extend

Extend the expiration time of a sandbox identified by its assignment ID. You can specify custom extension hours in the request body, otherwise it defaults to the pool configuration.

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

poolTag*string

Pool tag where the sandbox belongs

Query Parameters

repositoryIdentifier*string

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

Request Body

application/json

Assignment details to extend sandbox for

TypeScript Definitions

Use the request body type in TypeScript.

assignmentId*string

UUID of the assignment to extend

extensionHours?number

Number of hours to extend the sandbox expiration. If not provided, uses the pool's configured extension hours.

Range1 <= value <= 720

isImmortal?boolean

Set or change the immortal state of the sandbox. If not provided, immortal state remains unchanged.

Response Body

`application/json`

curl -X POST "https://example.com/sfp/api/pools/core_dev/extend?repositoryIdentifier=flxbl-io%2Fsf-core" \  -H "Content-Type: application/json" \  -d '{    "assignmentId": "550e8400-e29b-41d4-a716-446655440000"  }'

Empty

Trigger pool replenishment workflow

POST/sfp/api/pools/{poolTag}/replenish

Triggers the pool replenishment Hatchet workflow asynchronously. For sandbox pools fires the monitoring flow (reconciliation + lifecycle + quota). For scratch org pools fires the provisioning flow. Pass poolTag=all to replenish all active pools in the repository.

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

poolTag*string

Pool tag to replenish, or "all" to target all active pools

Query Parameters

repositoryIdentifier*string

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

Response Body

`application/json`

curl -X POST "https://example.com/sfp/api/pools/core_dev/replenish?repositoryIdentifier=flxbl-io%2Fsf-core"

Empty

Delete an org instance from a pool

DELETE/sfp/api/pools/{poolTag}/instances/{instanceName}

Delete an org instance from the pool. For scratch orgs, deletes from DevHub and removes from tracking. For sandboxes, deletes from Salesforce and removes from database. ERROR status instances are always cleaned up from the database.

Authorization

access-token

AuthorizationBearer <token>

In: header

Path Parameters

poolTag*string

Pool tag where the instance belongs

instanceName*string

Name/username of the org instance to delete

Query Parameters

repositoryIdentifier*string

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

force?boolean

Delete an immortal instance. Note this does NOT bypass Salesforce's per-licence refresh interval — that is enforced by Salesforce. Inside it, the instance is taken out of the pool and marked DELETING for automatic retry, and the response reports deletionType=deferred.

Response Body

curl -X DELETE "https://example.com/sfp/api/pools/core_dev/instances/test-abc@example.com?repositoryIdentifier=flxbl-io%2Fsf-core"

Empty

200application/json

403

403

defaultapplication/json

200application/json

403

403

defaultapplication/json

403

defaultapplication/json

200

403

200

403

403

defaultapplication/json

403

defaultapplication/json

200application/json

403

200application/json

403

200

403

200

403

200application/json

403

202

403

403

defaultapplication/json

403

defaultapplication/json

202application/json

400

403

404

200application/json

400

403

404

403

defaultapplication/json

403

defaultapplication/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`