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

# Set the Route target

> Set the configured Route target or a complete production target set.



## OpenAPI

````yaml /openapi.json put /api/v1/routes/{route}/target
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/routes/{route}/target:
    put:
      tags:
        - Routes
      summary: Set the Route target
      description: Set the configured Route target or a complete production target set.
      operationId: route-target-set
      parameters:
        - name: route
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
          description: Numeric Route ID.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                instance_id:
                  type: integer
                  description: Required when `targets` is absent.
                targets:
                  type: array
                  description: Required when `instance_id` is absent.
                  items:
                    type: integer
                dispositions:
                  type: array
                  items:
                    type: object
                    properties:
                      instance_id:
                        type: integer
                      route_id:
                        type: integer
                      remove:
                        type: boolean
                    required:
                      - instance_id
              additionalProperties: false
      responses:
        '200':
          description: The request succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Route'
                  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/routes/9/target" \
              --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 '{"instance_id": 4, "targets": [1], "dispositions": [{"instance_id": 4}]}'
        - lang: php
          label: PHP SDK
          source: >
            <?php


            use Orbit\Sdk\GatewayConnector;

            use Orbit\Sdk\Requests\Routes\SetRouteTargetRequest;


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


            $response = $connector->send(new SetRouteTargetRequest(routeId:
            9))->dto();
components:
  schemas:
    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'
    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
    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.