# Environments

## Get all environments

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/environments":{"get":{"operationId":"EnvironmentsController_findAll","summary":"Get all environments","description":"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.","parameters":[{"name":"repositoryIdentifier","required":false,"in":"query","description":"Filter by repository identifier (e.g., owner/repo)","schema":{"type":"string"}},{"name":"category","required":false,"in":"query","description":"Filter by environment category. When specified, returns a flat array of that category only.","schema":{"enum":["dev","test","snapshot","release"],"type":"string"}},{"name":"isActive","required":false,"in":"query","description":"Filter by active status","schema":{"type":"boolean"}},{"name":"branch","required":false,"in":"query","description":"Filter by git branch","schema":{"type":"string"}},{"name":"tags","required":false,"in":"query","description":"Filter by tags (all specified tags must match)","schema":{"type":"array","items":{}}}],"responses":{"200":{"description":"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.","content":{"application/json":{}}},"403":{"description":"Forbidden - Requires role: member, owner, application"}},"tags":["Environments"]}}}}
```

## Create a new environment

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/environments":{"post":{"operationId":"EnvironmentsController_create","summary":"Create a new environment","description":"Creates a new environment linked to a repository and Salesforce org. The environment can be locked using the mutex system for exclusive access.","parameters":[],"requestBody":{"required":true,"description":"Environment creation details","content":{"application/json":{"schema":{"type":"string"}}}},"responses":{"201":{"description":"Environment created successfully with lock status information","content":{"application/json":{"schema":{}}}},"400":{"description":"Bad request"},"403":{"description":"Forbidden - Requires role: owner, application"},"404":{"description":"Repository or Salesforce org not found"},"409":{"description":"Environment already exists or Salesforce username already registered"}},"tags":["Environments"]}}}}
```

## Get orchestration order for environments

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/environments/orchestration-order":{"get":{"operationId":"EnvironmentsController_getOrchestrationOrder","summary":"Get orchestration order for environments","description":"Retrieves the deployment orchestration order for environments within a specific category in a repository. Returns an ordered array of environment names.","parameters":[{"name":"repositoryIdentifier","required":true,"in":"query","description":"Repository identifier (e.g., owner/repo)","schema":{"type":"string"}},{"name":"category","required":true,"in":"query","description":"Environment category","schema":{"enum":["dev","test","snapshot","release"],"type":"string"}},{"name":"includeInactive","required":true,"in":"query","schema":{"type":"string"}},{"name":"branch","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Ordered array of environment names","content":{"application/json":{"schema":{"type":"array","items":{"type":"string"}}}}},"400":{"description":"Bad request - missing required parameters"},"403":{"description":"Forbidden - Requires role: owner, application"}},"tags":["Environments"]}}}}
```

## Update orchestration order for environments

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/environments/orchestration-order":{"put":{"operationId":"EnvironmentsController_updateOrchestrationOrder","summary":"Update orchestration order for environments","description":"Updates the deployment orchestration order for environments within a specific category in a repository. Replaces the entire order with the provided array.","parameters":[{"name":"repositoryIdentifier","required":true,"in":"query","description":"Repository identifier (e.g., owner/repo)","schema":{"type":"string"}},{"name":"category","required":true,"in":"query","description":"Environment category","schema":{"enum":["dev","test","snapshot","release"],"type":"string"}},{"name":"includeInactive","required":true,"in":"query","schema":{"type":"string"}},{"name":"branch","required":true,"in":"query","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"New orchestration order","content":{"application/json":{"schema":{"type":"string"}}}},"responses":{"200":{"description":"Updated orchestration order","content":{"application/json":{"schema":{"type":"array","items":{"type":"string"}}}}},"400":{"description":"Bad request - missing parameters or invalid environment names"},"403":{"description":"Forbidden - Requires role: owner, application"}},"tags":["Environments"]}}}}
```

## GET /sfp/api/environments/find

