Pools

Get all pool configurations

get

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

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

repositoryIdentifierstringOptional

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

Example: flxbl-io/sf-core

poolTypestring · enumOptional

Filter by pool type (SANDBOX or SCRATCH_ORG)

Possible values:

hasAssignmentRulesbooleanOptional

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

Responses

200

Pool configurations retrieved successfully

application/json

repositoryIdentifierstringRequired

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

Example: flxbl-io/sf-core

namestringRequired

User-friendly display name for the pool

Example: Development Pool

poolTagstringRequired

Unique machine-readable tag for this pool

Example: dev-pool

branchPatternstringOptional

Optional Git branch pattern this pool serves

Example: feature/*

devHubUsernamestringRequired

Registered Dev Hub alias/username

Example: devhub@example.com

sandboxDefinitionobjectOptional

Sandbox definition configuration. Either specify licenseType to create from production OR sourceSandboxName to clone an existing sandbox. Key fields: sandboxName (array of prefixes), licenseType (Developer/Developer_Pro/Partial/Full), sourceSandboxName (for cloning), autoActivate (default true)

Example:

{"autoActivate":true,"licenseType":"Developer","description":"Dev sandbox for feature development","sandboxName":["DEV","QA"]}

sourceSandboxNamestringOptionalDeprecated

Source sandbox name for cloning. Use this to clone from an existing sandbox instead of creating from production. Either use sandboxDefinition.sourceSandboxName or this field (deprecated)

Example: TEMPLATE_SB

daysToKeepUnassignedAvailablenumberRequired

TTL in days for available sandboxes before refresh/delete

Example: 30

isActivebooleanRequired

Whether this pool configuration is active for monitoring

Example: true

additionalConfigobjectOptional

Additional configuration for user activation and data seeding

lastMonitoredAtstringOptional

Timestamp when this pool was last monitored

Example: 2025-01-01T12:00:00Z

currentProvisionRunIdstringOptional

Unique identifier for the current provision run

Example: run-123456

currentMonitorRunIdstringOptional

Unique identifier for the current monitor run

Example: mon-123456

defaultExpirationHoursnumberOptional

Default expiration hours for assigned sandboxes

Example: 168

extendedExpirationHoursnumberOptional

Extended expiration hours for assigned sandboxes

Example: 336

averageOrgCreationTimenumberOptional

Average time in minutes it takes to create a sandbox

Example: 45

lastProvisionedAtstringOptional

Timestamp when the last provision action was triggered

Example: 2025-01-01T12:00:00Z

minAvailableInstancesnumberRequired

Target number of AVAILABLE sandboxes

Example: 3

maxTotalInstancesnumberRequired

Hard cap for total sandboxes in this pool

Example: 10

refreshOrDeleteStrategystring · enumRequired

Strategy for handling expired sandboxes. DELETE_EXPIRED (recommended) - automatically delete expired sandboxes. AUTO_REFRESH_EXPIRED - automatically refresh expired sandboxes (uses more resources). FLAG_EXPIRED - mark expired sandboxes for manual refresh. NOTIFY_ONLY - only notify about expired sandboxes without taking action

Example: DELETE_EXPIREDPossible values:

refreshStrategystring · enumOptional

Refresh strategy for sandboxes

Example: ALWAYSPossible values:

refreshIntervalHoursnumberOptional

Interval in hours between sandbox refreshes (for STAGGER strategy)

Example: 24

minActiveInstancesnumberOptional

Minimum number of active instances to maintain

Example: 3

maxActiveInstancesnumberOptional

Maximum number of active instances allowed

Example: 10

minRetentionDaysnumberOptional

Minimum retention days for sandboxes

Example: 7

returnToPoolOnUnassignbooleanOptional

When true, unassigned sandboxes return to pool as AVAILABLE with reset timer. When false (default), they are marked as EXPIRED.

Example: false

metadataobjectOptional

Additional metadata for the pool configuration for custom filtering and tagging

Example: {"environment":"dev","team":"platform","region":"us-west"}

monitoringCronPatternstringOptional

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

Example: */30 * * * *

poolStatusstring · enumOptional

Pool lifecycle status. ACTIVE = normal operation, DELETING = cleanup in progress

Default: ACTIVEPossible values:

cleanupJobIdstringOptional

Job ID for the cleanup flow when poolStatus is DELETING

403

Forbidden - Requires role: owner, member, application

get/sfp/api/pools/configs

