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

# Update Service

> Update a service's configuration. Send only the fields you want to change. The database update and the provisioner update run in one transaction.

This does not roll the change out - trigger a deployment afterwards.

When patching a service whose `type` is `job`, always include `"auto_deploy": false`. Omitting it on a job typed service surfaces as a `500`.



## OpenAPI

````yaml /openapi.json patch /v1/environments/{envId}/services/{serviceId}
openapi: 3.0.0
info:
  title: LocalOps API
  version: 1.0.0
  description: >-
    API for programmatically managing LocalOps environments and services.


    Every successful response (except `GET /health` and `DELETE
    /v1/environments/{envId}/services/{serviceId}`) is wrapped in an envelope:
    `{ "message": "success", "data": { ... } }`. Errors are returned unwrapped
    as `{ "error_code": "...", "message": "...", "errors": [...] }`.


    Deploys, deletes, secret writes and custom domain deploys are asynchronous.
    A 2xx confirms that the request was accepted and passed synchronous
    validation - observe the outcome by polling deployment state, service state
    or custom domain state.


    Endpoints badged **COMING SOON** are not live yet. Their request and
    response shapes are published so you can plan an integration, and may change
    before release - calls to those paths return `404` today.
servers:
  - url: https://sdk.localops.co
security:
  - bearerAuth: []
tags:
  - name: Health
    description: Liveness probe.
  - name: Environments
    description: Read an environment's identity, network edges and workload identity.
  - name: Services
    description: Create, read, update and delete services inside an environment.
  - name: Deployments
    description: Trigger deployments and poll their state.
  - name: Operations
    description: Track asynchronous work, with per operation status, error and logs.
  - name: Custom Domains
    description: Attach and verify custom domains for a service.
  - name: Secrets
    description: Read and replace environment level and service level secrets.
