> For the complete documentation index, see [llms.txt](https://docs.flxbl.io/flxbl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flxbl.io/flxbl/sfp-server/api-reference/pools.md).

# Pools

## Get all pool configurations

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"SandboxPoolConfigDto":{"type":"object","properties":{"repositoryIdentifier":{"type":"string","description":"Repository identifier in format org/repo or org/project/repo"},"name":{"type":"string","description":"User-friendly display name for the pool"},"poolTag":{"type":"string","description":"Unique machine-readable tag for this pool"},"branchPattern":{"type":"string","description":"Optional Git branch pattern this pool serves"},"devHubUsername":{"type":"string","description":"Registered Dev Hub alias/username"},"sandboxDefinition":{"type":"object","description":"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)"},"sourceSandboxName":{"type":"string","description":"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)","deprecated":true},"daysToKeepUnassignedAvailable":{"type":"number","description":"TTL in days for available sandboxes before refresh/delete"},"isActive":{"type":"boolean","description":"Whether this pool configuration is active for monitoring"},"additionalConfig":{"type":"object","description":"Additional configuration for user activation and data seeding"},"lastMonitoredAt":{"type":"string","description":"Timestamp when this pool was last monitored"},"currentProvisionRunId":{"type":"string","description":"Unique identifier for the current provision run"},"currentMonitorRunId":{"type":"string","description":"Unique identifier for the current monitor run"},"defaultExpirationHours":{"type":"number","description":"Default expiration hours for assigned sandboxes"},"extendedExpirationHours":{"type":"number","description":"Extended expiration hours for assigned sandboxes"},"averageOrgCreationTime":{"type":"number","description":"Average time in minutes it takes to create a sandbox"},"lastProvisionedAt":{"type":"string","description":"Timestamp when the last provision action was triggered"},"minAvailableInstances":{"type":"number","description":"Target number of AVAILABLE sandboxes"},"maxTotalInstances":{"type":"number","description":"Hard cap for total sandboxes in this pool"},"refreshOrDeleteStrategy":{"type":"string","description":"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","enum":["DELETE_EXPIRED","AUTO_REFRESH_EXPIRED","FLAG_EXPIRED","NOTIFY_ONLY"]},"refreshStrategy":{"type":"string","description":"Refresh strategy for sandboxes","enum":["ALWAYS","NEVER","STAGGER"]},"refreshIntervalHours":{"type":"number","description":"Interval in hours between sandbox refreshes (for STAGGER strategy)"},"minActiveInstances":{"type":"number","description":"Minimum number of active instances to maintain"},"maxActiveInstances":{"type":"number","description":"Maximum number of active instances allowed"},"minRetentionDays":{"type":"number","description":"Minimum retention days for sandboxes"},"returnToPoolOnUnassign":{"type":"boolean","description":"When true, unassigned sandboxes return to pool as AVAILABLE with reset timer. When false (default), they are marked as EXPIRED."},"metadata":{"type":"object","description":"Additional metadata for the pool configuration for custom filtering and tagging"},"monitoringCronPattern":{"type":"string","description":"Cron pattern for monitoring schedule (5-field standard cron)"},"poolStatus":{"type":"string","description":"Pool lifecycle status. ACTIVE = normal operation, DELETING = cleanup in progress","enum":["ACTIVE","DELETING"],"default":"ACTIVE"},"cleanupJobId":{"type":"string","description":"Job ID for the cleanup flow when poolStatus is DELETING"}},"required":["repositoryIdentifier","name","poolTag","devHubUsername","daysToKeepUnassignedAvailable","isActive","minAvailableInstances","maxTotalInstances","refreshOrDeleteStrategy"]}}},"paths":{"/sfp/api/pools/configs":{"get":{"operationId":"PoolConfigController_getAllPoolConfigs","summary":"Get all pool configurations","description":"Retrieve all pool configurations (both sandbox and scratch org pools), optionally filtered by repository and/or pool type","parameters":[{"name":"repositoryIdentifier","required":false,"in":"query","description":"Repository identifier in format org/repo or org/project/repo","schema":{"type":"string"}},{"name":"poolType","required":false,"in":"query","description":"Filter by pool type (SANDBOX or SCRATCH_ORG)","schema":{"enum":["SANDBOX","SCRATCH_ORG"],"type":"string"}},{"name":"hasAssignmentRules","required":false,"in":"query","description":"Filter by assignment rules: true = only pools with rules, false = only pools without rules (no branchPattern or domainPatterns)","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Pool configurations retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SandboxPoolConfigDto"}}}}},"403":{"description":"Forbidden - Requires role: owner, member, application"}},"tags":["Pools"]}}}}
```

## Create a new pool configuration

> Create a new configuration for a sandbox or scratch org pool. Use poolType=SCRATCH\_ORG for scratch org pools.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"CreateSandboxPoolConfigDto":{"type":"object","properties":{"repositoryIdentifier":{"type":"string","description":"Repository identifier in format org/repo or org/project/repo"},"name":{"type":"string","description":"User-friendly display name for the pool"},"poolTag":{"type":"string","description":"Unique machine-readable tag for this pool. Must be lowercase."},"branchPattern":{"type":"string","description":"Optional Git branch pattern this pool serves"},"devHubUsername":{"type":"string","description":"Registered Dev Hub alias/username"},"sandboxDefinition":{"type":"object","description":"Sandbox definition configuration. Either specify licenseType to create from production OR sourceSandboxName to clone an existing sandbox"},"sourceSandboxName":{"type":"string","description":"Source sandbox name for cloning (deprecated - use sandboxDefinition.sourceSandboxName)","deprecated":true},"minAvailableInstances":{"type":"number","description":"Target number of AVAILABLE sandboxes"},"maxTotalInstances":{"type":"number","description":"Hard cap for total sandboxes in this pool"},"daysToKeepUnassignedAvailable":{"type":"number","description":"TTL in days for available sandboxes before refresh/delete"},"refreshOrDeleteStrategy":{"type":"string","description":"Strategy for handling expired sandboxes","enum":["DELETE_EXPIRED","AUTO_REFRESH_EXPIRED","FLAG_EXPIRED","NOTIFY_ONLY"]},"isActive":{"type":"boolean","description":"Whether this pool configuration is active for monitoring"},"additionalConfig":{"type":"object","description":"Additional configuration for user activation and data seeding"},"defaultExpirationHours":{"type":"number","description":"Default expiration hours for assigned sandboxes","default":24},"extendedExpirationHours":{"type":"number","description":"Extended expiration hours for assigned sandboxes"},"averageOrgCreationTime":{"type":"number","description":"Average time in minutes it takes to create a sandbox"},"returnToPoolOnUnassign":{"type":"boolean","description":"When true, unassigned sandboxes return to pool as AVAILABLE. When false, they are marked as EXPIRED","default":false},"monitoringCronPattern":{"type":"string","description":"Cron pattern for monitoring schedule (5-field standard cron)","default":"*/30 * * * *"},"metadata":{"type":"object","description":"Additional metadata for the pool configuration for custom filtering and tagging"}},"required":["repositoryIdentifier","name","poolTag","devHubUsername","minAvailableInstances","maxTotalInstances","daysToKeepUnassignedAvailable","refreshOrDeleteStrategy","isActive"]},"CreateScratchOrgPoolConfigDto":{"type":"object","properties":{"repositoryIdentifier":{"type":"string","description":"Repository identifier in format org/repo or org/project/repo"},"poolTag":{"type":"string","description":"Unique machine-readable tag for this pool. Must be lowercase."},"name":{"type":"string","description":"User-friendly display name for the pool"},"devHubUsername":{"type":"string","description":"Registered Dev Hub alias/username"},"branch":{"type":"string","description":"Git branch this pool targets"},"isActive":{"type":"boolean","description":"Whether this pool configuration is active"},"maxAllocation":{"type":"number","description":"Maximum number of scratch orgs to allocate"},"minAvailableInstances":{"type":"number","description":"Minimum available instances floor for replenishment"},"expiry":{"type":"number","description":"Scratch org expiry in days (Salesforce org expiry)","default":2},"defaultExpirationHours":{"type":"number","description":"Default assignment expiration hours","default":24},"returnToPoolOnUnassign":{"type":"boolean","description":"When true, scratch orgs return to AVAILABLE when assignment expires (if Salesforce lifetime remaining). When false, they are marked EXPIRED.","default":false},"daysToKeepUnassignedAvailable":{"type":"number","description":"Days to keep unassigned scratch orgs available (capped at Salesforce org expiry)"},"configFilePath":{"type":"string","description":"Path to scratch org definition file","default":"config/project-scratch-def.json"},"batchSize":{"type":"number","description":"Number of scratch orgs to create in each batch","default":5},"waitTime":{"type":"number","description":"Wait time in minutes for scratch org creation","default":6},"maxRetryCount":{"type":"number","description":"Maximum retry count for failed operations","default":2},"installAll":{"type":"boolean","description":"Install all packages in the repository"},"enableSourceTracking":{"type":"boolean","description":"Enable source tracking on scratch orgs"},"succeedOnDeploymentErrors":{"type":"boolean","description":"Whether to submit orgs to pool even on deployment errors"},"releaseConfigFile":{"type":"string","description":"Path to release config file"},"keys":{"type":"string","description":"Keys for unlocked packages"},"relaxAllIPRanges":{"type":"boolean","description":"Relax all IP ranges on scratch orgs"},"ipRangesToBeRelaxed":{"description":"Specific IP ranges to relax","type":"array","items":{"type":"string"}},"retryOnFailure":{"type":"boolean","description":"Retry on failure during prepare"},"fetchArtifacts":{"type":"object","description":"Artifact fetch configuration. Set to true to use internal server registry, or provide object with script/npm config."},"disableSourcePackageOverride":{"type":"boolean","description":"Disable source package override"},"snapshotPool":{"type":"string","description":"Snapshot pool to clone from"},"postDeploymentScriptPath":{"type":"string","description":"Path to post-deployment script"},"preDependencyInstallationScriptPath":{"type":"string","description":"Path to pre-dependency installation script"},"enableVlocity":{"type":"boolean","description":"Enable Vlocity configuration"},"noAnchestors":{"type":"boolean","description":"Skip ancestor checking for unlocked packages"},"monitoringCronPattern":{"type":"string","description":"Cron pattern for monitoring schedule (5-field standard cron)","default":"*/30 * * * *"},"provisioningCronPattern":{"type":"string","description":"Cron pattern for provisioning schedule (5-field standard cron)","default":"0 */2 * * *"},"metadata":{"type":"object","description":"Additional metadata"}},"required":["repositoryIdentifier","poolTag","name","devHubUsername","branch","isActive","maxAllocation"]}}},"paths":{"/sfp/api/pools/configs":{"post":{"operationId":"PoolConfigController_createPoolConfig","summary":"Create a new pool configuration","description":"Create a new configuration for a sandbox or scratch org pool. Use poolType=SCRATCH_ORG for scratch org pools.","parameters":[{"name":"poolType","required":false,"in":"query","description":"Pool type: SANDBOX (default) or SCRATCH_ORG","schema":{"enum":["SANDBOX","SCRATCH_ORG"],"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CreateSandboxPoolConfigDto"},{"$ref":"#/components/schemas/CreateScratchOrgPoolConfigDto"}]}}}},"responses":{"403":{"description":"Forbidden - Requires role: owner, application"},"default":{"description":"Pool configuration created successfully","content":{"application/json":{"schema":{}}}}},"tags":["Pools"]}}}}
```

