Environments | sfp server

Get all environments

get

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

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

repositoryIdentifierstringOptional

Filter by repository identifier (e.g., owner/repo)

Example: myorg/myrepo

categorystring · enumOptional

Filter by environment category. When specified, returns a flat array of that category only.

Possible values:

isActivebooleanOptional

Filter by active status

Example: true

branchstringOptional

Filter by git branch

Example: main

Responses

200

List of environments with lock status. Returns GroupedEnvironmentsDto when no category filter, or EnvironmentDto[] when category is specified. Each environment includes isLocked, lockedBy, lockExpiresAt, lockExpiresInSeconds, and detailed lockStatus object.

application/json

403

Forbidden - Requires role: member, owner, application

get

/sfp/api/environments

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

{
  "dev": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "repositoryIdentifier": "myorg/myrepo",
      "repositoryName": "myrepo",
      "name": "dev1",
      "description": "Development environment",
      "category": "dev",
      "salesforceUsername": "[email protected]",
      "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": "[email protected]",
      "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": "[email protected]",
      "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"
    }
  ]
}

Create a new environment

post

Creates a new environment linked to a repository and Salesforce org. The environment can be locked using the mutex system for exclusive access.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

stringOptional

Responses

201

Environment created successfully with lock status information

application/json

400

Bad request

403

Forbidden - Requires role: owner, application

404

Repository or Salesforce org not found

409

Environment already exists or Salesforce username already registered

post

/sfp/api/environments

POST /sfp/api/environments HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 287

{
  "repositoryIdentifier": "myorg/myrepo",
  "name": "prod",
  "description": "Production environment",
  "category": "release",
  "salesforceUsername": "[email protected]",
  "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": "[email protected]",
  "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": "[email protected]",
  "updatedBy": "[email protected]"
}

Get orchestration order for environments

get

Retrieves the deployment orchestration order for environments within a specific category in a repository. Returns an ordered array of environment names.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

repositoryIdentifierstringRequired

Repository identifier (e.g., owner/repo)

Example: myorg/myrepo

categorystring · enumRequired

Environment category

Possible values:

includeInactivestringRequired

Responses

200

Ordered array of environment names

application/json

string[]OptionalExample: ["dev1","dev2","dev3"]

400

Bad request - missing required parameters

403

Forbidden - Requires role: owner, application

get

/sfp/api/environments/orchestration-order

GET /sfp/api/environments/orchestration-order?repositoryIdentifier=myorg%2Fmyrepo&category=dev&includeInactive=text HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  "dev1",
  "dev2",
  "dev3"
]

Update orchestration order for environments

put

Updates the deployment orchestration order for environments within a specific category in a repository. Replaces the entire order with the provided array.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

repositoryIdentifierstringRequired

Repository identifier (e.g., owner/repo)

Example: myorg/myrepo

categorystring · enumRequired

Environment category

Possible values:

includeInactivestringRequired

Body

stringOptional

Responses

200

Updated orchestration order

application/json

string[]OptionalExample: ["dev3","dev1","dev2"]

400

Bad request - missing parameters or invalid environment names

403

Forbidden - Requires role: owner, application

put

/sfp/api/environments/orchestration-order

PUT /sfp/api/environments/orchestration-order?repositoryIdentifier=myorg%2Fmyrepo&category=dev&includeInactive=text HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 43

{
  "environmentOrder": [
    "dev1",
    "dev2",
    "dev3"
  ]
}

[
  "dev3",
  "dev1",
  "dev2"
]

get

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

sandboxNamestringRequired

productionOrgstringRequired

salesforceUsernamestringRequired

repositoryIdentifierstringRequired

Responses

403

Forbidden - Requires role: owner, application

get

/sfp/api/environments/find

GET /sfp/api/environments/find?sandboxName=text&productionOrg=text&salesforceUsername=text&repositoryIdentifier=text HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

403

Forbidden - Requires role: owner, application

No content

Get environment by name and repository

get

Retrieves detailed information about a specific environment by its name and repository identifier

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

namestringRequired

Environment name

Example: production

Query parameters

repositoryIdentifierstringRequired

Repository identifier (e.g., owner/repo)

Example: myorg/myrepo

authTypestring · enumOptional

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.

Possible values:

Responses

200

Environment details

No content

403

Forbidden - Requires role: member, owner, application

404

Environment not found

get

/sfp/api/environments/by-name/{name}