>

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/environments/find":{"get":{"operationId":"EnvironmentsController_findEnvironments","parameters":[{"name":"sandboxName","required":true,"in":"query","schema":{"type":"string"}},{"name":"productionOrg","required":true,"in":"query","schema":{"type":"string"}},{"name":"salesforceUsername","required":true,"in":"query","schema":{"type":"string"}},{"name":"name","required":true,"in":"query","schema":{"type":"string"}},{"name":"repositoryIdentifier","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"403":{"description":"Forbidden - Requires role: owner, application"}},"tags":["Environments"]}}}}
```

## Get environment by name and repository

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/environments/by-name/{name}":{"get":{"operationId":"EnvironmentsController_findByName","summary":"Get environment by name and repository","description":"Retrieves detailed information about a specific environment by its name and repository identifier","parameters":[{"name":"name","required":true,"in":"path","description":"Environment name","schema":{"type":"string"}},{"name":"repositoryIdentifier","required":true,"in":"query","description":"Repository identifier (e.g., owner/repo)","schema":{"type":"string"}},{"name":"authType","required":false,"in":"query","description":"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.","schema":{"enum":["accessToken","sfdxAuthUrl"],"type":"string"}}],"responses":{"200":{"description":"Environment details"},"403":{"description":"Forbidden - Requires role: member, owner, application"},"404":{"description":"Environment not found"}},"tags":["Environments"]}}}}
```

## Delete environment by name

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/environments/by-name/{name}":{"delete":{"operationId":"EnvironmentsController_removeByName","summary":"Delete environment by name","description":"Permanently deletes an environment by name and repository. Cannot delete a locked environment.","parameters":[{"name":"name","required":true,"in":"path","description":"Environment name","schema":{"type":"string"}},{"name":"repositoryIdentifier","required":true,"in":"query","description":"Repository identifier (e.g., owner/repo)","schema":{"type":"string"}}],"responses":{"204":{"description":"Environment deleted successfully"},"403":{"description":"Forbidden - Requires role: owner"},"404":{"description":"Environment not found"},"409":{"description":"Cannot delete locked environment"}},"tags":["Environments"]}}}}
```

## Update environment by name

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/environments/by-name/{name}":{"patch":{"operationId":"EnvironmentsController_updateByName","summary":"Update environment by name","description":"Updates environment properties by name and repository. Only provided fields will be updated.","parameters":[{"name":"name","required":true,"in":"path","description":"Environment name","schema":{"type":"string"}},{"name":"repositoryIdentifier","required":true,"in":"query","description":"Repository identifier (e.g., owner/repo)","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Fields to update","content":{"application/json":{"schema":{"type":"string"}}}},"responses":{"200":{"description":"Environment updated successfully"},"403":{"description":"Forbidden - Requires role: owner, application"},"404":{"description":"Environment or Salesforce org not found"},"409":{"description":"Environment name already exists"}},"tags":["Environments"]}}}}
```

## Get environment by ID

> Retrieves detailed information about a specific environment including its lock status

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/environments/{id}":{"get":{"operationId":"EnvironmentsController_findOne","summary":"Get environment by ID","description":"Retrieves detailed information about a specific environment including its lock status","parameters":[{"name":"id","required":true,"in":"path","description":"Environment ID","schema":{"type":"string"}},{"name":"authType","required":false,"in":"query","description":"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.","schema":{"enum":["accessToken","sfdxAuthUrl"],"type":"string"}}],"responses":{"200":{"description":"Environment details","content":{"application/json":{"schema":{}}}},"403":{"description":"Forbidden - Requires role: member, owner, application"},"404":{"description":"Environment not found"}},"tags":["Environments"]}}}}
```

## Delete environment

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/environments/{id}":{"delete":{"operationId":"EnvironmentsController_remove","summary":"Delete environment","description":"Permanently deletes an environment. Cannot delete a locked environment. All associated tags and audit records will be deleted.","parameters":[{"name":"id","required":true,"in":"path","description":"Environment ID","schema":{"type":"string"}}],"responses":{"204":{"description":"Environment deleted successfully"},"403":{"description":"Forbidden - Requires role: owner"},"404":{"description":"Environment not found"},"409":{"description":"Cannot delete locked environment"}},"tags":["Environments"]}}}}
```

