slackGitHub

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
Query parameters
repositoryIdentifierstringOptional

Repository identifier in format org/repo

Example: flxbl-io/sf-core
poolTypestring · enumOptional

Filter by pool type (SANDBOX or SCRATCH_ORG)

Possible values:
Responses
200

Pool configurations retrieved successfully

application/json
get
GET /sfp/api/pools/configs HTTP/1.1
Host: 
Authorization: Bearer JWT
Accept: */*
200

Pool configurations retrieved successfully

[
  {
    "repositoryIdentifier": "flxbl-io/sf-core",
    "name": "Development Pool",
    "poolTag": "dev-pool",
    "branchPattern": "feature/*",
    "devHubUsername": "[email protected]",
    "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"
    }
  }
]

Create a new sandbox pool configuration

post

Create a new configuration for a sandbox pool (Note: Scratch org pools are discovered automatically from DevHub)

Authorizations
Body
repositoryIdentifierstringRequired

Repository identifier in format org/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: [email protected]
sandboxDefinitionobjectOptional

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

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

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

Example: TEMPLATE_SB
minAvailableInstancesnumberRequired

Target number of AVAILABLE sandboxes

Example: 3
maxTotalInstancesnumberRequired

Hard cap for total sandboxes in this pool

Example: 10
daysToKeepUnassignedAvailablenumberRequired

TTL in days for available sandboxes before refresh/delete

Example: 30
refreshOrDeleteStrategystring · enumRequired

Strategy for handling expired sandboxes

Example: DELETE_EXPIREDPossible values:
isActivebooleanRequired

Whether this pool configuration is active for monitoring

Example: true
additionalConfigobjectOptional

Additional configuration for user activation and data seeding

defaultExpirationHoursnumberOptional

Default expiration hours for assigned sandboxes

Default: 24Example: 24
extendedExpirationHoursnumberOptional

Extended expiration hours for assigned sandboxes

Example: 168
averageOrgCreationTimenumberOptional

Average time in minutes it takes to create a sandbox

Example: 45
returnToPoolOnUnassignbooleanOptional

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

Default: falseExample: false
metadataobjectOptional

Additional metadata for the pool configuration for custom filtering and tagging

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

Pool configuration created successfully

application/json
ResponseanyExample: {"accountId":"org-123","name":"Core Development Pool","poolTag":"core_dev","devHubUsername":"[email protected]","sandboxDefinition":{"autoActivate":true,"licenseType":"Developer","sandboxName":["DEV","CORE"],"description":"Development sandbox for core features"},"minAvailableInstances":3,"maxTotalInstances":10,"daysToKeepUnassignedAvailable":3,"refreshOrDeleteStrategy":"DELETE_EXPIRED","defaultExpirationHours":48,"isActive":true,"additionalConfig":{"usersToActivate":["[email protected]"],"dataSeedPlan":"standard"},"lastMonitoredAt":"2025-01-01T12:00:00Z","currentProvisionRunId":"prov-123456","currentMonitorRunId":"mon-123456"}
post
POST /sfp/api/pools/configs HTTP/1.1
Host: 
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 655

{
  "repositoryIdentifier": "flxbl-io/sf-core",
  "name": "Development Pool",
  "poolTag": "dev-pool",
  "branchPattern": "feature/*",
  "devHubUsername": "[email protected]",
  "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,
  "metadata": {
    "environment": "dev",
    "team": "platform",
    "region": "us-west"
  }
}
default

Pool configuration created successfully

{
  "accountId": "org-123",
  "name": "Core Development Pool",
  "poolTag": "core_dev",
  "devHubUsername": "[email protected]",
  "sandboxDefinition": {
    "autoActivate": true,
    "licenseType": "Developer",
    "sandboxName": [
      "DEV",
      "CORE"
    ],
    "description": "Development sandbox for core features"
  },
  "minAvailableInstances": 3,
  "maxTotalInstances": 10,
  "daysToKeepUnassignedAvailable": 3,
  "refreshOrDeleteStrategy": "DELETE_EXPIRED",
  "defaultExpirationHours": 48,
  "isActive": true,
  "additionalConfig": {
    "usersToActivate": [
      "[email protected]"
    ],
    "dataSeedPlan": "standard"
  },
  "lastMonitoredAt": "2025-01-01T12:00:00Z",
  "currentProvisionRunId": "prov-123456",
  "currentMonitorRunId": "mon-123456"
}

Get a pool configuration

get

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

Authorizations
Path parameters
poolTagstringRequired

The tag of the pool to retrieve

Query parameters
repositoryIdentifierstringRequired

Repository identifier in format org/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
get
GET /sfp/api/pools/configs/{poolTag}?repositoryIdentifier=flxbl-io%2Fsf-core HTTP/1.1
Host: 
Authorization: Bearer JWT
Accept: */*
200