## Get a pool configuration

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"SandboxPoolConfigDto":{"type":"object","properties":{"repositoryIdentifier":{"type":"string","description":"Repository identifier in format org/repo or org/project/repo"},"name":{"type":"string","description":"User-friendly display name for the pool"},"poolTag":{"type":"string","description":"Unique machine-readable tag for this pool"},"branchPattern":{"type":"string","description":"Optional Git branch pattern this pool serves"},"devHubUsername":{"type":"string","description":"Registered Dev Hub alias/username"},"sandboxDefinition":{"type":"object","description":"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)"},"sourceSandboxName":{"type":"string","description":"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)","deprecated":true},"daysToKeepUnassignedAvailable":{"type":"number","description":"TTL in days for available sandboxes before refresh/delete"},"isActive":{"type":"boolean","description":"Whether this pool configuration is active for monitoring"},"additionalConfig":{"type":"object","description":"Additional configuration for user activation and data seeding"},"lastMonitoredAt":{"type":"string","description":"Timestamp when this pool was last monitored"},"currentProvisionRunId":{"type":"string","description":"Unique identifier for the current provision run"},"currentMonitorRunId":{"type":"string","description":"Unique identifier for the current monitor run"},"defaultExpirationHours":{"type":"number","description":"Default expiration hours for assigned sandboxes"},"extendedExpirationHours":{"type":"number","description":"Extended expiration hours for assigned sandboxes"},"averageOrgCreationTime":{"type":"number","description":"Average time in minutes it takes to create a sandbox"},"lastProvisionedAt":{"type":"string","description":"Timestamp when the last provision action was triggered"},"minAvailableInstances":{"type":"number","description":"Target number of AVAILABLE sandboxes"},"maxTotalInstances":{"type":"number","description":"Hard cap for total sandboxes in this pool"},"refreshOrDeleteStrategy":{"type":"string","description":"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","enum":["DELETE_EXPIRED","AUTO_REFRESH_EXPIRED","FLAG_EXPIRED","NOTIFY_ONLY"]},"refreshStrategy":{"type":"string","description":"Refresh strategy for sandboxes","enum":["ALWAYS","NEVER","STAGGER"]},"refreshIntervalHours":{"type":"number","description":"Interval in hours between sandbox refreshes (for STAGGER strategy)"},"minActiveInstances":{"type":"number","description":"Minimum number of active instances to maintain"},"maxActiveInstances":{"type":"number","description":"Maximum number of active instances allowed"},"minRetentionDays":{"type":"number","description":"Minimum retention days for sandboxes"},"returnToPoolOnUnassign":{"type":"boolean","description":"When true, unassigned sandboxes return to pool as AVAILABLE with reset timer. When false (default), they are marked as EXPIRED."},"metadata":{"type":"object","description":"Additional metadata for the pool configuration for custom filtering and tagging"},"monitoringCronPattern":{"type":"string","description":"Cron pattern for monitoring schedule (5-field standard cron)"},"poolStatus":{"type":"string","description":"Pool lifecycle status. ACTIVE = normal operation, DELETING = cleanup in progress","enum":["ACTIVE","DELETING"],"default":"ACTIVE"},"cleanupJobId":{"type":"string","description":"Job ID for the cleanup flow when poolStatus is DELETING"}},"required":["repositoryIdentifier","name","poolTag","devHubUsername","daysToKeepUnassignedAvailable","isActive","minAvailableInstances","maxTotalInstances","refreshOrDeleteStrategy"]}}},"paths":{"/sfp/api/pools/configs/{poolTag}":{"get":{"operationId":"PoolConfigController_getPoolConfig","summary":"Get a pool configuration","description":"Retrieve a specific pool configuration (sandbox or scratch org) by tag and repository","parameters":[{"name":"poolTag","required":true,"in":"path","description":"The tag of the pool to retrieve","schema":{"type":"string"}},{"name":"repositoryIdentifier","required":true,"in":"query","description":"Repository identifier in format org/repo or org/project/repo","schema":{"type":"string"}},{"name":"poolType","required":false,"in":"query","description":"Pool type hint for faster lookup (SANDBOX or SCRATCH_ORG). If not specified, both types are checked","schema":{"enum":["SANDBOX","SCRATCH_ORG"],"type":"string"}}],"responses":{"200":{"description":"Pool configuration retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxPoolConfigDto"}}}},"403":{"description":"Forbidden - Requires role: owner, member, application"}},"tags":["Pools"]}}}}
```

## Delete a pool configuration

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/pools/configs/{poolTag}":{"delete":{"operationId":"PoolConfigController_deletePoolConfig","summary":"Delete a pool configuration","description":"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.","parameters":[{"name":"poolTag","required":true,"in":"path","description":"The tag of the pool to delete","schema":{"type":"string"}},{"name":"repositoryIdentifier","required":true,"in":"query","description":"Repository identifier in format org/repo or org/project/repo","schema":{"type":"string"}}],"responses":{"403":{"description":"Forbidden - Requires role: owner"},"default":{"description":"Pool deleted successfully","content":{"application/json":{"schema":{}}}}},"tags":["Pools"]}}}}
```

