Skip to main content

​
Overview

The LocalOps API lets you manage environments, services, deployments, custom domains and secrets programmatically - from the LocalOps SDK, a CLI wrapper or your CI pipeline. It also reads an environment’s network edges and workload identity, so you can point your own DNS, firewall allowlists and IAM policies at it. It is a small, deliberately separate surface from the LocalOps console. Every operation the API supports is listed under Endpoints in the sidebar.
An environment is also referred to as a Space in the console. The envId path parameter is the environment’s unique identifier.

​
Base URL

​
Authentication

Every endpoint except GET /health requires your account API token, sent as a bearer token:
The token is issued per account. Owners and admins can read it from the LocalOps console. A missing header, a non-Bearer header, a malformed token, or a token that matches no account are all rejected the same way:
Your account also needs an active plan. If your subscription is not active or past_due, requests are rejected with 403 and You don't have an active plan. Accounts without a subscription, such as BYOC accounts, pass this check.
The API token is the tenancy boundary for every request. Environment, service, deployment and custom domain identifiers are always looked up within your account, so an identifier belonging to another account behaves exactly like one that does not exist.

​
Attribution in audit logs

API requests are not tied to a user. Audit log entries for actions taken through the API show API Token as the actor, and deployments created this way have a zero UUID in created_by_id. Service creates, updates and deletes, secret updates, and custom domain creates, verifications and force deploys are all written to the audit log.

​
Response format

Successful responses are wrapped in an envelope:
There are two exceptions:
  • GET /health returns { "message": "ok" }
  • DELETE /v1/environments/{envId}/services/{serviceId} returns 202 { "message": "accepted" }

​
Errors

Errors are not wrapped in the data envelope:
The errors array is present only on validation failures, and can be null when the failure has no field level detail.
Check error_code rather than the HTTP status to decide whether a request was at fault. Some business rule violations, such as Ops Json is only supported for docker image and helm chart sources or Enable Preview is allowed only for service type web, are returned as 500 with error_code: validation.

​
Always send a body

Endpoints that accept a request body reject a zero byte body with 422:
Send at least {}. This matters most when deploying the latest commit on a git service’s configured branch, where there is nothing else to send.

​
Rate limits

There are no rate limits on the API today.

​
Asynchronous work

Deployments, service deletes, secret writes and custom domain deploys all hand off to the provisioner. The HTTP response confirms only that the request was accepted and passed synchronous validation. Observe the real outcome by polling:
  • deployment state, with GET /v1/deployments/{deploymentId}
  • service state, with GET /v1/environments/{envId}/services/{serviceId}
  • custom domain state, with GET /v1/environments/{envId}/services/{serviceId}/custom-domains
There are no idempotency keys. Retrying a deploy creates another deployment. Retrying a preview deploy for the same pull request reuses the existing preview service, indicated by is_new: false, but starts another rollout.

​
Coming soon

Some endpoints in the sidebar carry a COMING SOON badge. They are published so you can plan an integration against them, but they are not live yet - those paths return 404 today, and their shapes may change before release. Every asynchronous action will run as an operation with its own status, error and logs, so a failure tells you why instead of leaving you to guess. Alongside the two Operations endpoints, this adds an op_id to responses you already use, without changing any existing field: The op_ids and ops fields on GET /v1/deployments/{deploymentId}, empty today, will be filled in with the deployment’s operations at the same time. Creating and deleting environments, deleting a custom domain, and cancelling an in flight deployment are also on the way.

​
No list endpoints

The API has no “list services” or “list deployments” endpoint. Keep the identifiers returned when you create a service or trigger a deployment, or read them from the console.

​
Next steps

Common workflows

End to end recipes for creating and deploying a service, previewing pull requests, wiring services together and attaching custom domains.
The full endpoint reference, with request and response schemas and a live playground, is under Endpoints in the sidebar.