GET /sfp/api/environments/by-name/{name}?repositoryIdentifier=myorg%2Fmyrepo HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Delete environment by name

delete

Permanently deletes an environment by name and repository. Cannot delete a locked environment.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

namestringRequired

Environment name

Example: production

Query parameters

repositoryIdentifierstringRequired

Repository identifier (e.g., owner/repo)

Example: myorg/myrepo

Responses

204

Environment deleted successfully

403

Forbidden - Requires role: owner

404

Environment not found

409

Cannot delete locked environment

delete

/sfp/api/environments/by-name/{name}

DELETE /sfp/api/environments/by-name/{name}?repositoryIdentifier=myorg%2Fmyrepo HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update environment by name

patch

Updates environment properties by name and repository. Only provided fields will be updated.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

namestringRequired

Environment name

Example: production

Query parameters

repositoryIdentifierstringRequired

Repository identifier (e.g., owner/repo)

Example: myorg/myrepo

Body

stringOptional

Responses

200

Environment updated successfully

No content

403

Forbidden - Requires role: owner, application

404

Environment or Salesforce org not found

409

Environment name already exists

patch

/sfp/api/environments/by-name/{name}

PATCH /sfp/api/environments/by-name/{name}?repositoryIdentifier=myorg%2Fmyrepo HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 6

"text"

No content

Get environment by ID

get

Retrieves detailed information about a specific environment including its lock status

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

Environment ID

Example: 456e7890-e89b-12d3-a456-426614174001

Query parameters

authTypestring · enumOptional

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.

Possible values:

Responses

200

Environment details

application/json

anyOptionalExample:

{"id":"456e7890-e89b-12d3-a456-426614174001","repositoryIdentifier":"myorg/my-salesforce-project","repositoryName":"my-salesforce-project","name":"prod","description":"Production environment","category":"release","salesforceUsername":"[email protected]","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"}

403

Forbidden - Requires role: member, owner, application

404

Environment not found

get

/sfp/api/environments/{id}

GET /sfp/api/environments/{id} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "456e7890-e89b-12d3-a456-426614174001",
  "repositoryIdentifier": "myorg/my-salesforce-project",
  "repositoryName": "my-salesforce-project",
  "name": "prod",
  "description": "Production environment",
  "category": "release",
  "salesforceUsername": "[email protected]",
  "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"
}

Delete environment

delete

Permanently deletes an environment. Cannot delete a locked environment. All associated tags and audit records will be deleted.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

Environment ID

Example: 456e7890-e89b-12d3-a456-426614174001

Responses

204

Environment deleted successfully

403

Forbidden - Requires role: owner

404

Environment not found

409

Cannot delete locked environment

delete

/sfp/api/environments/{id}

DELETE /sfp/api/environments/{id} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update environment

patch

Updates environment properties. Only provided fields will be updated. Changing salesforceUsername will validate the new org exists.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

Environment ID

Example: 456e7890-e89b-12d3-a456-426614174001

Body

stringOptional

Responses

200

Environment updated successfully with current lock status

application/json

anyOptionalExample:

{"id":"456e7890-e89b-12d3-a456-426614174001","repositoryIdentifier":"myorg/myrepo","repositoryName":"myrepo","name":"prod","description":"Updated production environment","category":"release","salesforceUsername":"[email protected]","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":"[email protected]","updatedBy":"[email protected]"}

403

Forbidden - Requires role: owner, application

404

Environment or Salesforce org not found

409

Environment name already exists or Salesforce username conflict

patch

/sfp/api/environments/{id}

PATCH /sfp/api/environments/{id} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 46

{
  "tags": [
    "production",
    "critical",
    "monitored"
  ]
}

{
  "id": "456e7890-e89b-12d3-a456-426614174001",
  "repositoryIdentifier": "myorg/myrepo",
  "repositoryName": "myrepo",
  "name": "prod",
  "description": "Updated production environment",
  "category": "release",
  "salesforceUsername": "[email protected]",
  "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": "[email protected]",
  "updatedBy": "[email protected]"
}

Request a lock on an environment

post

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

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

Environment ID

Example: 456e7890-e89b-12d3-a456-426614174001

Query parameters

repositoryIdentifierstringRequired

Full repository identifier (e.g., owner/repo)

Example: myorg/my-salesforce-project

Body

stringOptional

Responses

201

Environment locked successfully

application/json

400

Missing repositoryIdentifier parameter

403

Forbidden - Requires role: owner, application

404

