> ## 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.
# Get Operation
> Read one operation's status and error.
Every asynchronous action - a deploy, a delete, a secret write, an environment create - will run as an operation, so a `failed` state comes with the reason instead of leaving you to guess.
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 get /v1/operations/{opId}
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/operations/{opId}:
get:
tags:
- Operations
summary: Get Operation
description: >-
Read one operation's status and error.
Every asynchronous action - a deploy, a delete, a secret write, an
environment create - will run as an operation, so a `failed` state comes
with the reason instead of leaving you to guess.
operationId: getOperation
parameters:
- name: opId
in: path
required: true
description: The unique identifier of the operation
schema:
type: string
format: uuid
responses:
'200':
description: Operation status
content:
application/json:
schema:
type: object
properties:
message:
type: string
data:
type: object
properties:
operation:
$ref: '#/components/schemas/Operation'
example:
message: success
data:
operation:
id: 9d2e4c71-0000-0000-0000-000000000000
type: service_deploy
state: in_progress
environment_id: 6a1f7e0c-0000-0000-0000-000000000000
service_id: b1f0a9c2-0000-0000-0000-000000000000
deployment_id: 3c7a4d81-0000-0000-0000-000000000000
custom_domain_id: null
created_at: '2026-08-10T09:20:11Z'
started_at: '2026-08-10T09:20:14Z'
ended_at: null
error: null
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/ValidationError'
'500':
$ref: '#/components/responses/ServerError'
components:
schemas:
Operation:
type: object
description: >-
An asynchronous unit of work. Not live yet - see the endpoints badged
COMING SOON.
properties:
id:
type: string
format: uuid
description: The `op_id`
type:
type: string
enum:
- environment_create
- environment_delete
- service_deploy
- service_delete
- custom_domain_deploy
- custom_domain_delete
- write_secrets
state:
type: string
enum:
- pending
- queued
- in_progress
- success
- failed
- canceled
- skipped
description: '`success`, `failed`, `canceled` and `skipped` are terminal.'
environment_id:
type: string
format: uuid
service_id:
type: string
format: uuid
nullable: true
description: Set when the operation acts on a service
deployment_id:
type: string
format: uuid
nullable: true
description: Set when the operation acts on a deployment
custom_domain_id:
type: string
format: uuid
nullable: true
description: Set when the operation acts on a custom domain
created_at:
type: string
format: date-time
started_at:
type: string
format: date-time
nullable: true
ended_at:
type: string
format: date-time
nullable: true
error:
type: string
nullable: true
description: Human readable failure reason when `state` is `failed`
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 `.
Owners and admins can read the token from the LocalOps console.
````