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

# Project settings

> Read and patch a project's active settings

Every project has active settings — trim, background, subtitle style, layout — that control how exports are rendered. Use project settings when you want project-local overrides that aren't worth sharing as a preset.

See [Render settings reference](/en/render-settings-reference) for the shared
`preset`, `settings.style`, and `settingsOverride` field map.

## Endpoints

| Method  | Path                             | Purpose                                  |
| ------- | -------------------------------- | ---------------------------------------- |
| `GET`   | `/projects/{projectId}/settings` | Fetch the active project settings.       |
| `PATCH` | `/projects/{projectId}/settings` | Apply a preset, patch settings, or both. |

Full request and response schemas are in **API reference**.

## Fetch the current settings

```bash theme={null}
curl https://api.youka.io/api/v1/projects/prj_abc/settings \
  -H "Authorization: Bearer yk_..."
```

Returns the full active project settings, including any preset that is applied.

## Patch the settings

`PATCH` accepts any subset of `presetId` and `settings`. When both are passed, the preset is applied first and then `settings` is merged on top.

<Tabs>
  <Tab title="Apply a preset">
    ```bash theme={null}
    curl -X PATCH https://api.youka.io/api/v1/projects/prj_abc/settings \
      -H "Authorization: Bearer yk_..." \
      -H "Content-Type: application/json" \
      -d '{
        "presetId": "preset_abc123"
      }'
    ```
  </Tab>

  <Tab title="Inline settings">
    ```bash theme={null}
    curl -X PATCH https://api.youka.io/api/v1/projects/prj_abc/settings \
      -H "Authorization: Bearer yk_..." \
      -H "Content-Type: application/json" \
      -d '{
        "settings": {
          "trim": { "startSeconds": 5, "endSeconds": 180 },
          "style": {
            "background": {
              "type": "color",
              "color": "#101010"
            }
          }
        }
      }'
    ```
  </Tab>

  <Tab title="Preset + overrides">
    ```bash theme={null}
    curl -X PATCH https://api.youka.io/api/v1/projects/prj_abc/settings \
      -H "Authorization: Bearer yk_..." \
      -H "Content-Type: application/json" \
      -d '{
        "presetId": "preset_abc123",
        "settings": {
          "trim": { "startSeconds": 5, "endSeconds": 180 }
        }
      }'
    ```
  </Tab>
</Tabs>

## Discover valid fields

The SDK exports the schema that validates project settings updates. Convert it to JSON Schema at runtime:

```ts theme={null}
import { RestUpdateProjectSettingsRequestSchema } from "@youka/sdk";

const schema = RestUpdateProjectSettingsRequestSchema.toJSONSchema();
```

<Tip>
  Agents should fetch the SDK schema or the OpenAPI request schema before
  mutating project settings so they always know the current shape.
</Tip>

Human-readable reference:

* [Render settings reference](/en/render-settings-reference)
* [CLI projects](/en/cli/projects)
* [SDK project settings](/en/sdk/project-settings)

## Project settings vs presets vs export overrides

Youka has three layers where render settings can live:

| Layer                         | Scope           | When to use                                         |
| ----------------------------- | --------------- | --------------------------------------------------- |
| **Preset**                    | Account-wide    | The same look across many projects.                 |
| **Project settings**          | One project     | Project-specific trim, background, or color.        |
| **Export `settingsOverride`** | One export only | Tweak a single render without touching the project. |

Each layer is merged in that order at export time.

## What's next

* [Render settings reference](/en/render-settings-reference) — all shared field paths and enum values
* [Presets](/en/api/presets) — reusable configurations
* [Media](/en/api/media) — referenced from settings
* [CLI projects](/en/cli/projects) — the same flow from the terminal
* [SDK project settings](/en/sdk/project-settings) — the same endpoints in TypeScript