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

# Update Project Settings

> Change a project's streaming and player settings from an allow-list. Anything else is refused by name.

Partial update of a project's streaming and player settings. Send only the fields you want to change. Validation is all-or-nothing: if any field is unknown, out of range or inconsistent with the stored values, nothing is written and the response names the field.

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

<Info>
  Plan, region, concurrent-user allowance, the project's on/off state and build moderation are **not** settable here and are refused with `400`. Use the dashboard for those, and [Enable](/resources/api-reference/enable-project) / [Disable](/resources/api-reference/disable-project) for on/off.
</Info>

## Path parameters

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

## Headers

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

## Request body

Any subset of the fields below.

### Stream

<ParamField body="resX" type="integer">
  Render width, 320 to 7680, even.
</ParamField>

<ParamField body="resY" type="integer">
  Render height, 240 to 4320, even.
</ParamField>

<ParamField body="primaryCodec" type="string">
  `AV1`, `H264`, `VP8` or `VP9`.
</ParamField>

<ParamField body="fallbaCodec" type="string">
  Codec used when the browser cannot decode the primary one. Same values. (The field name is spelled `fallbaCodec`.)
</ParamField>

<ParamField body="minBitrate" type="integer">
  kbps, 100 to 200000. Must not exceed `maxBitrate`.
</ParamField>

<ParamField body="startBitrate" type="integer">
  kbps, between `minBitrate` and `maxBitrate`.
</ParamField>

<ParamField body="maxBitrate" type="integer">
  kbps, 100 to 200000.
</ParamField>

<ParamField body="forceTurn" type="boolean">
  Relay all media through TURN. For audiences behind strict corporate firewalls.
</ParamField>

<ParamField body="cdn" type="boolean">
  Serve the player assets from the CDN.
</ParamField>

### Session rules

<ParamField body="maxRunTime" type="integer">
  Maximum session length in minutes, 1 to 1440. Sessions end with code `4004` when reached.
</ParamField>

<ParamField body="afktimeout" type="integer">
  Inactivity timeout in seconds, 0 to 86400. `0` disables it; idle viewers then hold a GPU slot indefinitely.
</ParamField>

<ParamField body="accessMode" type="string">
  `public` or `programmatic`. Password and SSO access modes need companion settings and are configured in the dashboard.
</ParamField>

<ParamField body="validPathUrl" type="string">
  Comma-separated list of domains allowed to embed the player, e.g. `"app.example.com, www.example.com"`. Schemes and paths are stripped. An empty list allows any domain.
</ParamField>

<ParamField body="autoRelease" type="boolean">
  Distribute processed builds automatically. When `false`, builds stop at `Ready` until [Set Active Build](/resources/api-reference/set-active-build).
</ParamField>

### Resolution and quality presets

<ParamField body="resolutionMode" type="string">
  `Dynamic Resolution Mode`, `Fixed Resolution Mode` or `Crop on Resize Mode`.
</ParamField>

<ParamField body="startResolution" type="string">
  Desktop start resolution: `360p (640x360)`, `480p (854x480)`, `720p (1280x720)`, `1080p (1920x1080)`, `1440p (2560x1440)` or `4K (3840x2160)`.
</ParamField>

<ParamField body="startResolutionTab" type="string">
  Tablet start resolution, same values.
</ParamField>

<ParamField body="startResolutionMobile" type="string">
  Mobile start resolution, same values.
</ParamField>

<ParamField body="maxStreamQuality" type="string">
  Upper bound viewers may pick, same values.
</ParamField>

### Player and input

<ParamField body="name" type="string">Project name, up to 120 characters.</ParamField>
<ParamField body="addLaunchArg" type="string">Extra Unreal launch arguments, up to 500 characters.</ParamField>
<ParamField body="delay" type="integer">Milliseconds, 0 to 60000.</ParamField>
<ParamField body="loadingTextOne" type="string">Loading screen line 1, up to 200 characters.</ParamField>
<ParamField body="loadingTextTwo" type="string">Loading screen line 2.</ParamField>
<ParamField body="loadingTextThree" type="string">Loading screen line 3.</ParamField>
<ParamField body="hoverMouse" type="boolean">Mouse hover without click.</ParamField>
<ParamField body="keyBoardInput" type="boolean">Forward keyboard input.</ParamField>
<ParamField body="mouseInput" type="boolean">Forward mouse input.</ParamField>
<ParamField body="touchInput" type="boolean">Forward touch input.</ParamField>
<ParamField body="gamepadInput" type="boolean">Forward gamepad input.</ParamField>
<ParamField body="xrInput" type="boolean">Forward XR input.</ParamField>
<ParamField body="fakeMouseTouch" type="boolean">Translate touch to mouse events.</ParamField>
<ParamField body="showBtn" type="boolean">Show the player's control bar.</ParamField>
<ParamField body="showBtnResolution" type="boolean">Show the resolution picker.</ParamField>
<ParamField body="showBtnVolume" type="boolean">Show the volume control.</ParamField>
<ParamField body="showBtnInfo" type="boolean">Show the info button.</ParamField>
<ParamField body="showNetwork" type="boolean">Show the network indicator.</ParamField>
<ParamField body="showMic" type="boolean">Show the microphone control.</ParamField>
<ParamField body="showCamera" type="boolean">Show the camera control.</ParamField>
<ParamField body="showUdpBlockedWarning" type="boolean">Warn viewers whose network blocks UDP.</ParamField>