## Update a pool configuration

> Update an existing configuration for a sandbox or scratch org pool

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/pools/configs/{poolTag}":{"patch":{"operationId":"PoolConfigController_updatePoolConfig","summary":"Update a pool configuration","description":"Update an existing configuration for a sandbox or scratch org pool","parameters":[{"name":"poolTag","required":true,"in":"path","description":"The tag of the pool to update","schema":{"type":"string"}},{"name":"repositoryIdentifier","required":true,"in":"query","description":"Repository identifier in format org/repo or org/project/repo","schema":{"type":"string"}},{"name":"poolType","required":false,"in":"query","description":"Pool type hint for routing (SANDBOX or SCRATCH_ORG)","schema":{"enum":["SANDBOX","SCRATCH_ORG"],"type":"string"}}],"responses":{"403":{"description":"Forbidden - Requires role: owner, application"},"default":{"description":"Pool configuration updated successfully","content":{"application/json":{"schema":{}}}}},"tags":["Pools"]}}}}
```

## Get a pool's 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.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/pools/configs/{poolTag}/provisioning-origin":{"get":{"operationId":"PoolConfigController_getProvisioningOrigin","summary":"Get a pool's provisioning origin","description":"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.","parameters":[{"name":"poolTag","required":true,"in":"path","description":"The tag of the pool","schema":{"type":"string"}},{"name":"repositoryIdentifier","required":true,"in":"query","description":"Repository identifier in format org/repo or org/project/repo","schema":{"type":"string"}},{"name":"poolType","required":false,"in":"query","description":"Pool type hint for faster lookup. If not specified, both types are checked","schema":{"enum":["SANDBOX","SCRATCH_ORG"],"type":"string"}}],"responses":{"200":{"description":"Provisioning origin resolved successfully"},"403":{"description":"Forbidden - Requires role: owner, member, application"}},"tags":["Pools"]}}}}
```