GET /sfp/api/pools/configs HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "repositoryIdentifier": "flxbl-io/sf-core",
    "name": "Development Pool",
    "poolTag": "dev-pool",
    "branchPattern": "feature/*",
    "devHubUsername": "devhub@example.com",
    "sandboxDefinition": {
      "autoActivate": true,
      "licenseType": "Developer",
      "description": "Dev sandbox for feature development",
      "sandboxName": [
        "DEV",
        "QA"
      ]
    },
    "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": "text"
  }
]

Create a new pool configuration

post

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

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

poolTypestring · enumOptional

Pool type: SANDBOX (default) or SCRATCH_ORG

Possible values:

Body

Responses

403

Forbidden - Requires role: owner, application

No content

default

Pool configuration created successfully

application/json

post/sfp/api/pools/configs

POST /sfp/api/pools/configs HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 694

{
  "repositoryIdentifier": "flxbl-io/sf-core",
  "name": "Development Pool",
  "poolTag": "dev-pool",
  "branchPattern": "feature/*",
  "devHubUsername": "devhub@example.com",
  "sandboxDefinition": {
    "autoActivate": true,
    "licenseType": "Developer",
    "description": "Dev sandbox for feature development",
    "sandboxName": [
      "DEV",
      "QA"
    ]
  },
  "minAvailableInstances": 3,
  "maxTotalInstances": 10,
  "daysToKeepUnassignedAvailable": 30,
  "refreshOrDeleteStrategy": "DELETE_EXPIRED",
  "isActive": true,
  "additionalConfig": {},
  "defaultExpirationHours": 24,
  "extendedExpirationHours": 168,
  "averageOrgCreationTime": 45,
  "returnToPoolOnUnassign": false,
  "monitoringCronPattern": "*/30 * * * *",
  "metadata": {
    "environment": "dev",
    "team": "platform",
    "region": "us-west"
  }
}

No content

Get a pool configuration

get

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

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

poolTagstringRequired

The tag of the pool to retrieve

Query parameters

repositoryIdentifierstringRequired

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

Example: flxbl-io/sf-core

poolTypestring · enumOptional

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

Possible values:

Responses

200

Pool configuration retrieved successfully

application/json

repositoryIdentifierstringRequired

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

Example: flxbl-io/sf-core

namestringRequired

User-friendly display name for the pool

Example: Development Pool

poolTagstringRequired

Unique machine-readable tag for this pool

Example: dev-pool

branchPatternstringOptional

Optional Git branch pattern this pool serves

Example: feature/*

devHubUsernamestringRequired

Registered Dev Hub alias/username

Example: devhub@example.com

sandboxDefinitionobjectOptional

Example:

{"autoActivate":true,"licenseType":"Developer","description":"Dev sandbox for feature development","sandboxName":["DEV","QA"]}

sourceSandboxNamestringOptionalDeprecated

Source sandbox name for cloning. Use this to clone from an existing sandbox instead of creating from production. Either use sandboxDefinition.sourceSandboxName or this field (deprecated)

Example: TEMPLATE_SB

daysToKeepUnassignedAvailablenumberRequired

TTL in days for available sandboxes before refresh/delete

Example: 30

isActivebooleanRequired

Whether this pool configuration is active for monitoring

Example: true

additionalConfigobjectOptional

Additional configuration for user activation and data seeding

lastMonitoredAtstringOptional

Timestamp when this pool was last monitored

Example: 2025-01-01T12:00:00Z

currentProvisionRunIdstringOptional

Unique identifier for the current provision run

Example: run-123456

currentMonitorRunIdstringOptional

Unique identifier for the current monitor run

Example: mon-123456

defaultExpirationHoursnumberOptional

Default expiration hours for assigned sandboxes

Example: 168

extendedExpirationHoursnumberOptional

Extended expiration hours for assigned sandboxes

Example: 336

averageOrgCreationTimenumberOptional

Average time in minutes it takes to create a sandbox

Example: 45

lastProvisionedAtstringOptional

Timestamp when the last provision action was triggered

Example: 2025-01-01T12:00:00Z

minAvailableInstancesnumberRequired

Target number of AVAILABLE sandboxes

Example: 3

maxTotalInstancesnumberRequired

Hard cap for total sandboxes in this pool

Example: 10

refreshOrDeleteStrategystring · enumRequired

Example: DELETE_EXPIREDPossible values:

refreshStrategystring · enumOptional

Refresh strategy for sandboxes

Example: ALWAYSPossible values:

refreshIntervalHoursnumberOptional

Interval in hours between sandbox refreshes (for STAGGER strategy)

Example: 24

minActiveInstancesnumberOptional

Minimum number of active instances to maintain

Example: 3

maxActiveInstancesnumberOptional

Maximum number of active instances allowed

Example: 10

minRetentionDaysnumberOptional

Minimum retention days for sandboxes

Example: 7

returnToPoolOnUnassignbooleanOptional

When true, unassigned sandboxes return to pool as AVAILABLE with reset timer. When false (default), they are marked as EXPIRED.

Example: false

metadataobjectOptional

Additional metadata for the pool configuration for custom filtering and tagging

Example: {"environment":"dev","team":"platform","region":"us-west"}

monitoringCronPatternstringOptional

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

Example: */30 * * * *

