> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streampixel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Active Build

> Make a processed build the one viewers get: the API equivalent of Set Active in the dashboard.

Choose which build the project serves. The build is marked `Ready`, the project is switched on, and distribution to the region's streaming servers is queued. Viewers get the new build once it reaches `Approved`; poll [Build Status](/resources/api-reference/build-status) for that.

<Info>
  Scope: `control`. Team members need the Editor role or above. Limited to 30 control calls per minute per account.
</Info>

<Info>
  Only a build the pipeline has finished processing can be set active: status `Ready`, `Approved`, `Distribute` or `Distributing to Servers`. A build still downloading or scanning is refused with `409`; a failed or rejected build needs a new upload.
</Info>

## Path parameters

<ParamField path="projectId" type="string" required>
  The project.
</ParamField>

## Headers

<ParamField header="x-api-key" type="string" required>
  An API key issued with the `control` scope.
</ParamField>

## Request body

<ParamField body="buildId" type="string" required>
  The build to activate: `uploadId` from Upload File, or `id` from [List Builds](/resources/api-reference/list-builds).
</ParamField>

## Response

<ResponseField name="buildId" type="string">The build now being distributed.</ResponseField>
<ResponseField name="queued" type="boolean">`true`: distribution was queued.</ResponseField>
<ResponseField name="previousBuildStatus" type="string">The build's status before this call.</ResponseField>
<ResponseField name="enabled" type="boolean">Always `true`: setting a build active switches the project on.</ResponseField>
<ResponseField name="note" type="string">What to do next.</ResponseField>

<RequestExample>
  ```bash cURL theme={"dark"}
  curl -X POST https://platform.streampixel.io/api/v1/projects/664f1a2b3c4d5e6f7a8b9c0d/active-build \
    -H "x-api-key: $STREAMPIXEL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"buildId": "66a0b1c2d3e4f5a6b7c8d9e0"}'
  ```

  ```javascript Node.js theme={"dark"}
  const res = await fetch(
    'https://platform.streampixel.io/api/v1/projects/664f1a2b3c4d5e6f7a8b9c0d/active-build',
    {
      method: 'POST',
      headers: { 'x-api-key': process.env.STREAMPIXEL_API_KEY, 'Content-Type': 'application/json' },
      body: JSON.stringify({ buildId: '66a0b1c2d3e4f5a6b7c8d9e0' }),
    }
  );
  if (res.status === 409) console.log('not processed yet:', (await res.json()).message);
  ```

  ```python Python theme={"dark"}
  import os, requests

  r = requests.post(
      "https://platform.streampixel.io/api/v1/projects/664f1a2b3c4d5e6f7a8b9c0d/active-build",
      headers={"x-api-key": os.environ["STREAMPIXEL_API_KEY"]},
      json={"buildId": "66a0b1c2d3e4f5a6b7c8d9e0"},
  )
  print(r.status_code, r.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={"dark"}
  {
    "projectId": "664f1a2b3c4d5e6f7a8b9c0d",
    "name": "Showroom",
    "region": "Europe",
    "enabled": true,
    "buildId": "66a0b1c2d3e4f5a6b7c8d9e0",
    "queued": true,
    "previousBuildStatus": "Ready",
    "note": "Distribution to the region's streaming servers is queued; poll GET /projects/{id}/files/{fileId}/status until it is Approved."
  }
  ```

  ```json 409 Conflict theme={"dark"}
  {
    "code": "CONFLICT",
    "message": "Build is \"Extracting & Scanning\" and cannot be set active yet. It must have been processed (Ready or Approved); failed or rejected builds need a new upload.",
    "status": "Extracting & Scanning"
  }
  ```
</ResponseExample>

## Errors

| Status | `code`              | Cause                                                                          |
| ------ | ------------------- | ------------------------------------------------------------------------------ |
| `400`  | `VALIDATION_FAILED` | `buildId` missing or not a 24-character id.                                    |
| `403`  | `API_KEY_SCOPE`     | The key was issued without `control`.                                          |
| `403`  | —                   | The project belongs to another account, or the team role cannot edit projects. |
| `404`  | `NOT_FOUND`         | No such project, or no such build on it.                                       |
| `409`  | `CONFLICT`          | The build has not been processed yet, or failed.                               |
| `429`  | `RATE_LIMITED`      | More than 30 control calls in a minute.                                        |

## A full release from CI

<Steps>
  <Step title="Upload">
    [Upload File](/resources/api-reference/upload-file-api) with `autoRelease: false`; keep the `uploadId`.
  </Step>

  <Step title="Wait for processing">
    Poll [Build Status](/resources/api-reference/build-status) until `state` is `ready_for_activation`, or listen for the `build.saving` webhook.
  </Step>

  <Step title="Activate">
    Call this endpoint with the `uploadId`.
  </Step>

  <Step title="Wait for distribution">
    Poll Build Status until `state` is `live`. Optionally [End Sessions](/resources/api-reference/end-sessions) so current viewers reconnect onto the new build.
  </Step>
</Steps>