## Update environment

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/environments/{id}":{"patch":{"operationId":"EnvironmentsController_update","summary":"Update environment","description":"Updates environment properties. Only provided fields will be updated. Changing salesforceUsername will validate the new org exists.","parameters":[{"name":"id","required":true,"in":"path","description":"Environment ID","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Fields to update","content":{"application/json":{"schema":{"type":"string"}}}},"responses":{"200":{"description":"Environment updated successfully with current lock status","content":{"application/json":{"schema":{}}}},"403":{"description":"Forbidden - Requires role: owner, application"},"404":{"description":"Environment or Salesforce org not found"},"409":{"description":"Environment name already exists or Salesforce username conflict"}},"tags":["Environments"]}}}}
```

## Request a lock on an environment

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/environments/{id}/lock":{"post":{"operationId":"EnvironmentsController_lockEnvironment","summary":"Request a lock on an environment","description":"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.","parameters":[{"name":"id","required":true,"in":"path","description":"Environment ID","schema":{"type":"string"}},{"name":"repositoryIdentifier","required":true,"in":"query","description":"Full repository identifier (e.g., owner/repo)","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Lock configuration","content":{"application/json":{"schema":{"type":"string"}}}},"responses":{"201":{"description":"Environment locked successfully","content":{"application/json":{"schema":{"type":"object","properties":{"ticketId":{"type":"string","description":"Unique ticket ID for this lock. Use this to release the lock."}}}}}},"400":{"description":"Missing repositoryIdentifier parameter"},"403":{"description":"Forbidden - Requires role: owner, application"},"404":{"description":"Environment not found"}},"tags":["Environments"]}}}}
```

## Acquire a previously requested lock

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/environments/{id}/lock/{ticketId}/acquire":{"put":{"operationId":"EnvironmentsController_acquireEnvironmentLock","summary":"Acquire a previously requested lock","description":"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.","parameters":[{"name":"id","required":true,"in":"path","description":"Environment ID","schema":{"type":"string"}},{"name":"ticketId","required":true,"in":"path","description":"Lock ticket ID obtained when requesting the lock","schema":{"type":"string"}},{"name":"repositoryIdentifier","required":true,"in":"query","description":"Full repository identifier (e.g., owner/repo)","schema":{"type":"string"}},{"name":"authType","required":false,"in":"query","description":"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.","schema":{"enum":["accessToken","sfdxAuthUrl"],"type":"string"}}],"responses":{"200":{"description":"Lock acquired successfully with sensitive credentials","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"environmentId":{"type":"string"},"environmentName":{"type":"string"},"salesforceUsername":{"type":"string"},"accessToken":{"type":"string","description":"Short-lived access token (returned when authType=accessToken)"},"instanceUrl":{"type":"string","description":"Salesforce instance URL"},"sfdxAuthUrl":{"type":"string","description":"SFDX Auth URL with refresh token (returned when authType=sfdxAuthUrl)"},"frontDoorUrl":{"type":"string","description":"Front door URL for accessing the Salesforce org"}}}}}},"403":{"description":"Forbidden - Requires role: owner, application"},"404":{"description":"Ticket not found or expired"},"408":{"description":"Timeout waiting for lock acquisition"}},"tags":["Environments"]}}}}
```

## Unlock an environment

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/environments/{id}/lock/{ticketId}":{"delete":{"operationId":"EnvironmentsController_unlockEnvironment","summary":"Unlock an environment","description":"Releases a lock on an environment using the ticket ID obtained when locking. Only the lock holder can release it unless admin/owner role.","parameters":[{"name":"id","required":true,"in":"path","description":"Environment ID","schema":{"type":"string"}},{"name":"ticketId","required":true,"in":"path","description":"Lock ticket ID obtained when locking","schema":{"type":"string"}},{"name":"repositoryIdentifier","required":true,"in":"query","description":"Full repository identifier (e.g., owner/repo)","schema":{"type":"string"}}],"responses":{"204":{"description":"Environment unlocked successfully"},"400":{"description":"Missing repositoryIdentifier parameter"},"403":{"description":"Forbidden - Requires role: owner, application"},"404":{"description":"Environment or lock not found"}},"tags":["Environments"]}}}}
```