## Get pool status

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/pools/status":{"get":{"operationId":"PoolQueryController_getPoolStatus","summary":"Get pool status","description":"Retrieve current status of pools (sandbox or scratch org) and their instances. Supports filtering by status, pool type, and entity assignment.","parameters":[{"name":"repositoryIdentifier","required":false,"in":"query","description":"Repository identifier in format org/repo or org/project/repo","schema":{"type":"string"}},{"name":"poolTag","required":false,"in":"query","description":"Optional. If provided, returns detailed status for the specified pool.","schema":{"type":"string"}},{"name":"instanceStatus","required":false,"in":"query","description":"Optional. Filter instances by status (used with poolTag).","schema":{"enum":["REQUESTED","PROVISIONING","ACTIVATING","AVAILABLE","ASSIGNED","EXPIRED","FLAGGED_FOR_REFRESH","REFRESHING","DELETING","ORPHANED","ERROR","UNKNOWN"],"type":"string"}},{"name":"assignmentId","required":false,"in":"query","description":"Optional. Filter by assignment UUID (sandbox pools only).","schema":{"type":"string"}},{"name":"poolType","required":false,"in":"query","description":"Optional. Pool type hint for faster lookup (SANDBOX or SCRATCH_ORG).","schema":{"enum":["SANDBOX","SCRATCH_ORG"],"type":"string"}},{"name":"refresh","required":false,"in":"query","description":"Optional. Force refresh of cached data for scratch org pools.","schema":{"type":"boolean"}}],"responses":{"403":{"description":"Forbidden - Requires role: owner, member, application"},"default":{"description":"Pool status retrieved successfully","content":{"application/json":{"schema":{}}}}},"tags":["Pools"]}}}}
```

## Cleanup zombie sandbox instances

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/pools/cleanup-zombies":{"post":{"operationId":"PoolQueryController_cleanupZombies","summary":"Cleanup zombie sandbox instances","description":"Identify and optionally cleanup sandbox instances that exist in the database but not in Salesforce","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["devHubUsername"],"properties":{"devHubUsername":{"type":"string","description":"DevHub username to check for zombies"},"dryRun":{"type":"boolean","description":"If true, only identify zombies without deleting them"}}}}}},"responses":{"403":{"description":"Forbidden - Requires role: owner"},"default":{"description":"Zombie cleanup completed","content":{"application/json":{"schema":{}}}}},"tags":["Pools"]}}}}
```

