# 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","version":"50.1.0-build.525"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"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","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"}}],"responses":{"200":{"description":"Pool configurations retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"repositoryIdentifier":{"type":"string","description":"Repository identifier in format org/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"}},"required":["repositoryIdentifier","name","poolTag","devHubUsername","daysToKeepUnassignedAvailable","isActive","minAvailableInstances","maxTotalInstances","refreshOrDeleteStrategy"]}}}}}},"tags":["pools"]}}}}
```

## Create a new sandbox pool configuration

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

```json
{"openapi":"3.0.0","info":{"title":"sfp","version":"50.1.0-build.525"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/pools/configs":{"post":{"operationId":"PoolConfigController_createPoolConfig","summary":"Create a new sandbox pool configuration","description":"Create a new configuration for a sandbox pool (Note: Scratch org pools are discovered automatically from DevHub)","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"repositoryIdentifier":{"type":"string","description":"Repository identifier in format org/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"},"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},"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"]}}}},"responses":{"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","version":"50.1.0-build.525"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"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","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":{"type":"object","properties":{"repositoryIdentifier":{"type":"string","description":"Repository identifier in format org/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"}},"required":["repositoryIdentifier","name","poolTag","devHubUsername","daysToKeepUnassignedAvailable","isActive","minAvailableInstances","maxTotalInstances","refreshOrDeleteStrategy"]}}}}},"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","version":"50.1.0-build.525"},"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","schema":{"type":"string"}}],"responses":{"default":{"description":"Pool deleted successfully","content":{"application/json":{"schema":{}}}}},"tags":["pools"]}}}}
```

## Update a sandbox pool configuration

> Update an existing configuration for a sandbox pool

```json
{"openapi":"3.0.0","info":{"title":"sfp","version":"50.1.0-build.525"},"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 sandbox pool configuration","description":"Update an existing configuration for a sandbox 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","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"User-friendly display name for the 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"},"sourceSandboxName":{"type":"string","description":"Source sandbox name for cloning (deprecated)","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"},"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"},"metadata":{"type":"object","description":"Additional metadata for the pool configuration for custom filtering and tagging"}}}}}},"responses":{"default":{"description":"Pool configuration updated successfully","content":{"application/json":{"schema":{}}}}},"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","version":"50.1.0-build.525"},"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","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","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":{"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","version":"50.1.0-build.525"},"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":{"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

```json
{"openapi":"3.0.0","info":{"title":"sfp","version":"50.1.0-build.525"},"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","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"}}}}}}},"tags":["pools"]}}}}
```

## Get pool monitoring status

> Retrieve information about all repository-specific pool monitoring jobs

```json
{"openapi":"3.0.0","info":{"title":"sfp","version":"50.1.0-build.525"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"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","parameters":[],"responses":{"200":{"description":"Monitoring job status retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"totalJobs":{"type":"number","description":"Total number of monitoring jobs"},"jobs":{"description":"List of monitoring jobs","type":"array","items":{"type":"object","properties":{"jobName":{"type":"string","description":"Job name identifier"},"description":{"type":"string","description":"Description of the monitoring job"},"pattern":{"type":"string","description":"Cron pattern for the job"},"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"}},"required":["jobName","nextRun","lastRun","running"]}}},"required":["totalJobs","jobs"]}}}}},"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","version":"50.1.0-build.525"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"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","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"}]}}}}}},"tags":["pools"]}}}}
```

## Provision sandbox pool instances

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

```json
{"openapi":"3.0.0","info":{"title":"sfp","version":"50.1.0-build.525"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/pools/{poolTag}/provision":{"post":{"operationId":"PoolInstanceController_provisionPool","summary":"Provision sandbox pool instances","description":"Create new sandbox instances for a specific pool or all pools to meet target capacity. (Note: Only works for sandbox pools)","parameters":[{"name":"poolTag","required":true,"in":"path","description":"Pool tag to target, or \"all\" to target all active pools","schema":{"type":"string"}},{"name":"repositoryIdentifier","required":true,"in":"query","description":"Repository identifier in format org/repo","schema":{"type":"string"}}],"responses":{"default":{"description":"Provisioning started successfully","content":{"application/json":{"schema":{}}}}},"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","version":"50.1.0-build.525"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"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","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Assignment configuration","content":{"application/json":{"schema":{"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}}}}}},"responses":{"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","version":"50.1.0-build.525"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"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","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Unassignment details: either sandboxId OR assignmentId","content":{"application/json":{"schema":{"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)"}}}}}},"responses":{"default":{"description":"Instance unassigned successfully (sandbox or scratch org)","content":{"application/json":{"schema":{}}}}},"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","version":"50.1.0-build.525"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"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","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Assignment details to extend sandbox for","content":{"application/json":{"schema":{"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"]}}}},"responses":{"default":{"description":"Expiry extended successfully","content":{"application/json":{"schema":{}}}}},"tags":["pools"]}}}}
```

## Run complete pool replenishment workflow

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

```json
{"openapi":"3.0.0","info":{"title":"sfp","version":"50.1.0-build.525"},"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":"Run complete pool replenishment workflow","description":"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.","parameters":[{"name":"poolTag","required":true,"in":"path","description":"The unique tag of the pool","schema":{"type":"string"}},{"name":"repositoryIdentifier","required":true,"in":"query","description":"Repository identifier in format org/repo","schema":{"type":"string"}}],"responses":{"default":{"description":"Replenishment workflow initiated","content":{"application/json":{"schema":{}}}}},"tags":["pools"]}}}}
```

## Force delete a sandbox instance

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

```json
{"openapi":"3.0.0","info":{"title":"sfp","version":"50.1.0-build.525"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/pools/{poolTag}/instances/{sandboxName}":{"delete":{"operationId":"PoolInstanceController_forceDeleteInstance","summary":"Force delete a sandbox instance","description":"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.","parameters":[{"name":"poolTag","required":true,"in":"path","description":"Pool tag where the sandbox belongs","schema":{"type":"string"}},{"name":"sandboxName","required":true,"in":"path","description":"Name of the sandbox to delete","schema":{"type":"string"}},{"name":"repositoryIdentifier","required":true,"in":"query","description":"Repository identifier in format org/repo","schema":{"type":"string"}},{"name":"force","required":false,"in":"query","description":"Force deletion even if sandbox is less than 24 hours old","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Sandbox successfully deleted or marked for deletion","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"},"timestamp":{"type":"string"},"details":{"type":"object","properties":{"sandboxName":{"type":"string"},"previousStatus":{"type":"string"},"isImmortal":{"type":"boolean"},"createdAt":{"type":"string"},"deletionType":{"type":"string","enum":["immediate","deferred"]}}}}}}}},"400":{"description":"Cannot delete sandbox (e.g., immortal instance without force flag)"},"404":{"description":"Sandbox not found"}},"tags":["pools"]}}}}
```