paths:
  /v1/environments/{envId}/services/{serviceId}:
    patch:
      tags:
        - Services
      summary: Update Service
      description: >-
        Update a service's configuration. Send only the fields you want to
        change. The database update and the provisioner update run in one
        transaction.


        This does not roll the change out - trigger a deployment afterwards.


        When patching a service whose `type` is `job`, always include
        `"auto_deploy": false`. Omitting it on a job typed service surfaces as a
        `500`.
      operationId: updateService
      parameters:
        - name: envId
          in: path
          required: true
          description: The unique identifier of the environment
          schema:
            type: string
            format: uuid
        - name: serviceId
          in: path
          required: true
          description: The unique identifier of the service
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 3
                  maxLength: 50
                  description: Letters, spaces and hyphens
                replica_count:
                  type: integer
                  minimum: 0
                cpu_count_min:
                  type: number
                cpu_count_max:
                  type: number
                memory_mb_min:
                  type: integer
                memory_mb_max:
                  type: integer
                port:
                  type: integer
                  minimum: 1
                  maximum: 65535
                cron_schedule:
                  type: string
                  minLength: 1
                  maxLength: 100
                auto_deploy:
                  type: boolean
                  description: Rejected for services whose `type` is `job`
                source:
                  type: string
                  enum:
                    - github
                    - gitlab
                    - docker_image
                    - helm_chart
                  description: >-
                    Changing the source makes the matching source fields
                    required in the same request
                git_repo_branch:
                  type: string
                  maxLength: 100
                  description: 'Required if `source: github` is sent'
                run_command:
                  type: string
                  maxLength: 100
                dockerfile_path:
                  type: string
                  maxLength: 100
                  description: Trimmed server side
                build_context:
                  type: string
                  maxLength: 100
                  description: >-
                    Docker build context directory, relative to the repository
                    root. Git sources only. Surrounding whitespace is trimmed
                    and a blank value is treated as unset.
                ops_json_path:
                  type: string
                  maxLength: 100
                  description: Trimmed server side
                ops_json:
                  type: string
                  description: Docker image source only
                enable_previews:
                  type: boolean
                enable_code_review:
                  type: boolean
                docker_registry:
                  type: string
                  maxLength: 100
                  description: 'Required if `source: docker_image` is sent'
                docker_image:
                  type: string
                  maxLength: 100
                  description: 'Required if `source: docker_image` is sent'
                helm_chart_repo:
                  type: string
                  maxLength: 100
                  description: 'Required if `source: helm_chart` is sent'
                helm_chart_name:
                  type: string
                  maxLength: 100
                  description: 'Required if `source: helm_chart` is sent'
                helm_values_yml:
                  type: string
                  description: Full replacement of `values.yaml`
                prov_node_group_id:
                  type: string
                  format: uuid
                is_protected:
                  type: boolean
                  description: Set to false before deleting a protected service
            examples:
              helm:
                summary: Bump Helm values and move node group
                value:
                  helm_values_yml: |
                    replicaCount: 3
                    image:
                      tag: 1.5.0
                  prov_node_group_id: 8e77b210-0000-0000-0000-000000000000
              unprotect:
                summary: Remove delete protection
                value:
                  is_protected: false
      responses:
        '200':
          description: Service updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      service:
                        $ref: '#/components/schemas/Service'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    Service:
      type: object
      description: >-
        A service inside an environment. Fields that are unset are omitted from
        the response.
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        type:
          type: string
          nullable: true
          enum:
            - web
            - internal
            - worker
            - cron
            - job
        state:
          type: string
          enum:
            - deploy_pending
            - deploy_queued
            - deploying
            - deploy_failed
            - running
            - delete_pending
            - delete_queued
            - deleting
            - deleted
            - delete_failed
          description: Lifecycle state, mirrored from the provisioner
        run_status:
          type: string
          description: >-
            Runtime status reported by the provisioner. Empty unless the
            response hydrates live state.
        ready_count:
          type: integer
          description: >-
            Number of ready replicas. Empty unless the response hydrates live
            state.
        replica_count:
          type: integer
          nullable: true
        cpu_count_min:
          type: number
        cpu_count_max:
          type: number
        memory_mb_min:
          type: integer
        memory_mb_max:
          type: integer
        source:
          type: string
          enum:
            - github
            - gitlab
            - docker_image
            - helm_chart
        port:
          type: integer
          nullable: true
        cron_schedule:
          type: string
          nullable: true
        auto_deploy:
          type: boolean
          description: Deploy on push. Git sources only.
        gitlab_connection_id:
          type: string
          format: uuid
        git_repo_full_name:
          type: string
        git_repo_branch:
          type: string
        dockerfile_path:
          type: string
        build_context:
          type: string
          description: >-
            Docker build context directory, relative to the repository root. Git
            sources only, omitted when unset.
        run_command:
          type: string
        ops_json_path:
          type: string
        ops_json:
          type: string
          description: Inline ops JSON. Docker image and Helm chart sources only.
        docker_registry:
          type: string
        docker_image:
          type: string
        helm_chart_repo:
          type: string
        helm_chart_name:
          type: string
        helm_values_yml:
          type: string
        prov_node_group_id:
          type: string
          format: uuid
          nullable: true
        account_id:
          type: string
          format: uuid
        private_instance_id:
          type: string
          format: uuid
          description: Id of the environment this service belongs to
        subdomain:
          type: string
          description: >-
            Generated by LocalOps as `<first 4 chars of name>-<8 char id>`. Not
            accepted on create.
        is_protected:
          type: boolean
          description: When true, the service cannot be deleted until protection is removed
        is_deleted:
          type: boolean
        latest_deployment:
          type: object
          nullable: true
          description: Metadata of the most recent deployment, when the edge is loaded
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        kube_svc_alias:
          type: string
          description: >-
            In cluster DNS alias. Only hydrated by `GET
            /v1/environments/{envId}/services/{serviceId}`.
        namespace_name:
          type: string
          description: >-
            Kubernetes namespace the service runs in. Only hydrated by `GET
            /v1/environments/{envId}/services/{serviceId}`, and omitted until
            the service is provisioned.
        ip_whitelist:
          type: array
          items:
            type: string
          description: >-
            CIDRs allowed to reach the service. Only hydrated by `GET
            /v1/environments/{envId}/services/{serviceId}`, and omitted when the
            service is unrestricted.
        ops_dependencies:
          type: array
          items:
            $ref: '#/components/schemas/OpsDependency'
          description: >-
            Cloud resources declared in the service's ops.json. Only hydrated by
            `GET /v1/environments/{envId}/services/{serviceId}`, where a service
            that declares none gets an empty array.
        kube_secret:
          type: string
        kube_dep_secret:
          type: string
        kube_preview_dep_secret:
          type: string
        custom_domain_id:
          type: string
          format: uuid
          description: Zero UUID when no custom domain is attached
        custom_domain:
          type: object
          nullable: true
        origin:
          type: string
          description: Public URL of the service, or the custom domain when one is attached
        parent_service_id:
          type: string
          format: uuid
          nullable: true
          description: Set on preview services
        enable_previews:
          type: boolean
        enable_code_review:
          type: boolean
        is_preview:
          type: boolean
        pr_number:
          type: integer
          nullable: true
        pr_comment_id:
          type: integer
          nullable: true
    OpsDependency:
      type: object
      description: >-
        A cloud resource declared in the service's
        [ops.json](/environment/services/ops-json), reported as it was declared.
      properties:
        id:
          type: string
          description: >-
            Resource identifier from ops.json. Free form, not a UUID - for
            example `orders-primary`.
        kind:
          type: string
          description: >-
            Resource kind, for example `s3`, `rds`, `elasticache` or `sqs`, or
            provider prefixed like `gcp:cloudsql`. New kinds are added over
            time, so treat this as an open set.
        exports:
          type: object
          additionalProperties:
            type: string
          description: >-
            Environment variable name to the resource attribute it resolves to,
            for example `{"DATABASE_URL": "$dsn"}`. The `$...` tokens are
            resolved when the variables are injected into your service; this
            response returns them verbatim.
      example:
        id: sessions
        kind: elasticache
        exports:
          REDIS_HOST: $address
          REDIS_PORT: $port
    Error:
      type: object
      properties:
        error_code:
          type: string
          enum:
            - unauthorized
            - forbidden
            - notfound
            - conflict
            - validation
            - unknown
          description: >-
            Machine readable error code. Treat this, and not the HTTP status, as
            the signal for whether the request was at fault - some business rule
            violations are returned as `500` with `error_code: validation`.
        message:
          type: string
          description: Human readable error message
        errors:
          type: array
          nullable: true
          description: >-
            Per field details. Present only on validation errors, and can be
            null when the failure has no field level detail.
          items:
            $ref: '#/components/schemas/FieldError'
    FieldError:
      type: object
      properties:
        field:
          type: string
          description: Name of the request field that failed validation
        error:
          type: string
          description: Reason the field was rejected
  responses:
    Unauthorized:
      description: Missing, malformed or unknown API token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error_code: unauthorized
            message: You are not authorized to do this action
    NotFound:
      description: >-
        The environment, service, deployment, custom domain or connection does
        not exist, or belongs to another account
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error_code: notfound
            message: Service not found
    ValidationError:
      description: >-
        Field validation failed, or the request body was missing or malformed.
        Endpoints that take a body always need at least `{}` - a zero byte body
        fails to bind.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            field:
              summary: Field validation
              value:
                error_code: validation
                message: Invalid data
                errors:
                  - field: replica_count
                    error: replica_count is a required field
            body:
              summary: Missing or malformed body
              value:
                error_code: validation
                message: Please check your request body
    ServerError:
      description: >-
        Unexpected failure. Some business rule violations are also returned here
        with `error_code: validation` - check `error_code` rather than the
        status to decide whether the request was at fault.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            unknown:
              summary: Unexpected failure
              value:
                error_code: unknown
                message: Something went wrong. Please try again later
            rule:
              summary: Business rule violation
              value:
                error_code: validation
                message: Ops Json is only supported for docker image source
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: UUID
      description: >-
        Your account API token, sent as `Authorization: Bearer <api_token>`.
        Owners and admins can read the token from the LocalOps console.

````