poolStatusstring · enumOptional

Pool lifecycle status. ACTIVE = normal operation, DELETING = cleanup in progress

Default: ACTIVEPossible values:

cleanupJobIdstringOptional

Job ID for the cleanup flow when poolStatus is DELETING

403

Forbidden - Requires role: owner, member, application

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

GET /sfp/api/pools/configs/{poolTag}?repositoryIdentifier=flxbl-io%2Fsf-core HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "repositoryIdentifier": "flxbl-io/sf-core",
  "name": "Development Pool",
  "poolTag": "dev-pool",
  "branchPattern": "feature/*",
  "devHubUsername": "devhub@example.com",
  "sandboxDefinition": {
    "autoActivate": true,
    "licenseType": "Developer",
    "description": "Dev sandbox for feature development",
    "sandboxName": [
      "DEV",
      "QA"
    ]
  },
  "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": "text"
}

Delete a pool configuration

delete

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.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

poolTagstringRequired

The tag of the pool to delete

Query parameters

repositoryIdentifierstringRequired

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

Example: flxbl-io/sf-core

Responses

403

Forbidden - Requires role: owner

No content

default

Pool deleted successfully

application/json

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

DELETE /sfp/api/pools/configs/{poolTag}?repositoryIdentifier=flxbl-io%2Fsf-core HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update a pool configuration

patch

Update an existing configuration for a sandbox or scratch org pool

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

poolTagstringRequired

The tag of the pool to update

Query parameters

repositoryIdentifierstringRequired

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

Example: flxbl-io/sf-core

poolTypestring · enumOptional

Pool type hint for routing (SANDBOX or SCRATCH_ORG)

Possible values:

Responses

403

Forbidden - Requires role: owner, application

No content

default

Pool configuration updated successfully

application/json

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

PATCH /sfp/api/pools/configs/{poolTag}?repositoryIdentifier=flxbl-io%2Fsf-core HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Get a pool's provisioning origin

get

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.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

poolTagstringRequired

The tag of the pool

Query parameters

repositoryIdentifierstringRequired

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

Example: flxbl-io/sf-core

poolTypestring · enumOptional

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

Possible values:

Responses

200

Provisioning origin resolved successfully

No content

403

Forbidden - Requires role: owner, member, application

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

GET /sfp/api/pools/configs/{poolTag}/provisioning-origin?repositoryIdentifier=flxbl-io%2Fsf-core HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

List pool tag collisions

get

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.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

repositoryIdentifierstringRequired

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

Example: flxbl-io/sf-core

Responses

200

Pool tags owned by more than one pool type (empty when the repository is clean)

No content

403

Forbidden - Requires role: owner, member, application

get/sfp/api/pools/collisions

GET /sfp/api/pools/collisions?repositoryIdentifier=flxbl-io%2Fsf-core HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Get pool status

get

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

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

repositoryIdentifierstringOptional

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

Example: flxbl-io/sf-core

poolTagstringOptional

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

instanceStatusstring · enumOptional

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

Possible values:

assignmentIdstringOptional

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

poolTypestring · enumOptional

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

Possible values:

refreshbooleanOptional

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

Responses

403

Forbidden - Requires role: owner, member, application

No content

default

Pool status retrieved successfully

application/json

get/sfp/api/pools/status

GET /sfp/api/pools/status HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Cleanup zombie sandbox instances

post

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

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

devHubUsernamestringRequired

DevHub username to check for zombies

Example: devhub_main_org

dryRunbooleanOptional

If true, only identify zombies without deleting them

Example: true

Responses

403

Forbidden - Requires role: owner

No content

default

Zombie cleanup completed

application/json

post/sfp/api/pools/cleanup-zombies

POST /sfp/api/pools/cleanup-zombies HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 50