## Get current sandbox service mode

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/pools/mode":{"get":{"operationId":"PoolMonitoringController_getServiceMode","summary":"Get current sandbox service mode","description":"Returns whether the system is using mock or real Salesforce sandbox service. All authenticated users can view the service mode.","parameters":[],"responses":{"200":{"description":"Current mode information","content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["mock","real"]},"description":{"type":"string"},"mockModeEnvVar":{"type":"string"}}}}}},"403":{"description":"Forbidden - Requires role: owner, member, application"}},"tags":["Pools"]}}}}
```

## Get pool monitoring status

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"MonitoringJobsListDto":{"type":"object","properties":{"totalJobs":{"type":"number","description":"Total number of monitoring jobs"},"jobs":{"description":"List of monitoring jobs","type":"array","items":{"$ref":"#/components/schemas/MonitoringJobDto"}}},"required":["totalJobs","jobs"]},"MonitoringJobDto":{"type":"object","properties":{"jobName":{"type":"string","description":"Job name identifier"},"repositoryIdentifier":{"type":"string","description":"Repository identifier for the pool"},"poolTag":{"type":"string","description":"Pool tag"},"poolType":{"type":"string","description":"Pool type this job belongs to. Disambiguates jobs when a sandbox and a scratch org pool share the same poolTag.","enum":["SANDBOX","SCRATCH_ORG"]},"taskType":{"type":"string","description":"Underlying workflow that backs this job (e.g. monitor-pool, monitor-scratch-org-pool, provision-scratch-org-pool)."},"description":{"type":"string","description":"Description of the monitoring job"},"pattern":{"type":"string","description":"Cron pattern for the job"},"enabled":{"type":"boolean","description":"Whether the job schedule is enabled"},"nextRun":{"format":"date-time","type":"string","description":"Next scheduled run time","nullable":true},"lastRun":{"format":"date-time","type":"string","description":"Last run time","nullable":true},"running":{"type":"boolean","description":"Whether the job is currently running"},"lastRunUrl":{"type":"string","description":"URL to the last execution run in the sfp dashboard"},"lastRunExecutionId":{"type":"string","description":"Task execution ID of the last run"}},"required":["jobName","repositoryIdentifier","poolTag","poolType","taskType","enabled"]}}},"paths":{"/sfp/api/pools/monitoring-jobs":{"get":{"operationId":"PoolMonitoringController_getMonitoringStatus","summary":"Get pool monitoring status","description":"Retrieve information about all repository-specific pool monitoring jobs. All authenticated users can view monitoring job status.","parameters":[],"responses":{"200":{"description":"Monitoring job status retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitoringJobsListDto"}}}},"403":{"description":"Forbidden - Requires role: owner, member, application"}},"tags":["Pools"]}}}}
```