## Request a lock on an environment by name

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/environments/by-name/{name}/lock":{"post":{"operationId":"EnvironmentsController_lockEnvironmentByName","summary":"Request a lock on an environment by name","description":"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.","parameters":[{"name":"name","required":true,"in":"path","description":"Environment name","schema":{"type":"string"}},{"name":"repositoryIdentifier","required":true,"in":"query","description":"Repository identifier (owner/repo)","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Lock configuration","content":{"application/json":{"schema":{"type":"string"}}}},"responses":{"201":{"description":"Environment locked successfully","content":{"application/json":{"schema":{"type":"object","properties":{"ticketId":{"type":"string","description":"Unique ticket ID for this lock. Use this to release the lock."}}}}}},"400":{"description":"Bad request"},"403":{"description":"Forbidden - Requires role: owner, application"},"404":{"description":"Environment not found"}},"tags":["Environments"]}}}}
```

## Acquire a previously requested lock by name

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/environments/by-name/{name}/lock/{ticketId}/acquire":{"put":{"operationId":"EnvironmentsController_acquireEnvironmentLockByName","summary":"Acquire a previously requested lock by name","description":"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.","parameters":[{"name":"name","required":true,"in":"path","description":"Environment name","schema":{"type":"string"}},{"name":"ticketId","required":true,"in":"path","description":"Lock ticket ID obtained when requesting the lock","schema":{"type":"string"}},{"name":"repositoryIdentifier","required":true,"in":"query","description":"Repository identifier (owner/repo)","schema":{"type":"string"}},{"name":"authType","required":false,"in":"query","description":"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.","schema":{"enum":["accessToken","sfdxAuthUrl"],"type":"string"}}],"responses":{"200":{"description":"Lock acquired successfully with sensitive credentials","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"environmentId":{"type":"string"},"environmentName":{"type":"string"},"salesforceUsername":{"type":"string"},"accessToken":{"type":"string","description":"Short-lived access token (returned when authType=accessToken)"},"instanceUrl":{"type":"string","description":"Salesforce instance URL"},"sfdxAuthUrl":{"type":"string","description":"SFDX Auth URL with refresh token (returned when authType=sfdxAuthUrl)"},"frontDoorUrl":{"type":"string","description":"Front door URL for accessing the Salesforce org"}}}}}},"403":{"description":"Forbidden - Requires role: owner, application"},"404":{"description":"Environment or ticket not found"},"408":{"description":"Timeout waiting for lock acquisition"}},"tags":["Environments"]}}}}
```

## Unlock an environment by name

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/environments/by-name/{name}/lock/{ticketId}":{"delete":{"operationId":"EnvironmentsController_unlockEnvironmentByName","summary":"Unlock an environment by name","description":"Releases a lock on an environment using repository identifier, environment name, and ticket ID.","parameters":[{"name":"name","required":true,"in":"path","description":"Environment name","schema":{"type":"string"}},{"name":"ticketId","required":true,"in":"path","description":"Lock ticket ID obtained when locking","schema":{"type":"string"}},{"name":"repositoryIdentifier","required":true,"in":"query","description":"Repository identifier (owner/repo)","schema":{"type":"string"}}],"responses":{"204":{"description":"Environment unlocked successfully"},"400":{"description":"Bad request"},"403":{"description":"Forbidden - Requires role: owner, application"},"404":{"description":"Environment not found"}},"tags":["Environments"]}}}}
```

## Get access audit for environment

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/environments/{id}/audit":{"get":{"operationId":"EnvironmentsController_getEnvironmentAudit","summary":"Get access audit for environment","description":"Retrieves audit logs for all access to this environment including reads, updates, locks, and frontdoor access","parameters":[{"name":"id","required":true,"in":"path","description":"Environment ID","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of audit records to return (default: 100)","schema":{"type":"number"}},{"name":"accessType","required":true,"in":"query","schema":{"type":"string"}},{"name":"offset","required":true,"in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":"Environment access audit logs","content":{"application/json":{"schema":{"type":"array"}}}},"403":{"description":"Forbidden - Requires role: owner, application"}},"tags":["Environments"]}}}}
```

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

