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

# Update the deployment branch

> Update a production Instance deployment branch.



## OpenAPI

````yaml /openapi.json patch /api/v1/instances/{instance}
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/instances/{instance}:
    patch:
      tags:
        - Instances
      summary: Update the deployment branch
      description: Update a production Instance deployment branch.
      operationId: instance-update
      parameters:
        - name: instance
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
          description: Numeric Instance ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                branch:
                  type: string
                  description: Deployment branch
              required:
                - branch
              additionalProperties: false
      responses:
        '200':
          description: The request succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Instance'
                  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 PATCH "https://gateway.orbit/api/v1/instances/12" \
              --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 '{"branch": "main"}'
        - lang: php
          label: PHP SDK
          source: >
            <?php


            use Orbit\Sdk\GatewayConnector;

            use Orbit\Sdk\Requests\Instances\UpdateInstanceRequest;


            $connector = new GatewayConnector(
                baseUrl: 'https://gateway.orbit',
                caPemPath: '/path/to/orbit-root-ca.pem',
            );


            $response = $connector->send(new UpdateInstanceRequest(instanceId:
            4, branch: 'main'))->dto();
components:
  schemas:
    Instance:
      type: object
      properties:
        id:
          type: integer
        project_id:
          type: integer
        node_id:
          type: integer
        project:
          $ref: '#/components/schemas/ProjectIdentity'
        node:
          $ref: '#/components/schemas/NodeIdentity'
        name:
          type: string
        source_layout:
          type: string
        checkout_path:
          type: string
        production_user:
          type:
            - string
            - 'null'
        production_home:
          type:
            - string
            - 'null'
        root:
          type:
            - string
            - 'null'
        effective_root:
          type:
            - string
            - 'null'
        selected_branch:
          type:
            - string
            - 'null'
        branch_override:
          type:
            - string
            - 'null'
        starting_commit:
          type:
            - string
            - 'null'
        detached:
          type: boolean
        status:
          type: string
        route:
          oneOf:
            - $ref: '#/components/schemas/Route'
            - type: 'null'
        domain:
          type:
            - string
            - 'null'
        url:
          type:
            - string
            - 'null'
        removal:
          oneOf:
            - $ref: '#/components/schemas/InstanceRemoval'
            - type: 'null'
        transfer:
          oneOf:
            - $ref: '#/components/schemas/InstanceTransfer'
            - type: 'null'
        deploy_steps:
          type: array
          items:
            $ref: '#/components/schemas/DeploymentStep'
        vite_port:
          type:
            - integer
            - 'null'
        ssr_port:
          type:
            - integer
            - 'null'
        seed_path:
          type:
            - string
            - 'null'
        seed_commit:
          type:
            - string
            - 'null'
        annotator_port:
          type:
            - integer
            - 'null'
        annotator_url:
          type:
            - string
            - 'null'
        routes:
          type: array
          items:
            $ref: '#/components/schemas/Route'
    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
    ProjectIdentity:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        slug:
          type: string
        type:
          type: string
          enum:
            - monorepo
            - laravel-app
            - symfony-app
            - laravel-package
            - node-package
    NodeIdentity:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
    Route:
      type: object
      properties:
        id:
          type: integer
        kind:
          type: string
        project_id:
          type:
            - integer
            - 'null'
        node_id:
          type:
            - integer
            - 'null'
        cluster_id:
          type:
            - integer
            - 'null'
        generation_basis_node_id:
          type:
            - integer
            - 'null'
        domain:
          type: string
        provenance:
          type: string
        publication:
          type: string
        status:
          type: string
        failed_step:
          type:
            - string
            - 'null'
        error_code:
          type:
            - string
            - 'null'
        replaces_route_id:
          type:
            - integer
            - 'null'
        replaced_by_route_id:
          type:
            - integer
            - 'null'
        replacement_step:
          type:
            - string
            - 'null'
        target_set_step:
          type:
            - string
            - 'null'
        target:
          oneOf:
            - $ref: '#/components/schemas/RouteTarget'
            - type: 'null'
        targets:
          type: array
          items:
            $ref: '#/components/schemas/RouteTarget'
        process_id:
          type:
            - integer
            - 'null'
        upstream:
          type:
            - string
            - 'null'
        analytics_instance_id:
          type:
            - integer
            - 'null'
        web_root:
          type:
            - string
            - 'null'
    InstanceRemoval:
      type: object
      properties:
        operation_id:
          type: string
        id:
          type: integer
        name:
          type: string
        force:
          type: boolean
        status:
          type: string
        current_step:
          type:
            - string
            - 'null'
        total:
          type: integer
        completed:
          type: integer
        remaining:
          type: integer
        failed_step:
          type:
            - string
            - 'null'
        error_code:
          type:
            - string
            - 'null'
    InstanceTransfer:
      type: object
      properties:
        operation_id:
          type: string
        id:
          type: integer
        source_node_id:
          type: integer
        destination_node_id:
          type: integer
        destination_name:
          type: string
        destination_path:
          type: string
        destination_domain:
          type: string
        sqlite_selected:
          type: boolean
        status:
          type: string
        current_step:
          type: string
        cutover_completed:
          type: boolean
        cleanup_completed:
          type: boolean
        failed_step:
          type:
            - string
            - 'null'
        error_code:
          type:
            - string
            - 'null'
        recovery_evidence:
          type:
            - object
            - 'null'
          additionalProperties: true
    DeploymentStep:
      type: object
      properties:
        name:
          type: string
        phase:
          type: string
        command:
          type: string
        timeout_seconds:
          type: integer
    RouteTarget:
      type: object
      properties:
        id:
          type: integer
        instance_id:
          type: integer
        position:
          type: integer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.