{
  "devHubUsername": "devhub_main_org",
  "dryRun": true
}

No content

Get current sandbox service mode

get

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

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

Current mode information

application/json

modestring · enumOptionalPossible values:

descriptionstringOptional

mockModeEnvVarstringOptional

403

Forbidden - Requires role: owner, member, application

get/sfp/api/pools/mode

GET /sfp/api/pools/mode HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

Get pool monitoring status

get

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

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

Monitoring job status retrieved successfully

application/json

totalJobsnumberRequired

Total number of monitoring jobs

Example: 3

403

Forbidden - Requires role: owner, member, application

get/sfp/api/pools/monitoring-jobs

GET /sfp/api/pools/monitoring-jobs HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

Disables a pool monitoring cron schedule without deleting it.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

jobNamestringRequired

The monitoring job name (cron name)

Responses

200

Monitoring job paused

No content

403

Forbidden - Requires role: owner

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

POST /sfp/api/pools/monitoring-jobs/{jobName}/pause HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Resume a paused pool monitoring job

post

Re-enables a previously paused pool monitoring cron schedule.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

jobNamestringRequired

The monitoring job name (cron name)

Responses

200

Monitoring job resumed

No content

403

Forbidden - Requires role: owner

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

POST /sfp/api/pools/monitoring-jobs/{jobName}/resume HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

List pool instances

get

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

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

poolTagstringRequired

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

Example: core_dev or ci

Query parameters

repositoryIdentifierstringRequired

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

Example: flxbl-io/sf-core

poolTypestring · enumOptional

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

Possible values:

refreshbooleanOptional

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

Responses

200

List of pool instances (either SandboxPoolInstance or BasePoolInstance depending on pool type)

application/json

itemsone ofOptional

403

Forbidden - Requires role: owner, member, application

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

GET /sfp/api/pools/{poolTag}/instances?repositoryIdentifier=flxbl-io%2Fsf-core HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  null
]

Drain all instances from a pool (keeps pool config)

delete

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.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

poolTagstringRequired

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

Example: core_dev

Query parameters

repositoryIdentifierstringRequired

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

Example: flxbl-io/sf-core

Responses

202

Drain workflow dispatched

No content

403

Forbidden - Requires role: owner

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

DELETE /sfp/api/pools/{poolTag}/instances?repositoryIdentifier=flxbl-io%2Fsf-core HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Fetch and assign sandbox from pool

post

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.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

poolTagstringRequired

Pool tag to fetch sandbox from

Example: core_dev

Query parameters

repositoryIdentifierstringRequired

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

Example: flxbl-io/sf-core

Body

assignmentIdstringOptional

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

Example: 550e8400-e29b-41d4-a716-446655440000

aliasstring · max: 8Optional

User-selected alias for the sandbox assignment

Example: dev-a1b2

isImmortalbooleanOptional

If true, the sandbox will not expire automatically

Default: false

assignedToUserEmailstringOptional

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

Example: developer@example.com

createUserbooleanOptional

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

Default: false

Responses

403

Forbidden - Requires role: owner, member, application

No content

default

Instance successfully assigned (sandbox or scratch org)

application/json

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

POST /sfp/api/pools/{poolTag}/fetch?repositoryIdentifier=flxbl-io%2Fsf-core HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 158

{
  "assignmentId": "550e8400-e29b-41d4-a716-446655440000",
  "alias": "dev-a1b2",
  "isImmortal": false,
  "assignedToUserEmail": "developer@example.com",
  "createUser": false
}

No content

Unassign instance from user

post

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.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

poolTagstringRequired

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

Example: core_dev or ci

Query parameters

repositoryIdentifierstringRequired

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

Example: flxbl-io/sf-core

Body

sandboxIdstringOptional

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

Example: sb-123456

assignmentIdstringOptional

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

Example: 550e8400-e29b-41d4-a716-446655440000

returnToPoolbooleanOptional

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

Default: trueExample: true

Responses

403

Forbidden - Requires role: owner, application

No content

default

Instance unassigned successfully (sandbox or scratch org)

application/json

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

POST /sfp/api/pools/{poolTag}/unassign?repositoryIdentifier=flxbl-io%2Fsf-core HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 99

{
  "sandboxId": "sb-123456",
  "assignmentId": "550e8400-e29b-41d4-a716-446655440000",
  "returnToPool": true
}

No content

Provision users into a sandbox

post

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

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

poolTagstringRequired

Sandbox pool tag

Example: core_dev