Pool configuration retrieved successfully

{
  "repositoryIdentifier": "flxbl-io/sf-core",
  "name": "Development Pool",
  "poolTag": "dev-pool",
  "branchPattern": "feature/*",
  "devHubUsername": "[email protected]",
  "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"
  }
}

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
Path parameters
poolTagstringRequired

The tag of the pool to delete

Query parameters
repositoryIdentifierstringRequired

Repository identifier in format org/repo

Example: flxbl-io/sf-core
Responses
default

Pool deleted successfully

application/json
ResponseanyExample: {"status":"deleted","message":"Pool configuration 'core_dev' deleted successfully.","timestamp":"2025-01-01T12:00:00Z"}
delete
DELETE /sfp/api/pools/configs/{poolTag}?repositoryIdentifier=flxbl-io%2Fsf-core HTTP/1.1
Host: 
Authorization: Bearer JWT
Accept: */*
default

Pool deleted successfully

{
  "status": "deleted",
  "message": "Pool configuration 'core_dev' deleted successfully.",
  "timestamp": "2025-01-01T12:00:00Z"
}

Update a sandbox pool configuration

patch

Update an existing configuration for a sandbox pool

Authorizations
Path parameters
poolTagstringRequired

The tag of the pool to update

Query parameters
repositoryIdentifierstringRequired

Repository identifier in format org/repo

Example: flxbl-io/sf-core
Body
namestringOptional

User-friendly display name for the pool

Example: Development Pool
branchPatternstringOptional

Optional Git branch pattern this pool serves

Example: feature/*
devHubUsernamestringOptional

Registered Dev Hub alias/username

Example: [email protected]
sandboxDefinitionobjectOptional

Sandbox definition configuration

sourceSandboxNamestringOptionalDeprecated

Source sandbox name for cloning (deprecated)

Example: TEMPLATE_SB
minAvailableInstancesnumberOptional

Target number of AVAILABLE sandboxes

Example: 3
maxTotalInstancesnumberOptional

Hard cap for total sandboxes in this pool

Example: 10
daysToKeepUnassignedAvailablenumberOptional

TTL in days for available sandboxes before refresh/delete

Example: 30
refreshOrDeleteStrategystring · enumOptional

Strategy for handling expired sandboxes

Example: DELETE_EXPIREDPossible values:
isActivebooleanOptional

Whether this pool configuration is active for monitoring

Example: true
additionalConfigobjectOptional

Additional configuration for user activation and data seeding

defaultExpirationHoursnumberOptional

Default expiration hours for assigned sandboxes

Example: 24
extendedExpirationHoursnumberOptional

Extended expiration hours for assigned sandboxes

Example: 168
averageOrgCreationTimenumberOptional

Average time in minutes it takes to create a sandbox

Example: 45
returnToPoolOnUnassignbooleanOptional

When true, unassigned sandboxes return to pool as AVAILABLE. When false, 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"}
Responses
default

Pool configuration updated successfully

application/json
ResponseanyExample: {"accountId":"org-123","name":"Core Development Pool","poolTag":"core_dev","devHubUsername":"[email protected]","sandboxDefinition":{"autoActivate":true,"licenseType":"Developer","sandboxName":["DEV","CORE"],"description":"Development sandbox for core features"},"minAvailableInstances":3,"maxTotalInstances":10,"daysToKeepUnassignedAvailable":3,"refreshOrDeleteStrategy":"DELETE_EXPIRED","defaultExpirationHours":48,"isActive":true,"additionalConfig":{"usersToActivate":["[email protected]"],"dataSeedPlan":"standard"},"lastMonitoredAt":"2025-01-01T12:00:00Z","currentProvisionRunId":"prov-123456","currentMonitorRunId":"mon-123456"}
patch
PATCH /sfp/api/pools/configs/{poolTag}?repositoryIdentifier=flxbl-io%2Fsf-core HTTP/1.1
Host: 
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 468

{
  "name": "Development Pool",
  "branchPattern": "feature/*",
  "devHubUsername": "[email protected]",
  "sandboxDefinition": {},
  "minAvailableInstances": 3,
  "maxTotalInstances": 10,
  "daysToKeepUnassignedAvailable": 30,
  "refreshOrDeleteStrategy": "DELETE_EXPIRED",
  "isActive": true,
  "additionalConfig": {},
  "defaultExpirationHours": 24,
  "extendedExpirationHours": 168,
  "averageOrgCreationTime": 45,
  "returnToPoolOnUnassign": false,
  "metadata": {
    "environment": "dev",
    "team": "platform",
    "region": "us-west"
  }
}
default

Pool configuration updated successfully

{
  "accountId": "org-123",
  "name": "Core Development Pool",
  "poolTag": "core_dev",
  "devHubUsername": "[email protected]",
  "sandboxDefinition": {
    "autoActivate": true,
    "licenseType": "Developer",
    "sandboxName": [
      "DEV",
      "CORE"
    ],
    "description": "Development sandbox for core features"
  },
  "minAvailableInstances": 3,
  "maxTotalInstances": 10,
  "daysToKeepUnassignedAvailable": 3,
  "refreshOrDeleteStrategy": "DELETE_EXPIRED",
  "defaultExpirationHours": 48,
  "isActive": true,
  "additionalConfig": {
    "usersToActivate": [
      "[email protected]"
    ],
    "dataSeedPlan": "standard"
  },
  "lastMonitoredAt": "2025-01-01T12:00:00Z",
  "currentProvisionRunId": "prov-123456",
  "currentMonitorRunId": "mon-123456"
}

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
Query parameters
repositoryIdentifierstringOptional

Repository identifier in format org/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
default

Pool status retrieved successfully

application/json
ResponseanyExample: {"poolTag":"core_dev","poolType":"SANDBOX","repositoryIdentifier":"flxbl-io/sf-core","status":"active","instances":[{"id":"sb-core-dev-123456","poolTag":"core_dev","type":"SANDBOX","status":"AVAILABLE","salesforceOrgId":"00D000000000001","instanceUrl":"https://test-sandbox.sandbox.my.salesforce.com","loginUrl":"https://test.salesforce.com","lastKnownDevHubUsername":"[email protected]","createdInSalesforceAt":"2025-01-01T10:00:00Z","sandboxName":"dev123456","poolConfigKey":"core_dev","provisionRunId":"prov-123456","lastActivityAt":"2025-01-01T12:00:00Z","assignmentId":"550e8400-e29b-41d4-a716-446655440000","assignedToUserEmail":"[email protected]","assignedAt":"2025-01-01T11:00:00Z","expiresAt":"2025-01-03T11:00:00Z","isImmortal":false,"salesforceStatusRaw":{"Id":"00D000000000001","SandboxName":"dev123456","Status":"Completed","LicenseType":"Developer","CreatedDate":"2025-01-01T10:00:00Z","Description":"CORE_DEV DEV 123456 | SFP Server Pool"}}],"statistics":{"total":5,"available":3,"assigned":1,"provisioning":1,"activating":0,"error":0,"expired":0,"deleting":0,"refreshing":0,"flaggedForRefresh":0},"config":{"accountId":"org-123","name":"Core Development Pool","poolTag":"core_dev","devHubUsername":"[email protected]","sandboxDefinition":{"autoActivate":true,"licenseType":"Developer","sandboxName":["DEV","CORE"],"description":"Development sandbox for core features"},"minAvailableInstances":3,"maxTotalInstances":10,"daysToKeepUnassignedAvailable":3,"refreshOrDeleteStrategy":"DELETE_EXPIRED","defaultExpirationHours":48,"isActive":true,"additionalConfig":{"usersToActivate":["[email protected]"],"dataSeedPlan":"standard"},"lastMonitoredAt":"2025-01-01T12:00:00Z","currentProvisionRunId":"prov-123456","currentMonitorRunId":"mon-123456"}}
get
GET /sfp/api/pools/status HTTP/1.1
Host: 
Authorization: Bearer JWT
Accept: */*
default

