# Review Environments

## Assign a review environment from pool

> Fetches an available environment from the specified pool and assigns it to a PR, issue, user, or custom identifier. If an active assignment already exists, it will be reused.

```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":{"AssignReviewEnvironmentDto":{"type":"object","properties":{"assignmentType":{"description":"Type of assignment for the review environment","type":"string","enum":["pr","issue","user","custom"]},"assignmentId":{"description":"Unique identifier for the assignment (e.g., \"123\" for PR number)","type":"string","pattern":"^[a-zA-Z0-9@._-]+$"},"repositoryIdentifier":{"description":"Repository identifier in format owner/repo or org/project/repo","type":"string","pattern":"^[a-zA-Z0-9_.-]+\\/[a-zA-Z0-9_.-]+(\\/[a-zA-Z0-9_.-]+)?$"},"poolTag":{"description":"Tag of the pool to fetch from. If not provided, resolved via branch/domain patterns","type":"string","pattern":"^[a-z0-9_-]+$"},"branch":{"description":"Git branch name for automatic pool resolution","type":"string"},"domains":{"description":"Domain names for automatic pool resolution (supports multiple domains)","type":"array","items":{"type":"string"}},"domain":{"description":"Specific domain for multi-domain assignments","type":"string"},"expirationHours":{"description":"Hours before expiration (1-720). If not provided, uses pool default","type":"integer","minimum":1,"exclusiveMinimum":false,"maximum":720,"exclusiveMaximum":false},"isImmortal":{"description":"If true, the environment will never expire","type":"boolean","default":false},"metadata":{"description":"Additional metadata for the assignment","type":"object","additionalProperties":{},"selfRequired":false},"override":{"description":"Force reassignment even if an environment is already assigned","type":"boolean","default":false}},"required":["assignmentType","assignmentId","repositoryIdentifier","metadata"]}}},"paths":{"/sfp/api/review/environments/assign":{"post":{"operationId":"ReviewEnvironmentsController_assignEnvironment","summary":"Assign a review environment from pool","description":"Fetches an available environment from the specified pool and assigns it to a PR, issue, user, or custom identifier. If an active assignment already exists, it will be reused.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignReviewEnvironmentDto"}}}},"responses":{"403":{"description":"Forbidden - Requires role: owner, application"},"default":{"description":"Review environment successfully assigned","content":{"application/json":{"schema":{}}}}},"tags":["Review Environments"]}}}}
```

## Get review environment details

> Retrieves the details of a specific review environment assignment

```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/review/environments/{assignmentType}/{assignmentId}":{"get":{"operationId":"ReviewEnvironmentsController_getEnvironment","summary":"Get review environment details","description":"Retrieves the details of a specific review environment assignment","parameters":[{"name":"assignmentType","required":true,"in":"path","description":"Type of assignment","schema":{"enum":["pr","issue","user","custom"],"type":"string"}},{"name":"assignmentId","required":true,"in":"path","description":"Assignment identifier","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":"Specific domain for multi-domain assignments","schema":{"type":"string"}}],"responses":{"403":{"description":"Forbidden - Requires role: owner, member, application"},"default":{"description":"Review environment details retrieved","content":{"application/json":{"schema":{}}}}},"tags":["Review Environments"]}}}}
```

## Extend review environment expiration

