> ## Documentation Index > Fetch the complete documentation index at: https://orbit.nckrtl.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Replace profile settings sections > Replaces the sections of the settings document that the body holds (`workspaces`, `appearance`, `devices`; at least one) and keeps the others. `devices` replaces every device type and must hold at least one; a patch removes one type. Send the document version you last read; a stale version returns `conn.settings_version_conflict` (409) with `details.current_version`. Prefer `conn:profile:settings:patch`, which versions each section. An empty object is refused, a document over 4 MB returns `validation.failed` (422), and the document keys keep Conn camelCase. ## OpenAPI ````yaml /openapi.json put /api/v1/conn/profiles/{profile}/settings openapi: 3.1.0 info: title: Orbit Gateway API version: v1 description: >- The HTTP API of the active Orbit Gateway. The CLI and the PHP SDK send every fleet command through these endpoints over WireGuard. See [Using the API](/api/overview) for transport, authentication, envelopes, and errors. servers: - url: https://gateway.orbit description: >- The active Gateway on the private WireGuard network, resolved by Orbit private DNS. security: [] tags: - name: Gateway description: >- Status and trust of the active Gateway, and the releases of the Gateway itself. - name: Nodes description: Machines in the fleet, their roles, access grants, and storage settings. - name: Clusters description: Groups of Nodes with one Router and one development TLD. - name: Firewall description: Named UFW rules on one Node. - name: Fleet rollout description: >- The rollout of each verified Gateway release to the managed Nodes, and its catch-up. - name: Tools description: Packages that Orbit installs on a Node through a Tool Manager. - name: Metrics description: The Prometheus and Grafana role and its exporters. - name: GitHub App description: The Gateway's own read-only GitHub App and the accounts that installed it. - name: Analytics description: >- The analytics role, its Plausible version, and the Stats API key the Gateway uses to read visits. - name: Projects description: Repository records with one type, default branch, and web root each. - name: Instances description: Development checkouts and production releases of a Project on one Node. - name: Environment description: Stored Instance environment configuration and its .env projection. - name: Routes description: Domains that reach an Instance. - name: Database connections description: The registry of mysql, pgsql, and sqlite connections. - name: Processes description: >- systemd services and Docker containers owned by an Instance, a Node, or a Project definition. - name: Schedules description: Recurring commands run by native systemd timers. - name: Annotations description: Instance annotations, T3 delivery, and replayable status events. - name: Tasks description: Commander feature groups and ordered subtasks. - name: Extensions description: Gateway-owned extension switches. - name: Doctor description: Verify-only drift checks across the fleet. - name: Activities description: The Gateway log of authorized commands. - name: proxycli description: CLIProxyAPI quota snapshots, provider pools, and account controls. - name: Vaultwarden description: The copy of database credentials into a Vaultwarden collection. - name: Conn description: >- Profiles, shared workspace settings, registered T3 servers, and the pairing links the Gateway mints on them for each Node. - name: Realtime description: >- The record-change event feed broadcast to Reverb, its channel authorization, and Reverb connection discovery. - name: Node callbacks description: Endpoints that managed Nodes and Caddy call; operators do not call them. paths: /api/v1/conn/profiles/{profile}/settings: put: tags: - Conn summary: Replace profile settings sections description: >- Replaces the sections of the settings document that the body holds (`workspaces`, `appearance`, `devices`; at least one) and keeps the others. `devices` replaces every device type and must hold at least one; a patch removes one type. Send the document version you last read; a stale version returns `conn.settings_version_conflict` (409) with `details.current_version`. Prefer `conn:profile:settings:patch`, which versions each section. An empty object is refused, a document over 4 MB returns `validation.failed` (422), and the document keys keep Conn camelCase. operationId: conn-profile-settings-update parameters: - name: profile in: path required: true schema: type: string description: '' requestBody: required: true content: application/json: schema: type: object required: - version - settings properties: version: type: integer minimum: 1 description: The document version the client last read. settings: type: object additionalProperties: false minProperties: 1 description: >- The sections to replace; the others stay. The whole document is at most 4 MB. properties: workspaces: type: array maxItems: 200 items: type: object additionalProperties: false required: - id - name - color - icon properties: id: type: string maxLength: 100 name: type: string maxLength: 100 color: type: string maxLength: 32 icon: type: - string - 'null' maxLength: 64 image: type: - string - 'null' maxLength: 200000 pattern: >- ^data:image\/(png|jpeg|webp);base64,[A-Za-z0-9+\/]+=*$(?![\s\S]) projectRefs: type: array maxItems: 500 items: type: string maxLength: 512 pattern: ^[^:\s]+:\S+$(?![\s\S]) projectKeys: type: array maxItems: 500 items: type: string maxLength: 512 appearance: type: object additionalProperties: false required: - schema - mode - contrast description: Serialized at most 512 KB. properties: schema: type: integer minimum: 1 maximum: 1000 mode: type: string enum: - light - dark - system contrast: type: integer minimum: 50 maximum: 200 themes: type: object additionalProperties: false minProperties: 1 properties: light: type: object additionalProperties: false required: - id - source properties: id: type: string maxLength: 100 source: type: string enum: - stock - builtin - custom - published name: type: string maxLength: 100 appearance: type: string enum: - light - dark colors: type: object minProperties: 1 maxProperties: 80 propertyNames: pattern: ^[a-zA-Z][a-zA-Z0-9]{0,63}$ additionalProperties: type: string maxLength: 64 pattern: ^[#A-Za-z0-9(),.%/ -]+$ dark: type: object additionalProperties: false required: - id - source properties: id: type: string maxLength: 100 source: type: string enum: - stock - builtin - custom - published name: type: string maxLength: 100 appearance: type: string enum: - light - dark colors: type: object minProperties: 1 maxProperties: 80 propertyNames: pattern: ^[a-zA-Z][a-zA-Z0-9]{0,63}$ additionalProperties: type: string maxLength: 64 pattern: ^[#A-Za-z0-9(),.%/ -]+$ customThemes: type: array maxItems: 50 items: type: object additionalProperties: false required: - id - name - appearance - colors properties: id: type: string maxLength: 100 description: Unique in the list. name: type: string maxLength: 100 appearance: type: string enum: - light - dark colors: type: object minProperties: 1 maxProperties: 80 propertyNames: pattern: ^[a-zA-Z][a-zA-Z0-9]{0,63}$ additionalProperties: type: string maxLength: 64 pattern: ^[#A-Za-z0-9(),.%/ -]+$ variants: type: object additionalProperties: false minProperties: 1 properties: light: type: object minProperties: 1 maxProperties: 80 propertyNames: pattern: ^[a-zA-Z][a-zA-Z0-9]{0,63}$ additionalProperties: type: string maxLength: 64 pattern: ^[#A-Za-z0-9(),.%/ -]+$ dark: type: object minProperties: 1 maxProperties: 80 propertyNames: pattern: ^[a-zA-Z][a-zA-Z0-9]{0,63}$ additionalProperties: type: string maxLength: 64 pattern: ^[#A-Za-z0-9(),.%/ -]+$ devices: type: object minProperties: 1 maxProperties: 8 propertyNames: pattern: ^[a-z][a-z0-9-]{1,23}$ additionalProperties: type: object additionalProperties: false required: - schema - values description: >- Serialized at most 64 KB. The Gateway checks the envelope and the value types; each client checks its own keys. properties: schema: type: integer minimum: 1 maximum: 1000 values: type: object minProperties: 1 maxProperties: 128 propertyNames: pattern: ^[a-zA-Z][a-zA-Z0-9]{0,63}$ additionalProperties: oneOf: - type: - string - number - boolean - 'null' maxLength: 512 - type: array maxItems: 32 items: type: - string - number - boolean maxLength: 512 description: >- Replaces every device type. At least one; a patch removes one type. additionalProperties: false responses: '200': description: The request succeeded. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/ConnProfileSettings' meta: $ref: '#/components/schemas/Meta' required: - data - meta '403': description: >- The caller is not an active WireGuard peer (`peer.identity_unknown`) or lacks Node access to the target (`node_access.required`). content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: No record matches the path parameters. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- A guard refused the change and the Gateway changed nothing; `error.code` names the guard. content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- The JSON body is not an object, has duplicate or unknown members, or fails validation (`validation.failed`). content: application/json: schema: $ref: '#/components/schemas/Error' x-codeSamples: - lang: bash label: curl source: > curl -sS -X PUT "https://gateway.orbit/api/v1/conn/profiles/1/settings" \ --cacert /path/to/orbit-root-ca.pem \ -H 'Accept: application/json' \ -H 'X-Orbit-Request-Id: 9d6b1e5c-4a3f-4a1b-9f0e-6d2c3f5a7b81' \ -H 'Content-Type: application/json' \ -d '{"version": 1, "settings": {"apps": {"path": "/srv/orbit/apps"}}}' components: schemas: ConnProfileSettings: type: object properties: profile_id: type: integer version: type: integer settings: type: object additionalProperties: true sections: type: object additionalProperties: true updated_at: type: string Meta: type: object properties: request_id: type: string format: uuid description: >- The request ID the Gateway assigned or accepted; the same value is in the `X-Orbit-Request-Id` response header and in the Activity record. required: - request_id Error: type: object properties: error: type: object properties: code: type: string description: >- Stable error code, namespaced by family, such as `node.not_active` or `route.target_conflict`. message: type: string description: >- Safe message without credentials, environment values, or remote output. details: type: object additionalProperties: true description: >- Bounded, redacted details such as the conflicting record IDs or the failed validation rule. request_id: type: string format: uuid required: - code - message required: - error ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.