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

# Delete Service

> Delete a service. The request creates a delete operation, asks the provisioner to tear the service down and moves the service to `delete_pending`. The teardown itself continues asynchronously.

A `202` means the delete was accepted and started. A non 2xx means nothing was torn down.

Poll the service status to follow `delete_queued`, `deleting` and `deleted`, or `delete_failed` on failure.

For GitLab sourced services LocalOps also removes the project webhook and deploy tokens it created.



## OpenAPI

````yaml /openapi.json delete /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}:
    delete:
      tags:
        - Services
      summary: Delete Service
      description: >-
        Delete a service. The request creates a delete operation, asks the
        provisioner to tear the service down and moves the service to
        `delete_pending`. The teardown itself continues asynchronously.


        A `202` means the delete was accepted and started. A non 2xx means
        nothing was torn down.


        Poll the service status to follow `delete_queued`, `deleting` and
        `deleted`, or `delete_failed` on failure.


        For GitLab sourced services LocalOps also removes the project webhook
        and deploy tokens it created.
      operationId: deleteService
      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
      responses:
        '202':
          description: >-
            Delete accepted and started. This response is not wrapped in the
            data envelope.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: accepted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  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
    Conflict:
      description: The service is protected against deletion
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error_code: conflict
            message: Cannot delete a protected service. Remove protection first.
    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
  schemas:
    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
  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.

````