> Extends the expiration time of a review environment assignment. Can also be used to make an environment immortal or remove immortal 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"}},"schemas":{"ExtendReviewEnvironmentDto":{"type":"object","properties":{"assignmentType":{"type":"string","description":"Type of assignment for the review environment","enum":["pr","issue","user","custom"]},"assignmentId":{"type":"string","description":"Unique identifier for the assignment"},"repositoryIdentifier":{"type":"string","description":"Repository identifier in format owner/repo"},"extensionHours":{"type":"number","description":"Number of hours to extend the expiration by. If not provided, uses pool default.","minimum":1,"maximum":168},"isImmortal":{"type":"boolean","description":"If true, makes the environment immortal (never expires). If false, removes immortal status."},"domain":{"type":"string","description":"Specific domain to extend. If not provided, extends the default domain."}},"required":["assignmentType","assignmentId","repositoryIdentifier"]}}},"paths":{"/sfp/api/review/environments/extend":{"post":{"operationId":"ReviewEnvironmentsController_extendEnvironment","summary":"Extend review environment expiration","description":"Extends the expiration time of a review environment assignment. Can also be used to make an environment immortal or remove immortal status.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtendReviewEnvironmentDto"}}}},"responses":{"403":{"description":"Forbidden - Requires role: owner, member, application"},"default":{"description":"Expiration extended successfully","content":{"application/json":{"schema":{}}}}},"tags":["Review Environments"]}}}}
```

## Unassign review environment

> Releases a review environment assignment and optionally returns it to the pool

```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":{"UnassignReviewEnvironmentDto":{"type":"object","properties":{"assignmentType":{"type":"string","description":"Type of assignment for the review environment","enum":["pr","issue","user","custom"]},"assignmentId":{"type":"string","description":"Unique identifier for the assignment"},"repositoryIdentifier":{"type":"string","description":"Repository identifier in format owner/repo"},"returnToPool":{"type":"boolean","description":"If true, returns the environment to the pool as available. If false, marks it as expired.","default":true},"domain":{"type":"string","description":"Specific domain to unassign. If not provided, unassigns all domains."}},"required":["assignmentType","assignmentId","repositoryIdentifier"]}}},"paths":{"/sfp/api/review/environments/unassign":{"post":{"operationId":"ReviewEnvironmentsController_unassignEnvironment","summary":"Unassign review environment","description":"Releases a review environment assignment and optionally returns it to the pool","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnassignReviewEnvironmentDto"}}}},"responses":{"403":{"description":"Forbidden - Requires role: owner, member, application"},"default":{"description":"Environment unassigned successfully","content":{"application/json":{"schema":{}}}}},"tags":["Review Environments"]}}}}
```

## Transition environment between assignments

> Moves a review environment from one assignment to another (e.g., from PR to issue)

```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":{"TransitionReviewEnvironmentDto":{"type":"object","properties":{"repositoryIdentifier":{"type":"string","description":"Repository identifier in format owner/repo"},"fromAssignmentType":{"type":"string","description":"Current assignment type","enum":["pr","issue","user","custom"]},"fromAssignmentId":{"type":"string","description":"Current assignment identifier"},"toAssignmentType":{"type":"string","description":"New assignment type","enum":["pr","issue","user","custom"]},"toAssignmentId":{"type":"string","description":"New assignment identifier"},"metadata":{"type":"object","description":"Additional metadata for the new assignment"}},"required":["repositoryIdentifier","fromAssignmentType","fromAssignmentId","toAssignmentType","toAssignmentId"]}}},"paths":{"/sfp/api/review/environments/transition":{"post":{"operationId":"ReviewEnvironmentsController_transitionEnvironment","summary":"Transition environment between assignments","description":"Moves a review environment from one assignment to another (e.g., from PR to issue)","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransitionReviewEnvironmentDto"}}}},"responses":{"403":{"description":"Forbidden - Requires role: owner, member"},"default":{"description":"Environment transitioned successfully","content":{"application/json":{"schema":{}}}}},"tags":["Review Environments"]}}}}
```

## Acquire environment for use

> Marks an assigned environment as in-use for a specified duration. Uses optimistic locking to handle concurrent requests.

```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":{"AcquireReviewEnvironmentDto":{"type":"object","properties":{"assignmentType":{"type":"string","description":"Type of assignment","enum":["pr","issue","user","custom"]},"assignmentId":{"type":"string","description":"Unique identifier for the assignment"},"repositoryIdentifier":{"type":"string","description":"Repository identifier in format owner/repo"},"duration":{"type":"number","description":"Duration in minutes for which the environment is needed","minimum":1,"maximum":480},"usedBy":{"type":"string","description":"Identifier of the process or user acquiring the environment"},"domain":{"type":"string","description":"Specific domain to acquire (for multi-domain assignments)"}},"required":["assignmentType","assignmentId","repositoryIdentifier","duration","usedBy"]}}},"paths":{"/sfp/api/review/environments/acquire":{"post":{"operationId":"ReviewEnvironmentsController_acquireEnvironment","summary":"Acquire environment for use","description":"Marks an assigned environment as in-use for a specified duration. Uses optimistic locking to handle concurrent requests.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcquireReviewEnvironmentDto"}}}},"responses":{"200":{"description":"Environment successfully acquired","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"assignment":{"$ref":"#/components/schemas/ReviewEnvironmentAssignmentDto"}}}}}},"403":{"description":"Forbidden - Requires role: owner, member, application"},"404":{"description":"Review environment assignment not found"},"409":{"description":"Environment is currently in use or was acquired by another process","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"currentUser":{"type":"string"},"availableAt":{"type":"string","format":"date-time"},"availableInMinutes":{"type":"number"}}}}}}},"tags":["Review Environments"]}}}}
```

## Release environment from use

> Marks an environment as idle, making it available for other processes to acquire

```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":{"ReleaseReviewEnvironmentDto":{"type":"object","properties":{"assignmentType":{"description":"Type of assignment","type":"string","enum":["pr","issue","user","custom"]},"assignmentId":{"description":"Unique identifier for the assignment","type":"string","minLength":1},"repositoryIdentifier":{"description":"Repository identifier in format owner/repo or org/project/repo","type":"string","pattern":"^[a-zA-Z0-9_.-]+\\/[a-zA-Z0-9_.-]+(\\/[a-zA-Z0-9_.-]+)?$"},"domain":{"description":"Specific domain to release (for multi-domain assignments)","type":"string"}},"required":["assignmentType","assignmentId","repositoryIdentifier"]}}},"paths":{"/sfp/api/review/environments/release":{"post":{"operationId":"ReviewEnvironmentsController_releaseEnvironment","summary":"Release environment from use","description":"Marks an environment as idle, making it available for other processes to acquire","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReleaseReviewEnvironmentDto"}}}},"responses":{"200":{"description":"Environment successfully released","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"assignment":{"$ref":"#/components/schemas/ReviewEnvironmentAssignmentDto"}}}}}},"403":{"description":"Forbidden - Requires role: owner, member, application"},"404":{"description":"Review environment assignment not found"},"409":{"description":"Environment state was modified by another process"}},"tags":["Review Environments"]}}}}
```

## List review environment assignments

> Retrieves a list of review environment assignments with optional filters

```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/review/environments/list":{"get":{"operationId":"ReviewEnvironmentsController_listEnvironments","summary":"List review environment assignments","description":"Retrieves a list of review environment assignments with optional filters","parameters":[{"name":"repositoryIdentifier","required":false,"in":"query","description":"Filter by repository identifier","schema":{"type":"string"}},{"name":"assignmentType","required":false,"in":"query","description":"Filter by assignment type","schema":{"enum":["pr","issue","user","custom"],"type":"string"}},{"name":"assignmentId","required":false,"in":"query","description":"Filter by assignment ID","schema":{"type":"string"}},{"name":"poolTag","required":false,"in":"query","description":"Filter by pool tag","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","description":"Filter by assignment status","schema":{"enum":["active","expired","released","unassigned"],"type":"string"}},{"name":"assignedBy","required":false,"in":"query","description":"Filter by who assigned the environment","schema":{"type":"string"}},{"name":"includeExpired","required":false,"in":"query","description":"Include expired assignments in the results. By default, expired assignments are excluded unless explicitly requested","schema":{"default":false,"type":"boolean"}}],"responses":{"403":{"description":"Forbidden - Requires role: owner, member, application"},"default":{"description":"List of review environment assignments","content":{"application/json":{"schema":{}}}}},"tags":["Review Environments"]}}}}
```