Environments
sfp server API reference for Environments: 25 endpoints.
/sfp/api/environmentsCreates a new environment linked to a repository and Salesforce org. The environment can be locked using the mutex system for exclusive access.
Authorization
access-token In: header
Request Body
application/json
Environment creation details
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "https://example.com/sfp/api/environments" \ -H "Content-Type: application/json" \ -d '{ "repositoryIdentifier": "myorg/myrepo", "name": "prod", "description": "Production environment", "category": "release", "salesforceUsername": "admin@company.com", "isActive": true, "isDefault": true, "metadata": { "region": "us-west", "tier": "enterprise" }, "tags": [ "critical", "monitored" ], "branch": "main" }'{ "id": "456e7890-e89b-12d3-a456-426614174001", "repositoryIdentifier": "myorg/myrepo", "repositoryName": "myrepo", "name": "prod", "description": "Production environment", "category": "release", "salesforceUsername": "admin@company.com", "devHubUsername": null, "isActive": true, "isDefault": true, "isLocked": false, "lockedBy": null, "lockExpiresAt": null, "lockExpiresInSeconds": null, "lockStatus": { "isLocked": false, "currentLock": null, "queuedLocks": [] }, "metadata": { "region": "us-west", "tier": "enterprise" }, "tags": [ "critical", "monitored" ], "branch": "main", "orchestrationOrder": null, "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-01T00:00:00Z", "createdBy": "admin@company.com", "updatedBy": "admin@company.com"}/sfp/api/environmentsRetrieves environments with optional filtering. Returns grouped by category when no specific category filter is provided, or a flat array when filtering by a specific category. Each environment includes current lock status and queue information.
Authorization
access-token In: header
Query Parameters
Filter by repository identifier (e.g., owner/repo)
Filter by environment category. When specified, returns a flat array of that category only.
Value in
- "dev"
- "test"
- "snapshot"
- "release"
Filter by active status
Filter by git branch
Response Body
application/json
curl -X GET "https://example.com/sfp/api/environments"{ "dev": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "repositoryIdentifier": "myorg/myrepo", "repositoryName": "myrepo", "name": "dev1", "description": "Development environment", "category": "dev", "salesforceUsername": "admin@company.dev", "devHubUsername": null, "isActive": true, "isDefault": false, "isLocked": false, "lockedBy": null, "lockExpiresAt": null, "lockExpiresInSeconds": null, "lockStatus": { "isLocked": false, "currentLock": null, "queuedLocks": [] }, "metadata": {}, "tags": [ "development" ], "branch": "develop", "orchestrationOrder": null, "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-01T00:00:00Z" } ], "test": [ { "id": "223e4567-e89b-12d3-a456-426614174000", "repositoryIdentifier": "myorg/myrepo", "repositoryName": "myrepo", "name": "test1", "description": "Test environment", "category": "test", "salesforceUsername": "admin@company.test", "devHubUsername": null, "isActive": true, "isDefault": false, "isLocked": true, "lockedBy": "ci-pipeline", "lockExpiresAt": "2024-01-15T15:00:00Z", "lockExpiresInSeconds": 3600, "lockStatus": { "isLocked": true, "currentLock": { "lockedBy": "ci-pipeline", "lockReason": "Running integration tests", "expiresAt": "2024-01-15T15:00:00Z", "expiresInSeconds": 3600 }, "queuedLocks": [ { "position": 1, "requestedBy": "deploy-bot", "lockReason": "Deployment to test", "estimatedWaitSeconds": 3600, "ticketId": "ticket_456def" } ] }, "metadata": { "tier": "sandbox" }, "tags": [ "testing", "automated" ], "branch": "develop", "orchestrationOrder": null, "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-15T14:00:00Z" } ], "snapshot": [], "release": [ { "id": "323e4567-e89b-12d3-a456-426614174000", "repositoryIdentifier": "myorg/myrepo", "repositoryName": "myrepo", "name": "prod", "description": "Production environment", "category": "release", "salesforceUsername": "admin@company.com", "devHubUsername": null, "isActive": true, "isDefault": true, "isLocked": false, "lockedBy": null, "lockExpiresAt": null, "lockExpiresInSeconds": null, "lockStatus": { "isLocked": false, "currentLock": null, "queuedLocks": [] }, "metadata": { "region": "us-west", "tier": "enterprise" }, "tags": [ "critical", "monitored" ], "branch": "main", "orchestrationOrder": 1, "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-01T00:00:00Z" } ]}/sfp/api/environments/orchestration-orderRetrieves the deployment orchestration order for environments within a specific category in a repository. Returns an ordered array of environment names.
Authorization
access-token In: header
Query Parameters
Repository identifier (e.g., owner/repo)
Environment category
Value in
- "dev"
- "test"
- "snapshot"
- "release"
Response Body
application/json
curl -X GET "https://example.com/sfp/api/environments/orchestration-order?repositoryIdentifier=myorg%2Fmyrepo&category=dev&includeInactive=string&branch=string"[ "dev1", "dev2", "dev3"]/sfp/api/environments/orchestration-orderUpdates the deployment orchestration order for environments within a specific category in a repository. Replaces the entire order with the provided array.
Authorization
access-token In: header
Query Parameters
Repository identifier (e.g., owner/repo)
Environment category
Value in
- "dev"
- "test"
- "snapshot"
- "release"
Request Body
application/json
New orchestration order
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X PUT "https://example.com/sfp/api/environments/orchestration-order?repositoryIdentifier=myorg%2Fmyrepo&category=dev&includeInactive=string&branch=string" \ -H "Content-Type: application/json" \ -d '{ "environmentOrder": [ "dev1", "dev2", "dev3" ] }'[ "dev3", "dev1", "dev2"]/sfp/api/environments/findAuthorization
access-token In: header
Query Parameters
Response Body
curl -X GET "https://example.com/sfp/api/environments/find?sandboxName=string&productionOrg=string&salesforceUsername=string&name=string&repositoryIdentifier=string"/sfp/api/environments/by-name/{name}Retrieves detailed information about a specific environment by its name and repository identifier
Authorization
access-token In: header
Path Parameters
Environment name
Query Parameters
Repository identifier (e.g., owner/repo)
Type of authentication credentials to include in response (requires owner/application role). Use "accessToken" (recommended) for short-lived tokens suitable for most operations, or "sfdxAuthUrl" for long-lived refresh tokens needed for extended operations.
Value in
- "accessToken"
- "sfdxAuthUrl"
Response Body
curl -X GET "https://example.com/sfp/api/environments/by-name/production?repositoryIdentifier=myorg%2Fmyrepo"/sfp/api/environments/by-name/{name}Updates environment properties by name and repository. Only provided fields will be updated.
Authorization
access-token In: header
Path Parameters
Environment name
Query Parameters
Repository identifier (e.g., owner/repo)
Request Body
application/json
Fields to update
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
curl -X PATCH "https://example.com/sfp/api/environments/by-name/production?repositoryIdentifier=myorg%2Fmyrepo" \ -H "Content-Type: application/json" \ -d 'string'/sfp/api/environments/by-name/{name}Permanently deletes an environment by name and repository. Cannot delete a locked environment.
Authorization
access-token In: header
Path Parameters
Environment name
Query Parameters
Repository identifier (e.g., owner/repo)
Response Body
curl -X DELETE "https://example.com/sfp/api/environments/by-name/production?repositoryIdentifier=myorg%2Fmyrepo"/sfp/api/environments/{id}Retrieves detailed information about a specific environment including its lock status
Authorization
access-token In: header
Path Parameters
Environment ID
Query Parameters
Type of authentication credentials to include in response (requires owner/application role). Use "accessToken" (recommended) for short-lived tokens suitable for most operations, or "sfdxAuthUrl" for long-lived refresh tokens needed for extended operations.
Value in
- "accessToken"
- "sfdxAuthUrl"
Response Body
application/json
curl -X GET "https://example.com/sfp/api/environments/456e7890-e89b-12d3-a456-426614174001"{ "id": "456e7890-e89b-12d3-a456-426614174001", "repositoryIdentifier": "myorg/my-salesforce-project", "repositoryName": "my-salesforce-project", "name": "prod", "description": "Production environment", "category": "release", "salesforceUsername": "admin@company.com", "isActive": true, "isDefault": true, "isLocked": true, "lockedBy": "deploy-bot", "metadata": { "region": "us-west", "tier": "enterprise" }, "tags": [ "critical", "monitored" ], "branch": "main", "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-15T12:00:00Z", "createdBy": "user123", "updatedBy": "user456"}/sfp/api/environments/{id}Updates environment properties. Only provided fields will be updated. Changing salesforceUsername will validate the new org exists.
Authorization
access-token In: header
Path Parameters
Environment ID
Request Body
application/json
Fields to update
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X PATCH "https://example.com/sfp/api/environments/456e7890-e89b-12d3-a456-426614174001" \ -H "Content-Type: application/json" \ -d '{ "tags": [ "production", "critical", "monitored" ] }'{ "id": "456e7890-e89b-12d3-a456-426614174001", "repositoryIdentifier": "myorg/myrepo", "repositoryName": "myrepo", "name": "prod", "description": "Updated production environment", "category": "release", "salesforceUsername": "admin@company.com", "devHubUsername": null, "isActive": true, "isDefault": true, "isLocked": false, "lockedBy": null, "lockExpiresAt": null, "lockExpiresInSeconds": null, "lockStatus": { "isLocked": false, "currentLock": null, "queuedLocks": [] }, "metadata": { "region": "us-west", "tier": "enterprise" }, "tags": [ "production", "critical", "monitored" ], "branch": "main", "orchestrationOrder": 1, "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-15T16:00:00Z", "createdBy": "admin@company.com", "updatedBy": "admin@company.com"}/sfp/api/environments/{id}Permanently deletes an environment. Cannot delete a locked environment. All associated tags and audit records will be deleted.
Authorization
access-token In: header
Path Parameters
Environment ID
Response Body
curl -X DELETE "https://example.com/sfp/api/environments/456e7890-e89b-12d3-a456-426614174001"/sfp/api/environments/{id}/lockRequests a lock on an environment. Returns a ticket ID immediately. The lock is queued if the environment is already locked. Use the /acquire endpoint with the ticket ID to wait for and obtain the actual lock. The lock will automatically expire after the specified duration.
Authorization
access-token In: header
Path Parameters
Environment ID
Query Parameters
Full repository identifier (e.g., owner/repo)
Request Body
application/json
Lock configuration
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "https://example.com/sfp/api/environments/456e7890-e89b-12d3-a456-426614174001/lock?repositoryIdentifier=myorg%2Fmy-salesforce-project" \ -H "Content-Type: application/json" \ -d '{ "leaseDurationSeconds": 3600, "reason": "Deploying release v2.1.0" }'{ "ticketId": "ticket_789abc12-3def-4567-8901-234567890abc"}/sfp/api/environments/{id}/lock/{ticketId}/acquireAttempts to acquire a lock that was previously requested. This endpoint will wait up to the specified timeout for the lock to become available. Returns immediately if the lock is already acquired. Returns Salesforce credentials only when the lock is successfully acquired.
Authorization
access-token In: header
Path Parameters
Environment ID
Lock ticket ID obtained when requesting the lock
Query Parameters
Full repository identifier (e.g., owner/repo)
Type of authentication credentials to return. Use "accessToken" (recommended, default) for short-lived tokens suitable for most operations, or "sfdxAuthUrl" for long-lived refresh tokens needed for extended operations that may exceed the access token lifetime.
Value in
- "accessToken"
- "sfdxAuthUrl"
Response Body
application/json
curl -X PUT "https://example.com/sfp/api/environments/456e7890-e89b-12d3-a456-426614174001/lock/ticket_789abc12-3def-4567-8901-234567890abc/acquire?repositoryIdentifier=myorg%2Fmy-salesforce-project"{ "status": "acquired", "environmentId": "456e7890-e89b-12d3-a456-426614174001", "environmentName": "production", "salesforceUsername": "admin@company.com", "accessToken": "00D...", "instanceUrl": "https://mycompany.my.salesforce.com", "sfdxAuthUrl": "force://PlatformCLI::...", "frontDoorUrl": "https://mycompany.my.salesforce.com/secur/frontdoor.jsp?sid=..."}/sfp/api/environments/{id}/lock/{ticketId}Releases a lock on an environment using the ticket ID obtained when locking. Only the lock holder can release it unless admin/owner role.
Authorization
access-token In: header
Path Parameters
Environment ID
Lock ticket ID obtained when locking
Query Parameters
Full repository identifier (e.g., owner/repo)
Response Body
curl -X DELETE "https://example.com/sfp/api/environments/456e7890-e89b-12d3-a456-426614174001/lock/ticket_789abc12-3def-4567-8901-234567890abc?repositoryIdentifier=myorg%2Fmy-salesforce-project"/sfp/api/environments/by-name/{name}/lockRequests a lock on an environment. Returns a ticket ID immediately. The lock is queued if the environment is already locked. Use the /acquire endpoint with the ticket ID to wait for and obtain the actual lock. The lock will automatically expire after the specified duration.
Authorization
access-token In: header
Path Parameters
Environment name
Query Parameters
Repository identifier (owner/repo)
Request Body
application/json
Lock configuration
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "https://example.com/sfp/api/environments/by-name/production/lock?repositoryIdentifier=myorg%2Fmyrepo" \ -H "Content-Type: application/json" \ -d '{ "leaseDurationMinutes": 60, "reason": "Deploying release v2.1.0" }'{ "ticketId": "ticket_789abc12-3def-4567-8901-234567890abc"}/sfp/api/environments/by-name/{name}/lock/{ticketId}/acquireAttempts to acquire a lock that was previously requested. This endpoint will wait up to the specified timeout for the lock to become available. Returns immediately if the lock is already acquired. Returns Salesforce credentials only when the lock is successfully acquired.
Authorization
access-token In: header
Path Parameters
Environment name
Lock ticket ID obtained when requesting the lock
Query Parameters
Repository identifier (owner/repo)
Type of authentication credentials to return. Use "accessToken" (recommended, default) for short-lived tokens suitable for most operations, or "sfdxAuthUrl" for long-lived refresh tokens needed for extended operations that may exceed the access token lifetime.
Value in
- "accessToken"
- "sfdxAuthUrl"
Response Body
application/json
curl -X PUT "https://example.com/sfp/api/environments/by-name/production/lock/ticket_789abc12-3def-4567-8901-234567890abc/acquire?repositoryIdentifier=myorg%2Fmyrepo"{ "status": "acquired", "environmentId": "456e7890-e89b-12d3-a456-426614174001", "environmentName": "production", "salesforceUsername": "admin@company.com", "accessToken": "00D...", "instanceUrl": "https://mycompany.my.salesforce.com", "sfdxAuthUrl": "force://PlatformCLI::...", "frontDoorUrl": "https://mycompany.my.salesforce.com/secur/frontdoor.jsp?sid=..."}/sfp/api/environments/by-name/{name}/lock/{ticketId}Releases a lock on an environment using repository identifier, environment name, and ticket ID.
Authorization
access-token In: header
Path Parameters
Environment name
Lock ticket ID obtained when locking
Query Parameters
Repository identifier (owner/repo)
Response Body
curl -X DELETE "https://example.com/sfp/api/environments/by-name/production/lock/ticket_789abc12-3def-4567-8901-234567890abc?repositoryIdentifier=myorg%2Fmyrepo"/sfp/api/environments/{id}/auditRetrieves audit logs for all access to this environment including reads, updates, locks, and frontdoor access
Authorization
access-token In: header
Path Parameters
Environment ID
Query Parameters
Maximum number of audit records to return (default: 100)
Response Body
application/json
curl -X GET "https://example.com/sfp/api/environments/456e7890-e89b-12d3-a456-426614174001/audit?accessType=string&offset=0"[ { "id": "audit123", "environment_id": "456e7890-e89b-12d3-a456-426614174001", "repository_identifier": "myorg/myrepo", "accessed_by": "user123", "accessed_by_application": null, "access_type": "lock", "access_details": { "action": "environment_locked", "ticket_id": "ticket_789abc", "duration_seconds": 3600, "reason": "Deployment in progress" }, "ip_address": "192.168.1.100", "user_agent": "Mozilla/5.0...", "accessed_at": "2024-01-15T14:30:00Z" }]/sfp/api/environments/repository/{repositoryIdentifier}/auditAuthorization
access-token In: header
Path Parameters
Repository identifier (e.g., owner/repo)
Query Parameters
Maximum number of audit records (default: 100)
Response Body
application/json
curl -X GET "https://example.com/sfp/api/environments/repository/string/audit?accessType=string&offset=0"[]/sfp/api/environments/{id}/frontdoorGenerates a Salesforce frontdoor URL for the environment's org. Can either return the URL or redirect directly to Salesforce. Access is audited.
Authorization
access-token In: header
Path Parameters
Environment ID
Query Parameters
Whether to redirect to Salesforce (default: true) or return the URL (false)
Response Body
application/json
curl -X GET "https://example.com/sfp/api/environments/456e7890-e89b-12d3-a456-426614174001/frontdoor"{ "url": "https://mycompany.my.salesforce.com/secur/frontdoor.jsp?sid=00D...&retURL=%2F"}/sfp/api/environments/{id}/artifactsRetrieves all artifacts installed in the Salesforce org associated with this environment. Results are cached for 1 hour unless force refresh is requested.
Authorization
access-token In: header
Path Parameters
Environment ID (UUID)
Query Parameters
Force refresh the cached data
Value in
- "true"
- "false"
Response Body
application/json
curl -X GET "https://example.com/sfp/api/environments/123e4567-e89b-12d3-a456-426614174000/artifacts"{ "environmentId": "string", "environmentName": "string", "salesforceUsername": "string", "artifacts": [ { "name": "string", "version": "string", "commitId": "string", "subscriberVersion": "string", "type": "string", "isInstalledBysfp": true } ], "retrievedAt": "2019-08-24T14:15:22Z", "cached": true}/sfp/api/environments/by-name/{name}/artifactsRetrieves all artifacts installed in the Salesforce org associated with this environment by name. Results are cached for 1 hour unless force refresh is requested.
Authorization
access-token In: header
Path Parameters
Environment name
Query Parameters
Repository identifier (e.g., owner/repo)
Force refresh the cached data
Value in
- "true"
- "false"
Response Body
application/json
curl -X GET "https://example.com/sfp/api/environments/by-name/production/artifacts?repositoryIdentifier=myorg%2Fmyrepo"{ "environmentId": "string", "environmentName": "string", "salesforceUsername": "string", "artifacts": [ { "name": "string", "version": "string", "commitId": "string", "subscriberVersion": "string", "type": "string", "isInstalledBysfp": true } ], "retrievedAt": "2019-08-24T14:15:22Z", "cached": true}/sfp/api/environments/{id}/releasesRetrieves all releases that have been deployed to a specific environment. Releases are sorted by publication date with the most recent first.
You can optionally filter releases by domain (release configuration) and paginate through results. This endpoint returns release metadata that was captured during the release process, including: - Release name and domain - Publication timestamp - Repository information - Any additional metadata from the release Returns an empty list if no releases have been recorded for the environment.Authorization
access-token In: header
Path Parameters
Environment ID (UUID)
Query Parameters
Filter releases by domain/release configuration name
Maximum number of releases to return
Number of releases to skip for pagination
Include changelog computation (commits, work items) for each release
Response Body
application/json
curl -X GET "https://example.com/sfp/api/environments/string/releases"{ "environmentId": "123e4567-e89b-12d3-a456-426614174000", "environmentName": "production", "repositoryIdentifier": "myorg/myrepo", "releases": [ { "name": "v1.2.3", "domain": "core", "targetOrg": "production", "publishedAt": "2024-01-15T10:30:00.000Z", "repoIdentifier": "myorg/myrepo", "metadata": {}, "changelog": {} } ], "totalCount": 100, "limit": 50, "offset": 0, "retrievedAt": "2024-01-15T10:30:00.000Z"}/sfp/api/environments/by-name/{name}/releasesRetrieves all releases for an environment identified by its name and repository. This is a convenience endpoint that works the same as the ID-based endpoint.
See GET /environments/:id/releases for full documentation.Authorization
access-token In: header
Path Parameters
Environment name
Query Parameters
Repository identifier in format owner/repo
Filter releases by domain/release configuration name
Maximum number of releases to return
Number of releases to skip for pagination
Include changelog computation (commits, work items) for each release
Response Body
application/json
curl -X GET "https://example.com/sfp/api/environments/by-name/string/releases?repositoryIdentifier=myorg%2Fmyrepo"{ "environmentId": "123e4567-e89b-12d3-a456-426614174000", "environmentName": "production", "repositoryIdentifier": "myorg/myrepo", "releases": [ { "name": "v1.2.3", "domain": "core", "targetOrg": "production", "publishedAt": "2024-01-15T10:30:00.000Z", "repoIdentifier": "myorg/myrepo", "metadata": {}, "changelog": {} } ], "totalCount": 100, "limit": 50, "offset": 0, "retrievedAt": "2024-01-15T10:30:00.000Z"}/sfp/api/environments/artifacts/compareCompares package versions across all environments in a repository to detect version drift.
This endpoint:
- Fetches artifacts from all matching environments in parallel
- Uses caching (30 minute TTL) for performance
- Handles partial failures gracefully (returns results for successful environments)
- Uses dynamic per-package baseline (last non-N/A environment from right)
A package is considered "out of sync" if any of its versions differ from the baseline. The baseline for each package is determined by finding the last environment (in orchestration order) that has a non-N/A version for that package.
Authorization
access-token In: header
Query Parameters
Repository identifier in format owner/repo
Comma-separated list of environment names to compare. If not provided, all environments are compared.
Filter environments by category
Value in
- "dev"
- "test"
- "snapshot"
- "release"
Force refresh all caches, bypassing the 30-minute cache TTL (default: false)
Response Body
application/json
curl -X GET "https://example.com/sfp/api/environments/artifacts/compare?repositoryIdentifier=myorg%2Fmyrepo"{ "summary": { "totalPackages": 15, "packagesByType": { "Unlocked": 5, "Source/Data": 3, "Managed": 2 }, "outOfSyncCount": 3, "outOfSyncPercentage": 20, "environments": [ "Dev", "Test", "Staging", "Production" ] }, "packages": [ { "name": "string", "type": "string", "isOutOfSync": true, "versions": { "property1": {}, "property2": {} } } ], "retrievedAt": "2019-08-24T14:15:22Z", "fetchStatus": [ { "environmentName": "string", "success": true, "cached": true, "retrievedAt": "2019-08-24T14:15:22Z", "error": "string" } ]}