> ## 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. # Deploy Service > Trigger a deployment for a specific service within an environment. There are two modes. A **standard deploy** rolls out the service itself and returns a `deployment_id` you can poll. A **preview deploy** (`preview: true`) fans out to a per PR preview service and returns that service instead - preview mode does not return a deployment id. A request body is always required. To deploy the latest commit on a git service's configured branch, send `{}`. The deployment row is created synchronously so the id comes back immediately. The rollout runs in the background and any failure there marks the deployment `failed` rather than failing this request. Preview mode requires the parent service to use the `github` source, be of type `web`, have `enable_previews` turned on, and not itself be a preview service. The account plan must include preview environments. If both `docker_image_tag` and `helm_chart_version` are supplied, `helm_chart_version` wins. ## OpenAPI ````yaml /openapi.json post /v1/environments/{envId}/services/{serviceId}/deploy 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}/deploy: post: tags: - Deployments summary: Deploy Service description: >- Trigger a deployment for a specific service within an environment. There are two modes. A **standard deploy** rolls out the service itself and returns a `deployment_id` you can poll. A **preview deploy** (`preview: true`) fans out to a per PR preview service and returns that service instead - preview mode does not return a deployment id. A request body is always required. To deploy the latest commit on a git service's configured branch, send `{}`. The deployment row is created synchronously so the id comes back immediately. The rollout runs in the background and any failure there marks the deployment `failed` rather than failing this request. Preview mode requires the parent service to use the `github` source, be of type `web`, have `enable_previews` turned on, and not itself be a preview service. The account plan must include preview environments. If both `docker_image_tag` and `helm_chart_version` are supplied, `helm_chart_version` wins. operationId: deployService parameters: - name: envId in: path required: true description: The unique identifier of the environment schema: type: string - name: serviceId in: path required: true description: The unique identifier of the service schema: type: string requestBody: required: true content: application/json: schema: oneOf: - title: Deploy by Commit ID type: object required: - commit_id properties: commit_id: type: string description: >- The Git commit ID to deploy. Omit it, and send `{}`, to deploy the latest commit on the service's configured branch. note: type: string maxLength: 300 description: Optional note stored on the deployment - title: Deploy Docker Image type: object required: - docker_image_tag properties: docker_image_tag: type: string description: >- The Docker image tag to deploy. Required for `docker_image` services. note: type: string maxLength: 300 description: Optional note stored on the deployment - title: Deploy Helm Chart type: object required: - helm_chart_version properties: helm_chart_version: type: string description: >- The Helm chart version to deploy. Required for `helm_chart` services. note: type: string maxLength: 300 description: Optional note stored on the deployment - title: Preview Deployment type: object required: - preview - commit_id - branch - pr_number properties: preview: type: boolean enum: - true description: Set to true to trigger a preview deployment commit_id: type: string description: The Git commit ID to deploy for preview branch: type: string description: The branch of the pull request pr_number: type: integer minimum: 1 description: The pull request number. Must be greater than 0. note: type: string maxLength: 300 description: Optional note stored on the deployment example: commit_id: a1b2c3d4 responses: '200': description: Deployment triggered successfully content: application/json: schema: type: object properties: message: type: string data: oneOf: - title: Standard deployment type: object properties: deployment_id: type: string format: uuid description: Poll this id on the deployment endpoint required: - deployment_id - title: Preview deployment type: object properties: service_id: type: string format: uuid description: The preview service for this pull request service_name: type: string origin: type: string description: Public URL of the preview service pr_number: type: integer is_new: type: boolean description: >- False when an existing preview service for this pull request was reused required: - service_id - pr_number examples: standard: summary: Standard deployment value: message: success data: deployment_id: 3c7a4d81-0000-0000-0000-000000000000 preview: summary: Preview deployment value: message: success data: service_id: 7ab3c920-0000-0000-0000-000000000000 service_name: checkout api (PR#42) origin: https://pr-42-chec-a1b2c3d4.space.example.com pr_number: 42 is_new: true '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '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 Forbidden: description: >- The account has no active plan, the plan does not include the requested feature, or the service is being deleted content: application/json: schema: $ref: '#/components/schemas/Error' example: error_code: forbidden message: You don't have an active plan 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 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 `. Owners and admins can read the token from the LocalOps console. ````