Pool status retrieved successfully

{
  "poolTag": "core_dev",
  "poolType": "SANDBOX",
  "repositoryIdentifier": "flxbl-io/sf-core",
  "status": "active",
  "instances": [
    {
      "id": "sb-core-dev-123456",
      "poolTag": "core_dev",
      "type": "SANDBOX",
      "status": "AVAILABLE",
      "salesforceOrgId": "00D000000000001",
      "instanceUrl": "https://test-sandbox.sandbox.my.salesforce.com",
      "loginUrl": "https://test.salesforce.com",
      "lastKnownDevHubUsername": "[email protected]",
      "createdInSalesforceAt": "2025-01-01T10:00:00Z",
      "sandboxName": "dev123456",
      "poolConfigKey": "core_dev",
      "provisionRunId": "prov-123456",
      "lastActivityAt": "2025-01-01T12:00:00Z",
      "assignmentId": "550e8400-e29b-41d4-a716-446655440000",
      "assignedToUserEmail": "[email protected]",
      "assignedAt": "2025-01-01T11:00:00Z",
      "expiresAt": "2025-01-03T11:00:00Z",
      "isImmortal": false,
      "salesforceStatusRaw": {
        "Id": "00D000000000001",
        "SandboxName": "dev123456",
        "Status": "Completed",
        "LicenseType": "Developer",
        "CreatedDate": "2025-01-01T10:00:00Z",
        "Description": "CORE_DEV DEV 123456 | SFP Server Pool"
      }
    }
  ],
  "statistics": {
    "total": 5,
    "available": 3,
    "assigned": 1,
    "provisioning": 1,
    "activating": 0,
    "error": 0,
    "expired": 0,
    "deleting": 0,
    "refreshing": 0,
    "flaggedForRefresh": 0
  },
  "config": {
    "accountId": "org-123",
    "name": "Core Development Pool",
    "poolTag": "core_dev",
    "devHubUsername": "[email protected]",
    "sandboxDefinition": {
      "autoActivate": true,
      "licenseType": "Developer",
      "sandboxName": [
        "DEV",
        "CORE"
      ],
      "description": "Development sandbox for core features"
    },
    "minAvailableInstances": 3,
    "maxTotalInstances": 10,
    "daysToKeepUnassignedAvailable": 3,
    "refreshOrDeleteStrategy": "DELETE_EXPIRED",
    "defaultExpirationHours": 48,
    "isActive": true,
    "additionalConfig": {
      "usersToActivate": [
        "[email protected]"
      ],
      "dataSeedPlan": "standard"
    },
    "lastMonitoredAt": "2025-01-01T12:00:00Z",
    "currentProvisionRunId": "prov-123456",
    "currentMonitorRunId": "mon-123456"
  }
}