Environment not found

post

/sfp/api/environments/{id}/lock

POST /sfp/api/environments/{id}/lock?repositoryIdentifier=myorg%2Fmy-salesforce-project HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 65

{
  "leaseDurationSeconds": 3600,
  "reason": "Deploying release v2.1.0"
}

{
  "ticketId": "ticket_789abc12-3def-4567-8901-234567890abc"
}

Acquire a previously requested lock

put

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

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

Environment ID

Example: 456e7890-e89b-12d3-a456-426614174001

ticketIdstringRequired

Lock ticket ID obtained when requesting the lock

Example: ticket_789abc12-3def-4567-8901-234567890abc

Query parameters

repositoryIdentifierstringRequired

Full repository identifier (e.g., owner/repo)

Example: myorg/my-salesforce-project

authTypestring · enumOptional

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.

Possible values:

Responses

200

Lock acquired successfully with sensitive credentials

application/json

statusstringOptionalExample: acquired

environmentIdstringOptionalExample: 456e7890-e89b-12d3-a456-426614174001

environmentNamestringOptionalExample: production

salesforceUsernamestringOptionalExample: [email protected]

accessTokenstringOptional

Short-lived access token (returned when authType=accessToken)

Example: 00D...

instanceUrlstringOptional

Salesforce instance URL

Example: https://mycompany.my.salesforce.com

sfdxAuthUrlstringOptional

SFDX Auth URL with refresh token (returned when authType=sfdxAuthUrl)

Example: force://PlatformCLI::...

frontDoorUrlstringOptional

Front door URL for accessing the Salesforce org

Example: https://mycompany.my.salesforce.com/secur/frontdoor.jsp?sid=...

403

Forbidden - Requires role: owner, application

404

Ticket not found or expired

408

Timeout waiting for lock acquisition

put

/sfp/api/environments/{id}/lock/{ticketId}/acquire

PUT /sfp/api/environments/{id}/lock/{ticketId}/acquire?repositoryIdentifier=myorg%2Fmy-salesforce-project HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "status": "acquired",
  "environmentId": "456e7890-e89b-12d3-a456-426614174001",
  "environmentName": "production",
  "salesforceUsername": "[email protected]",
  "accessToken": "00D...",
  "instanceUrl": "https://mycompany.my.salesforce.com",
  "sfdxAuthUrl": "force://PlatformCLI::...",
  "frontDoorUrl": "https://mycompany.my.salesforce.com/secur/frontdoor.jsp?sid=..."
}

Unlock an environment

delete

Releases a lock on an environment using the ticket ID obtained when locking. Only the lock holder can release it unless admin/owner role.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

Environment ID

Example: 456e7890-e89b-12d3-a456-426614174001

ticketIdstringRequired

Lock ticket ID obtained when locking

Example: ticket_789abc12-3def-4567-8901-234567890abc

Query parameters

repositoryIdentifierstringRequired

Full repository identifier (e.g., owner/repo)

Example: myorg/my-salesforce-project

Responses

204

Environment unlocked successfully

400

Missing repositoryIdentifier parameter

403

Forbidden - Requires role: owner, application

404

Environment or lock not found

delete

/sfp/api/environments/{id}/lock/{ticketId}

DELETE /sfp/api/environments/{id}/lock/{ticketId}?repositoryIdentifier=myorg%2Fmy-salesforce-project HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Request a lock on an environment by name

post

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

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

namestringRequired

Environment name

Example: production

Query parameters

repositoryIdentifierstringRequired

Repository identifier (owner/repo)

Example: myorg/myrepo

Body

stringOptional

Responses

201

Environment locked successfully

application/json

400

Bad request

403

Forbidden - Requires role: owner, application

404

Environment not found

post

/sfp/api/environments/by-name/{name}/lock

POST /sfp/api/environments/by-name/{name}/lock?repositoryIdentifier=myorg%2Fmyrepo HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 63

{
  "leaseDurationMinutes": 60,
  "reason": "Deploying release v2.1.0"
}

{
  "ticketId": "ticket_789abc12-3def-4567-8901-234567890abc"
}

Acquire a previously requested lock by name

put

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

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

namestringRequired

Environment name

Example: production

ticketIdstringRequired

Lock ticket ID obtained when requesting the lock

Example: ticket_789abc12-3def-4567-8901-234567890abc

Query parameters

repositoryIdentifierstringRequired

Repository identifier (owner/repo)