> Get access audit for all environments in a repository

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/environments/repository/{repositoryIdentifier}/audit":{"get":{"operationId":"EnvironmentsController_getRepositoryEnvironmentAudit","summary":"Get access audit for all environments in a repository","parameters":[{"name":"repositoryIdentifier","required":true,"in":"path","description":"Repository identifier (e.g., owner/repo)","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of audit records (default: 100)","schema":{"type":"number"}},{"name":"accessType","required":true,"in":"query","schema":{"type":"string"}},{"name":"offset","required":true,"in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":"Repository environment access audit logs","content":{"application/json":{"schema":{"type":"array"}}}},"403":{"description":"Forbidden - Requires role: owner, application"}},"tags":["Environments"]}}}}
```

## Get Salesforce frontdoor URL for environment

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/environments/{id}/frontdoor":{"get":{"operationId":"EnvironmentsController_getFrontdoorUrl","summary":"Get Salesforce frontdoor URL for environment","description":"Generates a Salesforce frontdoor URL for the environment's org. Can either return the URL or redirect directly to Salesforce. Access is audited.","parameters":[{"name":"id","required":true,"in":"path","description":"Environment ID","schema":{"type":"string"}},{"name":"redirect","required":false,"in":"query","description":"Whether to redirect to Salesforce (default: true) or return the URL (false)","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Frontdoor URL retrieved (when redirect=false)","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Salesforce frontdoor URL with session ID"}}}}}},"302":{"description":"Redirect to Salesforce (when redirect=true)"},"400":{"description":"Unable to generate frontdoor URL"},"403":{"description":"Forbidden - Requires role: owner"},"404":{"description":"Environment not found"}},"tags":["Environments"]}}}}
```