Cleanup zombie sandbox instances

post

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

Authorizations
Body
devHubUsernamestringRequired

DevHub username to check for zombies

Example: devhub_main_org
dryRunbooleanOptional

If true, only identify zombies without deleting them

Example: true
Responses
default

Zombie cleanup completed

application/json
ResponseanyExample: {"message":"Found 3 orphaned instances. Run with dryRun=false to delete them.","orphanedInstances":[{"sandboxName":"DEV123","poolTag":"core_dev","status":"AVAILABLE","reason":"Not found in Salesforce"}],"dryRun":true}
post
POST /sfp/api/pools/cleanup-zombies HTTP/1.1
Host: 
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 50

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

Zombie cleanup completed

{
  "message": "Found 3 orphaned instances. Run with dryRun=false to delete them.",
  "orphanedInstances": [
    {
      "sandboxName": "DEV123",
      "poolTag": "core_dev",
      "status": "AVAILABLE",
      "reason": "Not found in Salesforce"
    }
  ],
  "dryRun": true
}

Get current sandbox service mode

get

Returns whether the system is using mock or real Salesforce sandbox service

Authorizations
Responses
200

Current mode information

application/json
get
GET /sfp/api/pools/mode HTTP/1.1
Host: 
Authorization: Bearer JWT
Accept: */*
200

Current mode information

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

Get pool monitoring status

get

Retrieve information about all repository-specific pool monitoring jobs

Authorizations
Responses
200

Monitoring job status retrieved successfully

application/json
get
GET /sfp/api/pools/monitoring-jobs HTTP/1.1
Host: 
Authorization: Bearer JWT
Accept: */*
200