Example: myorg/myrepo

authTypestring · enumOptional

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.

Possible values:

Responses

200

Lock acquired successfully with sensitive credentials

application/json

statusstringOptionalExample: acquired

environmentIdstringOptionalExample: 456e7890-e89b-12d3-a456-426614174001

environmentNamestringOptionalExample: production

salesforceUsernamestringOptionalExample: [email protected]

accessTokenstringOptional

Short-lived access token (returned when authType=accessToken)

Example: 00D...

instanceUrlstringOptional

Salesforce instance URL

Example: https://mycompany.my.salesforce.com

sfdxAuthUrlstringOptional

SFDX Auth URL with refresh token (returned when authType=sfdxAuthUrl)

Example: force://PlatformCLI::...

frontDoorUrlstringOptional

Front door URL for accessing the Salesforce org

Example: https://mycompany.my.salesforce.com/secur/frontdoor.jsp?sid=...

403

Forbidden - Requires role: owner, application

404

Environment or ticket not found

408

Timeout waiting for lock acquisition

put

/sfp/api/environments/by-name/{name}/lock/{ticketId}/acquire

PUT /sfp/api/environments/by-name/{name}/lock/{ticketId}/acquire?repositoryIdentifier=myorg%2Fmyrepo HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "status": "acquired",
  "environmentId": "456e7890-e89b-12d3-a456-426614174001",
  "environmentName": "production",
  "salesforceUsername": "[email protected]",
  "accessToken": "00D...",
  "instanceUrl": "https://mycompany.my.salesforce.com",
  "sfdxAuthUrl": "force://PlatformCLI::...",
  "frontDoorUrl": "https://mycompany.my.salesforce.com/secur/frontdoor.jsp?sid=..."
}

Unlock an environment by name

delete

Releases a lock on an environment using repository identifier, environment name, and ticket ID.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

namestringRequired

Environment name

Example: production

ticketIdstringRequired

Lock ticket ID obtained when locking

Example: ticket_789abc12-3def-4567-8901-234567890abc

Query parameters

repositoryIdentifierstringRequired

Repository identifier (owner/repo)

Example: myorg/myrepo

Responses

204

Environment unlocked successfully

400

Bad request

403

Forbidden - Requires role: owner, application

404

Environment not found

delete

/sfp/api/environments/by-name/{name}/lock/{ticketId}

DELETE /sfp/api/environments/by-name/{name}/lock/{ticketId}?repositoryIdentifier=myorg%2Fmyrepo HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Get access audit for environment

get

Retrieves audit logs for all access to this environment including reads, updates, locks, and frontdoor access

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

Environment ID

Example: 456e7890-e89b-12d3-a456-426614174001

Query parameters

limitnumberOptional

Maximum number of audit records to return (default: 100)

Example: 50

accessTypestringRequired

offsetnumberRequired

Responses

200

Environment access audit logs

application/json

arrayOptionalExample:

[{"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"}]

403

Forbidden - Requires role: owner, application

get

/sfp/api/environments/{id}/audit

GET /sfp/api/environments/{id}/audit?accessType=text&offset=1 HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "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"
  }
]

Get access audit for all environments in a repository

get

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

repositoryIdentifierstringRequired

Repository identifier (e.g., owner/repo)

Query parameters

limitnumberOptional

Maximum number of audit records (default: 100)

accessTypestringRequired

offsetnumberRequired

Responses

200

Repository environment access audit logs

application/json

arrayOptional

403

Forbidden - Requires role: owner, application

get

/sfp/api/environments/repository/{repositoryIdentifier}/audit

GET /sfp/api/environments/repository/{repositoryIdentifier}/audit?accessType=text&offset=1 HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[]

Get Salesforce frontdoor URL for environment

get

Generates a Salesforce frontdoor URL for the environment's org. Can either return the URL or redirect directly to Salesforce. Access is audited.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

Environment ID

Example: 456e7890-e89b-12d3-a456-426614174001

Query parameters

redirectbooleanOptional

Whether to redirect to Salesforce (default: true) or return the URL (false)

Example: false

Responses

200

Frontdoor URL retrieved (when redirect=false)

application/json

urlstringOptional

Salesforce frontdoor URL with session ID

Example: https://mycompany.my.salesforce.com/secur/frontdoor.jsp?sid=00D...&retURL=%2F

302

Redirect to Salesforce (when redirect=true)

400

Unable to generate frontdoor URL

403

Forbidden - Requires role: owner