## Get installed artifacts for an environment

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"EnvironmentArtifactsResponseDto":{"type":"object","properties":{"environmentId":{"type":"string","description":"Environment ID"},"environmentName":{"type":"string","description":"Environment name"},"salesforceUsername":{"type":"string","description":"Salesforce username"},"artifacts":{"description":"List of installed artifacts","type":"array","items":{"$ref":"#/components/schemas/EnvironmentArtifactDto"}},"retrievedAt":{"format":"date-time","type":"string","description":"Timestamp when artifacts were retrieved"},"cached":{"type":"boolean","description":"Whether the response was served from cache"}},"required":["environmentId","environmentName","salesforceUsername","artifacts","retrievedAt","cached"]},"EnvironmentArtifactDto":{"type":"object","properties":{"name":{"type":"string","description":"Artifact name"},"version":{"type":"string","description":"Artifact version"},"commitId":{"type":"string","description":"Commit ID"},"subscriberVersion":{"type":"string","description":"Subscriber package version ID"},"type":{"type":"string","description":"Artifact type (Source/Data, Unlocked, OrgDependendent, Managed)"},"isInstalledBysfp":{"type":"boolean","description":"Whether artifact was installed by SFP"}},"required":["name","version","isInstalledBysfp"]}}},"paths":{"/sfp/api/environments/{id}/artifacts":{"get":{"operationId":"EnvironmentsController_getArtifacts","summary":"Get installed artifacts for an environment","description":"Retrieves all artifacts installed in the Salesforce org associated with this environment. Results are cached for 1 hour unless force refresh is requested.","parameters":[{"name":"id","required":true,"in":"path","description":"Environment ID (UUID)","schema":{"type":"string"}},{"name":"force","required":false,"in":"query","description":"Force refresh the cached data","schema":{"enum":["true","false"],"type":"string"}}],"responses":{"200":{"description":"List of installed artifacts retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentArtifactsResponseDto"}}}},"400":{"description":"Unable to retrieve artifacts (e.g., authentication error)"},"403":{"description":"Forbidden - Requires role: member, application"},"404":{"description":"Environment not found"}},"tags":["Environments"]}}}}
```

## Get installed artifacts for an environment by name

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"EnvironmentArtifactsResponseDto":{"type":"object","properties":{"environmentId":{"type":"string","description":"Environment ID"},"environmentName":{"type":"string","description":"Environment name"},"salesforceUsername":{"type":"string","description":"Salesforce username"},"artifacts":{"description":"List of installed artifacts","type":"array","items":{"$ref":"#/components/schemas/EnvironmentArtifactDto"}},"retrievedAt":{"format":"date-time","type":"string","description":"Timestamp when artifacts were retrieved"},"cached":{"type":"boolean","description":"Whether the response was served from cache"}},"required":["environmentId","environmentName","salesforceUsername","artifacts","retrievedAt","cached"]},"EnvironmentArtifactDto":{"type":"object","properties":{"name":{"type":"string","description":"Artifact name"},"version":{"type":"string","description":"Artifact version"},"commitId":{"type":"string","description":"Commit ID"},"subscriberVersion":{"type":"string","description":"Subscriber package version ID"},"type":{"type":"string","description":"Artifact type (Source/Data, Unlocked, OrgDependendent, Managed)"},"isInstalledBysfp":{"type":"boolean","description":"Whether artifact was installed by SFP"}},"required":["name","version","isInstalledBysfp"]}}},"paths":{"/sfp/api/environments/by-name/{name}/artifacts":{"get":{"operationId":"EnvironmentsController_getArtifactsByName","summary":"Get installed artifacts for an environment by name","description":"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.","parameters":[{"name":"name","required":true,"in":"path","description":"Environment name","schema":{"type":"string"}},{"name":"repositoryIdentifier","required":true,"in":"query","description":"Repository identifier (e.g., owner/repo)","schema":{"type":"string"}},{"name":"force","required":false,"in":"query","description":"Force refresh the cached data","schema":{"enum":["true","false"],"type":"string"}}],"responses":{"200":{"description":"List of installed artifacts retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentArtifactsResponseDto"}}}},"400":{"description":"Unable to retrieve artifacts (e.g., authentication error)"},"403":{"description":"Forbidden - Requires role: member, application"},"404":{"description":"Environment not found"}},"tags":["Environments"]}}}}
```