Monitoring job status retrieved successfully

{
  "totalJobs": 3,
  "jobs": [
    {
      "jobName": "global-pool-monitor",
      "description": "Global pool monitoring job that monitors all active pools",
      "pattern": "*/30 * * * *",
      "nextRun": "2024-01-01T12:30:00Z",
      "lastRun": "2024-01-01T12:00:00Z",
      "running": false
    }
  ]
}

List pool instances

get

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

Authorizations
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

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
get
GET /sfp/api/pools/{poolTag}/instances?repositoryIdentifier=flxbl-io%2Fsf-core HTTP/1.1
Host: 
Authorization: Bearer JWT
Accept: */*
200

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

[
  null
]

Provision sandbox pool instances

post

Create new sandbox instances for a specific pool or all pools to meet target capacity. (Note: Only works for sandbox pools)

Authorizations
Path parameters
poolTagstringRequired

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

Example: core_dev
Query parameters
repositoryIdentifierstringRequired

Repository identifier in format org/repo

Example: flxbl-io/sf-core
Responses
default

Provisioning started successfully

application/json
ResponseanyExample: {"status":"provisioning_started","message":"Provisioning 3 new instances for pool core_dev","timestamp":"2025-01-01T12:00:00Z","details":{"poolCapacity":5,"availableInstances":1,"provisioningInstances":4,"instancesToBeCreated":0}}
post
POST /sfp/api/pools/{poolTag}/provision?repositoryIdentifier=flxbl-io%2Fsf-core HTTP/1.1
Host: 
Authorization: Bearer JWT
Accept: */*
default

Provisioning started successfully

{
  "status": "provisioning_started",
  "message": "Provisioning 3 new instances for pool core_dev",
  "timestamp": "2025-01-01T12:00:00Z",
  "details": {
    "poolCapacity": 5,
    "availableInstances": 1,
    "provisioningInstances": 4,
    "instancesToBeCreated": 0
  }
}

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
Path parameters
poolTagstringRequired

Pool tag to fetch sandbox from

Example: core_dev
Query parameters
repositoryIdentifierstringRequired

Repository identifier in format org/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
isImmortalbooleanOptional

If true, the sandbox will not expire automatically

Default: false
Responses
default

Instance successfully assigned (sandbox or scratch org)

application/json
ResponseanyExample: {"value":{"status":"sandbox_assigned","message":"Sandbox successfully assigned","timestamp":"2025-01-01T12:00:00Z","details":{"sandboxId":"sb-core-dev-123456","sandboxName":"dev123456","instanceUrl":"https://test-sandbox.sandbox.my.salesforce.com","loginUrl":"https://test.salesforce.com","expiresAt":"2025-01-03T12:00:00Z","isReused":false,"sfdxAuthUrl":"force://PlatformCLI::[email protected]"}}}
post
POST /sfp/api/pools/{poolTag}/fetch?repositoryIdentifier=flxbl-io%2Fsf-core HTTP/1.1
Host: 
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 74

{
  "assignmentId": "550e8400-e29b-41d4-a716-446655440000",
  "isImmortal": false
}
default

Instance successfully assigned (sandbox or scratch org)

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

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
Responses
default

Instance unassigned successfully (sandbox or scratch org)

application/json
ResponseanyExample: {"value":{"status":"unassigned","message":"Sandbox successfully unassigned and returned to pool","timestamp":"2025-01-01T12:00:00Z","details":{"sandboxId":"sb-core-dev-123456","sandboxName":"dev123456","poolTag":"core_dev"}}}
post
POST /sfp/api/pools/{poolTag}/unassign?repositoryIdentifier=flxbl-io%2Fsf-core HTTP/1.1
Host: 
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 79

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

Instance unassigned successfully (sandbox or scratch org)

No content

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
Path parameters
poolTagstringRequired

Pool tag where the sandbox belongs

Example: core_dev
Query parameters
repositoryIdentifierstringRequired

Repository identifier in format org/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
default

Expiry extended successfully

