> ## 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.
# Cancel Deployment
> Stop a deployment that has not finished.
Only `queued` and `in_progress` deployments can be canceled. A canceled deployment ends in state `failed`, and its operation ends in state `canceled`.
This endpoint is not live yet. The shapes below show how it is expected to work so you can plan your
integration, and may change before release. Calls to this path return `404` today.
## OpenAPI
````yaml /openapi.json post /v1/deployments/{deploymentId}/cancel
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/deployments/{deploymentId}/cancel:
post:
tags:
- Deployments
summary: Cancel Deployment
description: >-
Stop a deployment that has not finished.
Only `queued` and `in_progress` deployments can be canceled. A canceled
deployment ends in state `failed`, and its operation ends in state
`canceled`.
operationId: cancelDeployment
parameters:
- name: deploymentId
in: path
required: true
description: The unique identifier of the deployment
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
type: object
properties: {}
example: {}
responses:
'200':
description: Deployment after the cancel
content:
application/json:
schema:
type: object
properties:
message:
type: string
data:
type: object
properties:
deployment:
$ref: '#/components/schemas/Deployment'
example:
message: success
data:
deployment:
id: 3c7a4d81-0000-0000-0000-000000000000
type: service_update
state: failed
service_id: b1f0a9c2-0000-0000-0000-000000000000
op_ids:
- 9d2e4c71-0000-0000-0000-000000000000
ops:
9d2e4c71-0000-0000-0000-000000000000:
id: 9d2e4c71-0000-0000-0000-000000000000
type: service_deploy
state: canceled
'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:
schemas:
Deployment:
type: object
properties:
id:
type: string
format: uuid
type:
type: string
enum:
- update
- restore
- service_update
state:
type: string
enum:
- queued
- in_progress
- success
- failed
description: >-
`success` and `failed` are terminal. Keep polling on `queued` and
`in_progress`.
service_id:
type: string
format: uuid
private_instance_id:
type: string
format: uuid
cloud_connection_id:
type: string
format: uuid
prev_deployment_id:
type: string
format: uuid
prov_deployment_id:
type: string
account_id:
type: string
format: uuid
op_ids:
type: array
description: >-
Empty today. Will carry the identifiers of the deployment's
operations once the Operations endpoints ship.
items:
type: string
ops:
type: object
description: >-
Empty today. Will carry each operation's status and error, keyed by
`op_id`, once the Operations endpoints ship.
git_commit_ref:
type: string
git_commit_author:
type: string
git_commit_message:
type: string
docker_image_tag:
type: string
helm_chart_version:
type: string
helm_values_yml:
type: string
note:
type: string
created_by_id:
type: string
format: uuid
description: Zero UUID for API triggered deployments
created_at:
type: string
format: date-time
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
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
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: UUID
description: >-
Your account API token, sent as `Authorization: Bearer `.
Owners and admins can read the token from the LocalOps console.
````