## Get releases for an environment

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"EnvironmentReleasesResponseDto":{"type":"object","properties":{"environmentId":{"type":"string","description":"The environment ID"},"environmentName":{"type":"string","description":"The environment name"},"repositoryIdentifier":{"type":"string","description":"Repository identifier"},"releases":{"description":"List of releases for this environment","type":"array","items":{"$ref":"#/components/schemas/ReleaseDto"}},"totalCount":{"type":"number","description":"Total count of releases (before pagination)"},"limit":{"type":"number","description":"Number of results returned (pagination limit)"},"offset":{"type":"number","description":"Number of results skipped (pagination offset)"},"retrievedAt":{"format":"date-time","type":"string","description":"ISO timestamp when the data was retrieved"}},"required":["environmentId","environmentName","repositoryIdentifier","releases","totalCount","limit","offset","retrievedAt"]},"ReleaseDto":{"type":"object","properties":{"name":{"type":"string","description":"The release name"},"domain":{"type":"string","description":"The release domain/configuration name"},"targetOrg":{"type":"string","description":"The target organization where this release was deployed"},"publishedAt":{"type":"string","description":"ISO timestamp when the release was published"},"repoIdentifier":{"type":"string","description":"Repository identifier for this release"},"metadata":{"type":"object","description":"Additional metadata about the release"},"changelog":{"type":"object","description":"Changelog information including commits and work items (only present when includeChangelog=true)"}},"required":["name","targetOrg","publishedAt","repoIdentifier"]}}},"paths":{"/sfp/api/environments/{id}/releases":{"get":{"operationId":"EnvironmentReleasesController_getReleases","summary":"Get releases for an environment","description":"Retrieves all releases that have been deployed to a specific environment. \n        Releases are sorted by publication date with the most recent first. \n        \n        You can optionally filter releases by domain (release configuration) and paginate through results.\n        \n        This endpoint returns release metadata that was captured during the release process, including:\n        - Release name and domain\n        - Publication timestamp\n        - Repository information\n        - Any additional metadata from the release\n        \n        Returns an empty list if no releases have been recorded for the environment.","parameters":[{"name":"id","required":true,"in":"path","description":"Environment ID (UUID)","schema":{"type":"string"}},{"name":"domain","required":false,"in":"query","description":"Filter releases by domain/release configuration name","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of releases to return","schema":{"type":"number"}},{"name":"offset","required":false,"in":"query","description":"Number of releases to skip for pagination","schema":{"type":"number"}},{"name":"includeChangelog","required":false,"in":"query","description":"Include changelog computation (commits, work items) for each release","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Releases retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentReleasesResponseDto"}}}},"403":{"description":"Forbidden - Requires role: member, owner, application"},"404":{"description":"Environment not found"}},"tags":["Environments"]}}}}
```

## Get releases for an environment by name

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"EnvironmentReleasesResponseDto":{"type":"object","properties":{"environmentId":{"type":"string","description":"The environment ID"},"environmentName":{"type":"string","description":"The environment name"},"repositoryIdentifier":{"type":"string","description":"Repository identifier"},"releases":{"description":"List of releases for this environment","type":"array","items":{"$ref":"#/components/schemas/ReleaseDto"}},"totalCount":{"type":"number","description":"Total count of releases (before pagination)"},"limit":{"type":"number","description":"Number of results returned (pagination limit)"},"offset":{"type":"number","description":"Number of results skipped (pagination offset)"},"retrievedAt":{"format":"date-time","type":"string","description":"ISO timestamp when the data was retrieved"}},"required":["environmentId","environmentName","repositoryIdentifier","releases","totalCount","limit","offset","retrievedAt"]},"ReleaseDto":{"type":"object","properties":{"name":{"type":"string","description":"The release name"},"domain":{"type":"string","description":"The release domain/configuration name"},"targetOrg":{"type":"string","description":"The target organization where this release was deployed"},"publishedAt":{"type":"string","description":"ISO timestamp when the release was published"},"repoIdentifier":{"type":"string","description":"Repository identifier for this release"},"metadata":{"type":"object","description":"Additional metadata about the release"},"changelog":{"type":"object","description":"Changelog information including commits and work items (only present when includeChangelog=true)"}},"required":["name","targetOrg","publishedAt","repoIdentifier"]}}},"paths":{"/sfp/api/environments/by-name/{name}/releases":{"get":{"operationId":"EnvironmentReleasesController_getReleasesByName","summary":"Get releases for an environment by name","description":"Retrieves all releases for an environment identified by its name and repository.\n        This is a convenience endpoint that works the same as the ID-based endpoint.\n        \n        See GET /environments/:id/releases for full documentation.","parameters":[{"name":"name","required":true,"in":"path","description":"Environment name","schema":{"type":"string"}},{"name":"repositoryIdentifier","required":true,"in":"query","description":"Repository identifier in format owner/repo","schema":{"type":"string"}},{"name":"domain","required":false,"in":"query","description":"Filter releases by domain/release configuration name","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of releases to return","schema":{"type":"number"}},{"name":"offset","required":false,"in":"query","description":"Number of releases to skip for pagination","schema":{"type":"number"}},{"name":"includeChangelog","required":false,"in":"query","description":"Include changelog computation (commits, work items) for each release","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Releases retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentReleasesResponseDto"}}}},"400":{"description":"Missing or invalid parameters"},"403":{"description":"Forbidden - Requires role: member, owner, application"},"404":{"description":"Environment not found"}},"tags":["Environments"]}}}}
```