application/json
ResponseanyExample: {"status":"expiry_extended","message":"Sandbox expiry extended successfully","timestamp":"2025-01-01T12:00:00Z","details":{"sandboxId":"sb-core-dev-123456","sandboxName":"dev123456","newExpiresAt":"2025-01-05T12:00:00Z","extensionHours":48}}
post
POST /sfp/api/pools/{poolTag}/extend?repositoryIdentifier=flxbl-io%2Fsf-core HTTP/1.1
Host: 
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 93

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

Expiry extended successfully

{
  "status": "expiry_extended",
  "message": "Sandbox expiry extended successfully",
  "timestamp": "2025-01-01T12:00:00Z",
  "details": {
    "sandboxId": "sb-core-dev-123456",
    "sandboxName": "dev123456",
    "newExpiresAt": "2025-01-05T12:00:00Z",
    "extensionHours": 48
  }
}

Run complete pool replenishment workflow

post

Performs the complete pool maintenance workflow including reconciliation with Salesforce, lifecycle processing (expiration/deletion), and quota maintenance (provisioning). This endpoint can be called manually by clients or triggered by server-side cron jobs.

Authorizations
Path parameters
poolTagstringRequired

The unique tag of the pool

Example: core_dev
Query parameters
repositoryIdentifierstringRequired

Repository identifier in format org/repo

Example: flxbl-io/sf-core
Responses
default

Replenishment workflow initiated

application/json
ResponseanyExample: {"poolTag":"core_dev","steps":{"reconciliation":{"success":true,"message":"State reconciliation completed successfully","duration":245},"lifecycleProcessing":{"success":true,"message":"Lifecycle processing completed successfully","duration":1523},"quotaMaintenance":{"success":true,"message":"Quota maintenance completed. 2 instances will be created.","availableInstances":1,"errorInstances":0,"instancesToBeCreated":2,"duration":342}},"summary":"Replenishment completed successfully. Reconciliation: ✓, Lifecycle: ✓, Quota: ✓ (2 new instances)","totalDuration":2110}
post
POST /sfp/api/pools/{poolTag}/replenish?repositoryIdentifier=flxbl-io%2Fsf-core HTTP/1.1
Host: 
Authorization: Bearer JWT
Accept: */*
default

Replenishment workflow initiated

{
  "poolTag": "core_dev",
  "steps": {
    "reconciliation": {
      "success": true,
      "message": "State reconciliation completed successfully",
      "duration": 245
    },
    "lifecycleProcessing": {
      "success": true,
      "message": "Lifecycle processing completed successfully",
      "duration": 1523
    },
    "quotaMaintenance": {
      "success": true,
      "message": "Quota maintenance completed. 2 instances will be created.",
      "availableInstances": 1,
      "errorInstances": 0,
      "instancesToBeCreated": 2,
      "duration": 342
    }
  },
  "summary": "Replenishment completed successfully. Reconciliation: ✓, Lifecycle: ✓, Quota: ✓ (2 new instances)",
  "totalDuration": 2110
}

Force delete a sandbox instance

delete

Forcefully delete a sandbox instance from the pool. This is an admin operation that bypasses normal lifecycle checks and should be used carefully. For instances in ERROR status, the database entry will be deleted even if Salesforce deletion fails, allowing the pool to replenish. For other statuses, use the force flag to delete regardless of Salesforce results.

Authorizations
Path parameters
poolTagstringRequired

Pool tag where the sandbox belongs

Example: core_dev
sandboxNamestringRequired

Name of the sandbox to delete

Example: 123456
Query parameters
repositoryIdentifierstringRequired

Repository identifier in format org/repo

Example: flxbl-io/sf-core
forcebooleanOptional

Force deletion even if sandbox is less than 24 hours old

Example: true
Responses
200

Sandbox successfully deleted or marked for deletion

application/json
delete
DELETE /sfp/api/pools/{poolTag}/instances/{sandboxName}?repositoryIdentifier=flxbl-io%2Fsf-core HTTP/1.1
Host: 
Authorization: Bearer JWT
Accept: */*

{
  "status": "text",
  "message": "text",
  "timestamp": "text",
  "details": {
    "sandboxName": "text",
    "previousStatus": "text",
    "isImmortal": true,
    "createdAt": "text",
    "deletionType": "immediate"
  }
}