# 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.9.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.9.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.9.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.9.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":"Whether to return the environment to the pool as available (true) or mark it expired (false). Explicit values always win. If omitted, the server falls back to each instance's pool config `returnToPoolOnUnassign` (default false). Multi-domain unassigns resolve per-instance, so each domain can take a different decision based on its own pool. Scratch-org pools always delete the org regardless of this flag."},"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.9.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.9.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.9.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.9.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"]}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.flxbl.io/flxbl/sfp-server/api-reference/review-environments.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.