## Compare artifacts across environments

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

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"ArtifactsCompareResponseDto":{"type":"object","properties":{"summary":{"description":"Summary statistics","allOf":[{"$ref":"#/components/schemas/ArtifactsCompareSummaryDto"}]},"packages":{"description":"Package comparison details","type":"array","items":{"$ref":"#/components/schemas/PackageComparisonDto"}},"retrievedAt":{"format":"date-time","type":"string","description":"Timestamp when the comparison was performed"},"fetchStatus":{"description":"Fetch status for each environment","type":"array","items":{"$ref":"#/components/schemas/EnvironmentFetchStatusDto"}}},"required":["summary","packages","retrievedAt","fetchStatus"]},"ArtifactsCompareSummaryDto":{"type":"object","properties":{"totalPackages":{"type":"number","description":"Total number of unique packages across all environments"},"packagesByType":{"type":"object","description":"Count of packages by type","additionalProperties":{"type":"number"}},"outOfSyncCount":{"type":"number","description":"Number of packages that are out of sync"},"outOfSyncPercentage":{"type":"number","description":"Percentage of packages that are out of sync"},"environments":{"description":"List of environment names included in the comparison (in orchestration order)","type":"array","items":{"type":"string"}}},"required":["totalPackages","packagesByType","outOfSyncCount","outOfSyncPercentage","environments"]},"PackageComparisonDto":{"type":"object","properties":{"name":{"type":"string","description":"Package name"},"type":{"type":"string","description":"Package type (e.g., Unlocked, Source/Data, Managed)"},"isOutOfSync":{"type":"boolean","description":"Whether the package is out of sync across environments"},"versions":{"type":"object","description":"Version information per environment. Key is environment name, value is version info or null if not installed.","additionalProperties":{"oneOf":[{"$ref":"#/components/schemas/ArtifactVersionInfoDto"},{"type":"null"}]}}},"required":["name","type","isOutOfSync","versions"]},"EnvironmentFetchStatusDto":{"type":"object","properties":{"environmentName":{"type":"string","description":"Environment name"},"success":{"type":"boolean","description":"Whether the fetch was successful"},"cached":{"type":"boolean","description":"Whether the result was served from cache"},"retrievedAt":{"format":"date-time","type":"string","description":"Timestamp when artifacts were retrieved"},"error":{"type":"string","description":"Error message if fetch failed"}},"required":["environmentName","success","cached","retrievedAt"]}}},"paths":{"/sfp/api/environments/artifacts/compare":{"get":{"operationId":"EnvironmentArtifactsController_compareArtifacts","summary":"Compare artifacts across environments","description":"Compares package versions across all environments in a repository to detect version drift.\n\nThis endpoint:\n- Fetches artifacts from all matching environments in parallel\n- Uses caching (30 minute TTL) for performance\n- Handles partial failures gracefully (returns results for successful environments)\n- Uses dynamic per-package baseline (last non-N/A environment from right)\n\nA package is considered \"out of sync\" if any of its versions differ from the baseline.\nThe baseline for each package is determined by finding the last environment (in orchestration order)\nthat has a non-N/A version for that package.","parameters":[{"name":"repositoryIdentifier","required":true,"in":"query","description":"Repository identifier in format owner/repo","schema":{"type":"string"}},{"name":"environments","required":false,"in":"query","description":"Comma-separated list of environment names to compare. If not provided, all environments are compared.","schema":{"type":"string"}},{"name":"category","required":false,"in":"query","description":"Filter environments by category","schema":{"enum":["dev","test","snapshot","release"],"type":"string"}},{"name":"force","required":false,"in":"query","description":"Force refresh all caches, bypassing the 30-minute cache TTL (default: false)","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Artifacts comparison completed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArtifactsCompareResponseDto"}}}},"400":{"description":"Invalid parameters or no environments found"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - Requires role: member, application"}},"tags":["Environments"]}}}}
```