instanceNamestringRequired

Sandbox instance name

Example: dev1

Query parameters

repositoryIdentifierstringRequired

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

Example: flxbl-io/sf-core

Body

sandboxNamestringRequired

Name of the sandbox to provision users into

Example: dev1

configNamestringOptional

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

Example: PO_ClientOpsconfig

Responses

202

User provisioning task dispatched

application/json

taskExecutionIdstringRequired

Task execution identifier

taskTypestringRequired

Task type

Example: provision-pool-users

statusstringRequired

Initial task status

Example: running

triggeredAtstringRequired

ISO 8601 dispatch timestamp

400

Invalid target

403

Forbidden - Requires role: owner, member, application

404

Sandbox pool or instance not found

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

POST /sfp/api/pools/{poolTag}/instances/{instanceName}/users?repositoryIdentifier=flxbl-io%2Fsf-core HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 151

{
  "sandboxName": "dev1",
  "configName": "PO_ClientOpsconfig",
  "users": [
    {
      "email": "developer@example.com",
      "accessLevel": "developer",
      "sendPasswordReset": true
    }
  ]
}

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

Regenerate sandbox SFDX auth URL

post

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.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

poolTagstringRequired

Sandbox pool tag where the instance belongs

Example: core_dev

Query parameters

repositoryIdentifierstringRequired

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

Example: flxbl-io/sf-core

Body

sandboxIdstringOptional

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

Example: sb-123456

sandboxNamestringOptional

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

Example: dev1

assignmentIdstringOptional

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

Example: 550e8400-e29b-41d4-a716-446655440000

Responses

200

SFDX auth URL regenerated successfully

application/json

statusstringRequired

Machine-readable operation status

Example: auth_url_regenerated

messagestringRequired

Human-readable operation result

Example: SFDX auth URL for sandbox dev1 has been regenerated.

timestampstringRequired

ISO timestamp when the API response was generated

Example: 2026-07-07T08:00:00.000Z

400

Invalid target or unsupported status

403

Forbidden - Requires role: owner, member, application

404

Sandbox pool or instance not found

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

POST /sfp/api/pools/{poolTag}/regenerate-auth-url?repositoryIdentifier=flxbl-io%2Fsf-core HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 100

{
  "sandboxId": "sb-123456",
  "sandboxName": "dev1",
  "assignmentId": "550e8400-e29b-41d4-a716-446655440000"
}

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

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.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

poolTagstringRequired

Pool tag where the sandbox belongs

Example: core_dev

Query parameters

repositoryIdentifierstringRequired

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

Example: flxbl-io/sf-core

Body

assignmentIdstringRequired

UUID of the assignment to extend

Example: 550e8400-e29b-41d4-a716-446655440000

extensionHoursnumber · min: 1 · max: 720Optional

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

Example: 24

isImmortalbooleanOptional

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

Example: true

Responses

403

Forbidden - Requires role: owner, member

No content

default

Expiry extended successfully (sandbox or scratch org)

application/json

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

POST /sfp/api/pools/{poolTag}/extend?repositoryIdentifier=flxbl-io%2Fsf-core HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 93

{
  "assignmentId": "550e8400-e29b-41d4-a716-446655440000",
  "extensionHours": 24,
  "isImmortal": true
}

No content

Trigger pool replenishment workflow

post

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.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

poolTagstringRequired

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

Example: core_dev

Query parameters

repositoryIdentifierstringRequired

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

Example: flxbl-io/sf-core

Responses

403

Forbidden - Requires role: owner

No content

default

Replenishment workflow initiated

application/json

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

POST /sfp/api/pools/{poolTag}/replenish?repositoryIdentifier=flxbl-io%2Fsf-core HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Delete an org instance from a pool

delete

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.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

poolTagstringRequired

Pool tag where the instance belongs

Example: core_dev

instanceNamestringRequired

Name/username of the org instance to delete

Example: test-abc@example.com

Query parameters

repositoryIdentifierstringRequired

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

Example: flxbl-io/sf-core

forcebooleanOptional

Force deletion even if instance is less than 24 hours old or is immortal

Example: true

Responses

200

Instance successfully deleted or marked for deletion

No content

400

Cannot delete instance (e.g., immortal instance without force flag)

403

Forbidden - Requires role: owner

404

Instance not found

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

DELETE /sfp/api/pools/{poolTag}/instances/{instanceName}?repositoryIdentifier=flxbl-io%2Fsf-core HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Last updated 20 hours ago

Was this helpful?