## Pause a pool monitoring job

> Disables a pool monitoring cron schedule without deleting it.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/pools/monitoring-jobs/{jobName}/pause":{"post":{"operationId":"PoolMonitoringController_pauseMonitoringJob","summary":"Pause a pool monitoring job","description":"Disables a pool monitoring cron schedule without deleting it.","parameters":[{"name":"jobName","required":true,"in":"path","description":"The monitoring job name (cron name)","schema":{"type":"string"}}],"responses":{"200":{"description":"Monitoring job paused"},"403":{"description":"Forbidden - Requires role: owner"}},"tags":["Pools"]}}}}
```

## Resume a paused pool monitoring job

> Re-enables a previously paused pool monitoring cron schedule.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/pools/monitoring-jobs/{jobName}/resume":{"post":{"operationId":"PoolMonitoringController_resumeMonitoringJob","summary":"Resume a paused pool monitoring job","description":"Re-enables a previously paused pool monitoring cron schedule.","parameters":[{"name":"jobName","required":true,"in":"path","description":"The monitoring job name (cron name)","schema":{"type":"string"}}],"responses":{"200":{"description":"Monitoring job resumed"},"403":{"description":"Forbidden - Requires role: owner"}},"tags":["Pools"]}}}}
```

## List pool instances

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{}},"paths":{"/sfp/api/pools/{poolTag}/instances":{"get":{"operationId":"PoolInstanceController_listPoolInstances","summary":"List pool instances","description":"Get a list of all instances in a specific pool (sandbox or scratch org)","parameters":[{"name":"poolTag","required":true,"in":"path","description":"Pool tag to get instances for (works with both sandbox and scratch org pools)","schema":{"type":"string"}},{"name":"repositoryIdentifier","required":true,"in":"query","description":"Repository identifier in format org/repo or org/project/repo","schema":{"type":"string"}},{"name":"poolType","required":false,"in":"query","description":"Optional pool type hint for faster lookup (SANDBOX or SCRATCH_ORG). If not specified, the pool type is auto-detected","schema":{"enum":["SANDBOX","SCRATCH_ORG"],"type":"string"}},{"name":"refresh","required":false,"in":"query","description":"Optional. Force refresh of cached data for scratch org pools (ignored for sandbox pools).","schema":{"type":"boolean"}}],"responses":{"200":{"description":"List of pool instances (either SandboxPoolInstance or BasePoolInstance depending on pool type)","content":{"application/json":{"schema":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/SandboxPoolInstanceDto"},{"$ref":"#/components/schemas/BasePoolInstance"}]}}}}},"403":{"description":"Forbidden - Requires role: owner, member, application"}},"tags":["Pools"]}}}}
```

## Drain all instances from a pool (keeps pool config)

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/pools/{poolTag}/instances":{"delete":{"operationId":"PoolInstanceController_drainPool","summary":"Drain all instances from a pool (keeps pool config)","description":"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.","parameters":[{"name":"poolTag","required":true,"in":"path","description":"Pool tag to drain, or \"all\" to drain every active pool","schema":{"type":"string"}},{"name":"repositoryIdentifier","required":true,"in":"query","description":"Repository identifier in format org/repo or org/project/repo","schema":{"type":"string"}}],"responses":{"202":{"description":"Drain workflow dispatched"},"403":{"description":"Forbidden - Requires role: owner"}},"tags":["Pools"]}}}}
```

## Fetch and assign sandbox from pool

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"FetchSandboxDto":{"type":"object","properties":{"assignmentId":{"type":"string","description":"UUID identifying the assignment. If not provided, a new UUID will be generated."},"isImmortal":{"type":"boolean","description":"If true, the sandbox will not expire automatically","default":false},"assignedToUserEmail":{"type":"string","description":"Email of the user to assign the sandbox to. Only applicable when using application tokens. If not provided, defaults to app:<token_creator>"},"createUser":{"type":"boolean","description":"If true, creates a Salesforce user in the assigned sandbox and sends a password reset email. Sandbox pools only.","default":false}}}}},"paths":{"/sfp/api/pools/{poolTag}/fetch":{"post":{"operationId":"PoolInstanceController_fetchSandbox","summary":"Fetch and assign sandbox from pool","description":"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.","parameters":[{"name":"poolTag","required":true,"in":"path","description":"Pool tag to fetch sandbox from","schema":{"type":"string"}},{"name":"repositoryIdentifier","required":true,"in":"query","description":"Repository identifier in format org/repo or org/project/repo","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Assignment configuration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FetchSandboxDto"}}}},"responses":{"403":{"description":"Forbidden - Requires role: owner, member, application"},"default":{"description":"Instance successfully assigned (sandbox or scratch org)","content":{"application/json":{"schema":{}}}}},"tags":["Pools"]}}}}
```

## Unassign instance from user

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"UnassignSandboxDto":{"type":"object","properties":{"sandboxId":{"type":"string","description":"ID of the sandbox to unassign (required if assignmentId is not provided)"},"assignmentId":{"type":"string","description":"UUID of the assignment to unassign (required if sandboxId is not provided)"},"returnToPool":{"type":"boolean","description":"When true (default), the sandbox returns to the AVAILABLE pool with a reset timer. When false, the sandbox is marked as EXPIRED.","default":true}}}}},"paths":{"/sfp/api/pools/{poolTag}/unassign":{"post":{"operationId":"PoolInstanceController_unassignSandbox","summary":"Unassign instance from user","description":"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.","parameters":[{"name":"poolTag","required":true,"in":"path","description":"Pool tag where the instance belongs (works with both sandbox and scratch org pools)","schema":{"type":"string"}},{"name":"repositoryIdentifier","required":true,"in":"query","description":"Repository identifier in format org/repo or org/project/repo","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Unassignment details: either sandboxId OR assignmentId","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnassignSandboxDto"}}}},"responses":{"403":{"description":"Forbidden - Requires role: owner, application"},"default":{"description":"Instance unassigned successfully (sandbox or scratch org)","content":{"application/json":{"schema":{}}}}},"tags":["Pools"]}}}}
```

## Regenerate sandbox SFDX 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.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"RegenerateSandboxAuthUrlDto":{"type":"object","properties":{"sandboxId":{"type":"string","description":"ID of the sandbox instance to regenerate auth URL for (required if sandboxName and assignmentId are not provided)"},"sandboxName":{"type":"string","description":"Name of the sandbox to regenerate auth URL for (required if sandboxId and assignmentId are not provided)"},"assignmentId":{"type":"string","description":"UUID of the assignment to regenerate auth URL for (required if sandboxId and sandboxName are not provided)"}}},"RegenerateSandboxAuthUrlResponseDto":{"type":"object","properties":{"status":{"type":"string","description":"Machine-readable operation status"},"message":{"type":"string","description":"Human-readable operation result"},"timestamp":{"type":"string","description":"ISO timestamp when the API response was generated"},"details":{"description":"Regenerated sandbox auth URL details","allOf":[{"$ref":"#/components/schemas/RegenerateSandboxAuthUrlDetailsDto"}]}},"required":["status","message","timestamp","details"]},"RegenerateSandboxAuthUrlDetailsDto":{"type":"object","properties":{"sandboxId":{"type":"string","description":"Sandbox pool instance ID"},"sandboxName":{"type":"string","description":"Sandbox name"},"poolTag":{"type":"string","description":"Sandbox pool tag"},"assignmentId":{"type":"string","description":"UUID of the active assignment, when assigned"},"instanceUrl":{"type":"string","description":"Salesforce instance URL returned by the fresh auth"},"sfdxAuthUrl":{"type":"string","description":"Fresh SFDX auth URL persisted for the sandbox"},"regeneratedAt":{"type":"string","description":"ISO timestamp when the auth URL was regenerated"}},"required":["sandboxId","sandboxName","poolTag","sfdxAuthUrl"]}}},"paths":{"/sfp/api/pools/{poolTag}/regenerate-auth-url":{"post":{"operationId":"PoolInstanceController_regenerateSandboxAuthUrl","summary":"Regenerate sandbox SFDX auth URL","description":"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.","parameters":[{"name":"poolTag","required":true,"in":"path","description":"Sandbox pool tag where the instance belongs","schema":{"type":"string"}},{"name":"repositoryIdentifier","required":true,"in":"query","description":"Repository identifier in format org/repo or org/project/repo","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Regeneration target: provide exactly one of sandboxId, sandboxName, or assignmentId","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegenerateSandboxAuthUrlDto"}}}},"responses":{"200":{"description":"SFDX auth URL regenerated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegenerateSandboxAuthUrlResponseDto"}}}},"400":{"description":"Invalid target or unsupported status"},"403":{"description":"Forbidden - Requires role: owner, member, application"},"404":{"description":"Sandbox pool or instance not found"}},"tags":["Pools"]}}}}
```

## Extend sandbox expiration time

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"ExtendSandboxDto":{"type":"object","properties":{"assignmentId":{"type":"string","description":"UUID of the assignment to extend"},"extensionHours":{"type":"number","description":"Number of hours to extend the sandbox expiration. If not provided, uses the pool's configured extension hours.","minimum":1,"maximum":720},"isImmortal":{"type":"boolean","description":"Set or change the immortal state of the sandbox. If not provided, immortal state remains unchanged."}},"required":["assignmentId"]}}},"paths":{"/sfp/api/pools/{poolTag}/extend":{"post":{"operationId":"PoolInstanceController_extendSandbox","summary":"Extend sandbox expiration time","description":"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.","parameters":[{"name":"poolTag","required":true,"in":"path","description":"Pool tag where the sandbox belongs","schema":{"type":"string"}},{"name":"repositoryIdentifier","required":true,"in":"query","description":"Repository identifier in format org/repo or org/project/repo","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Assignment details to extend sandbox for","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtendSandboxDto"}}}},"responses":{"403":{"description":"Forbidden - Requires role: owner, member"},"default":{"description":"Expiry extended successfully (sandbox or scratch org)","content":{"application/json":{"schema":{}}}}},"tags":["Pools"]}}}}
```

## Trigger pool replenishment workflow

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/pools/{poolTag}/replenish":{"post":{"operationId":"PoolInstanceController_replenish","summary":"Trigger pool replenishment workflow","description":"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.","parameters":[{"name":"poolTag","required":true,"in":"path","description":"Pool tag to replenish, or \"all\" to target all active pools","schema":{"type":"string"}},{"name":"repositoryIdentifier","required":true,"in":"query","description":"Repository identifier in format org/repo or org/project/repo","schema":{"type":"string"}}],"responses":{"403":{"description":"Forbidden - Requires role: owner"},"default":{"description":"Replenishment workflow initiated","content":{"application/json":{"schema":{}}}}},"tags":["Pools"]}}}}
```

## Delete an org instance from a pool

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/pools/{poolTag}/instances/{instanceName}":{"delete":{"operationId":"PoolInstanceController_deleteInstance","summary":"Delete an org instance from a pool","description":"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.","parameters":[{"name":"poolTag","required":true,"in":"path","description":"Pool tag where the instance belongs","schema":{"type":"string"}},{"name":"instanceName","required":true,"in":"path","description":"Name/username of the org instance to delete","schema":{"type":"string"}},{"name":"repositoryIdentifier","required":true,"in":"query","description":"Repository identifier in format org/repo or org/project/repo","schema":{"type":"string"}},{"name":"force","required":false,"in":"query","description":"Force deletion even if instance is less than 24 hours old or is immortal","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Instance successfully deleted or marked for deletion"},"400":{"description":"Cannot delete instance (e.g., immortal instance without force flag)"},"403":{"description":"Forbidden - Requires role: owner"},"404":{"description":"Instance not found"}},"tags":["Pools"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.flxbl.io/flxbl/sfp-server/api-reference/pools.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.