404

Environment not found

get

/sfp/api/environments/{id}/frontdoor

GET /sfp/api/environments/{id}/frontdoor HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "url": "https://mycompany.my.salesforce.com/secur/frontdoor.jsp?sid=00D...&retURL=%2F"
}

Get installed artifacts for an environment

get

Retrieves all artifacts installed in the Salesforce org associated with this environment. Results are cached for 1 hour unless force refresh is requested.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

Environment ID (UUID)

Example: 123e4567-e89b-12d3-a456-426614174000

Query parameters

forcestring · enumOptional

Force refresh the cached data

Possible values:

Responses

200

List of installed artifacts retrieved successfully

application/json

environmentIdstringRequired

Environment ID

environmentNamestringRequired

Environment name

salesforceUsernamestringRequired

Salesforce username

retrievedAtstring · date-timeRequired

Timestamp when artifacts were retrieved

cachedbooleanRequired

Whether the response was served from cache

400

Unable to retrieve artifacts (e.g., authentication error)

403

Forbidden - Requires role: member, application

404

Environment not found

get

/sfp/api/environments/{id}/artifacts

GET /sfp/api/environments/{id}/artifacts HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "environmentId": "text",
  "environmentName": "text",
  "salesforceUsername": "text",
  "artifacts": [
    {
      "name": "text",
      "version": "text",
      "commitId": "text",
      "subscriberVersion": "text",
      "type": "text",
      "isInstalledBysfp": true
    }
  ],
  "retrievedAt": "2026-02-26T00:06:10.614Z",
  "cached": true
}

Get installed artifacts for an environment by name

get

Retrieves all artifacts installed in the Salesforce org associated with this environment by name. Results are cached for 1 hour unless force refresh is requested.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

namestringRequired

Environment name

Example: production

Query parameters

repositoryIdentifierstringRequired

Repository identifier (e.g., owner/repo)

Example: myorg/myrepo

forcestring · enumOptional

Force refresh the cached data

Possible values:

Responses

200

List of installed artifacts retrieved successfully

application/json

environmentIdstringRequired

Environment ID

environmentNamestringRequired

Environment name

salesforceUsernamestringRequired

Salesforce username

retrievedAtstring · date-timeRequired

Timestamp when artifacts were retrieved

cachedbooleanRequired

Whether the response was served from cache

400

Unable to retrieve artifacts (e.g., authentication error)

403

Forbidden - Requires role: member, application

404

Environment not found

get

/sfp/api/environments/by-name/{name}/artifacts

GET /sfp/api/environments/by-name/{name}/artifacts?repositoryIdentifier=myorg%2Fmyrepo HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "environmentId": "text",
  "environmentName": "text",
  "salesforceUsername": "text",
  "artifacts": [
    {
      "name": "text",
      "version": "text",
      "commitId": "text",
      "subscriberVersion": "text",
      "type": "text",
      "isInstalledBysfp": true
    }
  ],
  "retrievedAt": "2026-02-26T00:06:10.614Z",
  "cached": true
}

Get releases for an environment

get

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

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

Environment ID (UUID)

Query parameters

domainstringOptional

Filter releases by domain/release configuration name

Example: core

limitnumberOptional

Maximum number of releases to return

Example: 50

offsetnumberOptional

Number of releases to skip for pagination

Example: 0

includeChangelogbooleanOptional

Include changelog computation (commits, work items) for each release

Example: false

Responses

200

Releases retrieved successfully

application/json

environmentIdstringRequired

The environment ID

Example: 123e4567-e89b-12d3-a456-426614174000

environmentNamestringRequired

The environment name

Example: production

repositoryIdentifierstringRequired

Repository identifier

Example: myorg/myrepo

totalCountnumberRequired

Total count of releases (before pagination)

Example: 100

limitnumberRequired

Number of results returned (pagination limit)

Example: 50

offsetnumberRequired

Number of results skipped (pagination offset)

Example: 0

retrievedAtstring · date-timeRequired

ISO timestamp when the data was retrieved

Example: 2024-01-15T10:30:00.000Z

403

Forbidden - Requires role: member, owner, application

404

Environment not found

get

/sfp/api/environments/{id}/releases

GET /sfp/api/environments/{id}/releases HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

Get releases for an environment by name

get

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

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

namestringRequired

Environment name

Query parameters

repositoryIdentifierstringRequired

Repository identifier in format owner/repo

Example: myorg/myrepo