### Webhooks

<ParamField body="webhookUrl" type="string">
  Public `https://` endpoint for [webhooks](/resources/api-reference/webhooks). Private and cluster-internal addresses are refused. Send `""` to remove.
</ParamField>

<ParamField body="webhookEvents" type="string[]">
  Events to deliver, e.g. `["build.approved", "build.rejected"]`. Up to 20.
</ParamField>

## Response

<ResponseField name="projectId" type="string">The project id.</ResponseField>
<ResponseField name="updated" type="string[]">The fields written.</ResponseField>
<ResponseField name="settings" type="object">Those fields with their stored values.</ResponseField>

<RequestExample>
  ```bash cURL theme={"dark"}
  curl -X PATCH https://platform.streampixel.io/api/v1/projects/664f1a2b3c4d5e6f7a8b9c0d/settings \
    -H "x-api-key: $STREAMPIXEL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"maxRunTime": 60, "primaryCodec": "H264", "resX": 1920, "resY": 1080}'
  ```

  ```javascript Node.js theme={"dark"}
  const res = await fetch(
    'https://platform.streampixel.io/api/v1/projects/664f1a2b3c4d5e6f7a8b9c0d/settings',
    {
      method: 'PATCH',
      headers: { 'x-api-key': process.env.STREAMPIXEL_API_KEY, 'Content-Type': 'application/json' },
      body: JSON.stringify({ maxRunTime: 60, primaryCodec: 'H264', resX: 1920, resY: 1080 }),
    }
  );
  const body = await res.json();
  if (!res.ok) console.error(body.code, body.message, body.unknown ?? body.invalid ?? body.inconsistent);
  ```

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

  r = requests.patch(
      "https://platform.streampixel.io/api/v1/projects/664f1a2b3c4d5e6f7a8b9c0d/settings",
      headers={"x-api-key": os.environ["STREAMPIXEL_API_KEY"]},
      json={"maxRunTime": 60, "primaryCodec": "H264", "resX": 1920, "resY": 1080},
  )
  print(r.status_code, r.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={"dark"}
  {
    "projectId": "664f1a2b3c4d5e6f7a8b9c0d",
    "updated": ["maxRunTime", "primaryCodec", "resX", "resY"],
    "settings": { "maxRunTime": 60, "primaryCodec": "H264", "resX": 1920, "resY": 1080 }
  }
  ```

  ```json 400 unknown field theme={"dark"}
  {
    "code": "VALIDATION_FAILED",
    "message": "Field(s) not settable here: allowedUsers, region",
    "unknown": ["allowedUsers", "region"]
  }
  ```

  ```json 400 invalid value theme={"dark"}
  {
    "code": "VALIDATION_FAILED",
    "message": "primaryCodec must be one of AV1, H264, VP8, VP9; maxRunTime must be an integer between 1 and 1440",
    "invalid": [
      { "field": "primaryCodec", "reason": "must be one of AV1, H264, VP8, VP9" },
      { "field": "maxRunTime", "reason": "must be an integer between 1 and 1440" }
    ]
  }
  ```

  ```json 400 inconsistent theme={"dark"}
  {
    "code": "VALIDATION_FAILED",
    "message": "minBitrate (2000) must not exceed maxBitrate (500)",
    "inconsistent": ["minBitrate (2000) must not exceed maxBitrate (500)"]
  }
  ```
</ResponseExample>

## Errors

| Status | `code`              | Cause                                                                                                                                          |
| ------ | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `VALIDATION_FAILED` | Unknown field (`unknown`), out-of-range value (`invalid`), or a cross-field conflict with stored values (`inconsistent`). Nothing was written. |
| `400`  | —                   | `Invalid webhook URL: …` when the URL points at a private address.                                                                             |
| `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 project with that id.                                                                                                                       |
| `429`  | `RATE_LIMITED`      | More than 30 control calls in a minute.                                                                                                        |

<Tip>
  Changes apply to sessions that start after the call. Running sessions keep the settings they launched with; call [End Sessions](/resources/api-reference/end-sessions) if everyone must pick up the new values now.
</Tip>