domainstringOptional

Filter releases by domain/release configuration name

Example: core

limitnumberOptional

Maximum number of releases to return

Example: 50

offsetnumberOptional

Number of releases to skip for pagination

Example: 0

includeChangelogbooleanOptional

Include changelog computation (commits, work items) for each release

Example: false

Responses

200

Releases retrieved successfully

application/json

environmentIdstringRequired

The environment ID

Example: 123e4567-e89b-12d3-a456-426614174000

environmentNamestringRequired

The environment name

Example: production

repositoryIdentifierstringRequired

Repository identifier

Example: myorg/myrepo

totalCountnumberRequired

Total count of releases (before pagination)

Example: 100

limitnumberRequired

Number of results returned (pagination limit)

Example: 50

offsetnumberRequired

Number of results skipped (pagination offset)

Example: 0

retrievedAtstring · date-timeRequired

ISO timestamp when the data was retrieved

Example: 2024-01-15T10:30:00.000Z

400

Missing or invalid parameters

403

Forbidden - Requires role: member, owner, application

404

Environment not found

get

/sfp/api/environments/by-name/{name}/releases

GET /sfp/api/environments/by-name/{name}/releases?repositoryIdentifier=myorg%2Fmyrepo HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

Compare artifacts across environments

get

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

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

repositoryIdentifierstringRequired

Repository identifier in format owner/repo

Example: myorg/myrepo

environmentsstringOptional

Comma-separated list of environment names to compare. If not provided, all environments are compared.

Example: dev,staging,prod

categorystring · enumOptional

Filter environments by category

Possible values:

forcebooleanOptional

Force refresh all caches, bypassing the 30-minute cache TTL (default: false)

Responses

200

Artifacts comparison completed successfully

application/json

retrievedAtstring · date-timeRequired

Timestamp when the comparison was performed

400

Invalid parameters or no environments found

401

Unauthorized

403

Forbidden - Requires role: member, application

get

/sfp/api/environments/artifacts/compare

GET /sfp/api/environments/artifacts/compare?repositoryIdentifier=myorg%2Fmyrepo HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "summary": {
    "totalPackages": 15,
    "packagesByType": {
      "Unlocked": 5,
      "Source/Data": 3,
      "Managed": 2
    },
    "outOfSyncCount": 3,
    "outOfSyncPercentage": 20,
    "environments": [
      "Dev",
      "Test",
      "Staging",
      "Production"
    ]
  },
  "packages": [
    {
      "name": "text",
      "type": "text",
      "isOutOfSync": true,
      "versions": {
        "ANY_ADDITIONAL_PROPERTY": null
      }
    }
  ],
  "retrievedAt": "2026-02-26T00:06:10.614Z",
  "fetchStatus": [
    {
      "environmentName": "text",
      "success": true,
      "cached": true,
      "retrievedAt": "2026-02-26T00:06:10.614Z",
      "error": "text"
    }
  ]
}

Good night

hashtagGet all environments

hashtagCreate a new environment

hashtagGet orchestration order for environments

hashtagUpdate orchestration order for environments

hashtagGet environment by name and repository

hashtagDelete environment by name

hashtagUpdate environment by name

hashtagGet environment by ID

hashtagDelete environment

hashtagUpdate environment

hashtagRequest a lock on an environment

hashtagAcquire a previously requested lock

hashtagUnlock an environment

hashtagRequest a lock on an environment by name

hashtagAcquire a previously requested lock by name

hashtagUnlock an environment by name

hashtagGet access audit for environment

hashtagGet access audit for all environments in a repository

hashtagGet Salesforce frontdoor URL for environment

hashtagGet installed artifacts for an environment

hashtagGet installed artifacts for an environment by name

hashtagGet releases for an environment

hashtagGet releases for an environment by name

hashtagCompare artifacts across environments

Get all environments

Create a new environment

Get orchestration order for environments

Update orchestration order for environments

Get environment by name and repository

Delete environment by name

Update environment by name

Get environment by ID

Delete environment

Update environment

Request a lock on an environment

Acquire a previously requested lock

Unlock an environment

Request a lock on an environment by name

Acquire a previously requested lock by name

Unlock an environment by name

Get access audit for environment

Get access audit for all environments in a repository

Get Salesforce frontdoor URL for environment

Get installed artifacts for an environment

Get installed artifacts for an environment by name

Get releases for an environment

Get releases for an environment by name

Compare artifacts across environments