---
title: "Register deployment"
method: POST
path: "/deployments"
tags: ["deployment"]
---

# Register deployment

`POST /deployments`

Registers a new deployment (HTTP or Lambda). Restate will invoke the endpoint to discover available services and handlers,
and make them available for invocation. For more information, see the [deployment documentation](https://docs.restate.dev/services/versioning#registering-a-deployment).

## Request body

- union
  - object — Register HTTP deployment request
    - `additional_headers` SerdeableHeaderHashMap — Proxy type to implement HashMap<HeaderName, HeaderValue> ser/de Use it directly or with `#[serde(with = "serde_with::As::<serde_with::FromInto<restate_serde_util::SerdeableHeaderMap>>")]`.
    - `auth` HttpAuth — HTTP authentication details.
      - `GoogleIdToken` GoogleIdTokenAuth, required
        - `audience` string, nullable — Explicit OIDC `aud` claim. Leave unset to automatically derive from the deployment URL.
        - `impersonate_service_account` string, nullable — Service account email to impersonate via `iamcredentials:generateIdToken`. Leave unset to use the ambient ADC identity.
    - `breaking` boolean — # Breaking If `true`, it allows registering new service revisions with schemas incompatible with previous service revisions, such as changing the service type. See the [versioning documentation](https://docs.restate.dev/operate/versioning) for more information.
    - `dry_run` boolean — # Dry-run mode If `true`, discovery will run but the deployment will not be registered. This is useful to see the impact of a new deployment before registering it. `force` and `breaking` will be respected.
    - `force` boolean, nullable — # Force If `true`, it overrides, if existing, any deployment using the same `uri`. Beware that this can lead inflight invocations to an unrecoverable error state. When set to `true`, it implies `breaking = true`. See the [versioning documentation](https://docs.restate.dev/operate/versioning) for more information.
    - `metadata` object — # Metadata Deployment metadata.
    - `uri` string, uri, required — # Uri Uri to use to discover/invoke the http deployment.
    - `use_http_11` boolean — # Use http1.1 If `true`, discovery will be attempted using a client that defaults to HTTP1.1 instead of a prior-knowledge HTTP2 client. HTTP2 may still be used for TLS servers that advertise HTTP2 support via ALPN. HTTP1.1 deployments will only work in request-response mode.
  - object — Register Lambda deployment request
    - `additional_headers` SerdeableHeaderHashMap — Proxy type to implement HashMap<HeaderName, HeaderValue> ser/de Use it directly or with `#[serde(with = "serde_with::As::<serde_with::FromInto<restate_serde_util::SerdeableHeaderMap>>")]`.
    - `arn` string, required — # ARN ARN to use to discover/invoke the lambda deployment.
    - `assume_role_arn` string, nullable — # Assume role ARN Optional ARN of a role to assume when invoking the addressed Lambda, to support role chaining
    - `breaking` boolean — # Breaking If `true`, it allows registering new service revisions with schemas incompatible with previous service revisions, such as changing the service type. See the [versioning documentation](https://docs.restate.dev/operate/versioning) for more information.
    - `dry_run` boolean — # Dry-run mode If `true`, discovery will run but the deployment will not be registered. This is useful to see the impact of a new deployment before registering it. `force` and `breaking` will be respected.
    - `force` boolean, nullable — # Force If `true`, it overrides, if existing, any deployment using the same `uri`. Beware that this can lead inflight invocations to an unrecoverable error state. This implies `breaking = true`. See the [versioning documentation](https://docs.restate.dev/operate/versioning) for more information.
    - `metadata` object — # Metadata Deployment metadata.

## Response `200`

Deployment already exists. No change if force = false, services overwritten if force = true

- RegisterDeploymentResponse
  - `id` string, required
  - `info` SchemaInfo[] — # Info List of configuration/deprecation information related to this deployment.
    - `code` string, nullable
    - `message` string, required
  - `max_protocol_version` integer — # Maximum Service Protocol version During registration, the SDKs declare a range from minimum (included) to maximum (included) Service Protocol supported version.
  - `min_protocol_version` integer — # Minimum Service Protocol version During registration, the SDKs declare a range from minimum (included) to maximum (included) Service Protocol supported version.
  - `sdk_version` string, nullable — # SDK version SDK library and version declared during registration.
  - `services` ServiceMetadata[], required
    - `abort_timeout` string — # Abort timeout This timer guards against stalled service/handler invocations that are supposed to terminate. The abort timeout is started after the 'inactivity timeout' has expired and the service/handler invocation has been asked to gracefully terminate. Once the timer expires, it will abort the service/handler invocation. This timer potentially **interrupts** user code. If the user code needs longer to gracefully terminate, then this value needs to be set accordingly. Can be configured using the [`jiff::fmt::friendly`](https://docs.rs/jiff/latest/jiff/fmt/friendly/index.html) format or ISO8601, for example `5 hours`. If unset, this returns the default abort timeout configured in invoker options.
    - `deployment_id` string, required
    - `documentation` string, nullable — # Documentation Documentation of the service, as propagated by the SDKs.
    - `enable_lazy_state` boolean — # Enable lazy state If true, lazy state will be enabled for all invocations to this service. This is relevant only for Workflows and Virtual Objects.
    - `handlers` HandlerMetadata[], required — # Handlers Handlers for this service.
      - `abort_timeout` string, nullable — # Abort timeout This timer guards against stalled service/handler invocations that are supposed to terminate. The abort timeout is started after the 'inactivity timeout' has expired and the service/handler invocation has been asked to gracefully terminate. Once the timer expires, it will abort the service/handler invocation. This timer potentially **interrupts** user code. If the user code needs longer to gracefully terminate, then this value needs to be set accordingly. Can be configured using the [`jiff::fmt::friendly`](https://docs.rs/jiff/latest/jiff/fmt/friendly/index.html) format or ISO8601, for example `5 hours`. If set, it overrides the value set in the service.
      - `documentation` string, nullable — # Documentation Documentation of the handler, as propagated by the SDKs.
      - `enable_lazy_state` boolean, nullable — # Enable lazy state If true, lazy state will be enabled for all invocations to this service. This is relevant only for Workflows and Virtual Objects. If set, it overrides the value set in the service.
      - `idempotency_retention` string, nullable — # Idempotency retention The retention duration of idempotent requests for this handler. If set, it overrides the value set in the service. Can be configured using the [`jiff::fmt::friendly`](https://docs.rs/jiff/latest/jiff/fmt/friendly/index.html) format or ISO8601, for example `5 hours`.
      - `inactivity_timeout` string, nullable — # Inactivity timeout This timer guards against stalled service/handler invocations. Once it expires, Restate triggers a graceful termination by asking the service invocation to suspend (which preserves intermediate progress). The 'abort timeout' is used to abort the invocation, in case it doesn't react to the request to suspend. Can be configured using the [`jiff::fmt::friendly`](https://docs.rs/jiff/latest/jiff/fmt/friendly/index.html) format or ISO8601, for example `5 hours`. If set, it overrides the value set in the service.
      - `info` SchemaInfo[] — # Info List of configuration/deprecation information related to this handler.
        - `code` string, nullable
        - `message` string, required
      - `input_description` string, required — # Human readable input description If empty, no schema was provided by the user at discovery time.
      - `input_json_schema` unknown
      - `journal_retention` string, nullable — # Journal retention The journal retention. When set, this applies to all requests to this handler. In case the invocation has an idempotency key, the `idempotency_retention` caps the maximum `journal_retention` time. In case this handler is a workflow handler, the `workflow_completion_retention` caps the maximum `journal_retention` time. Can be configured using the [`jiff::fmt::friendly`](https://docs.rs/jiff/latest/jiff/fmt/friendly/index.html) format or ISO8601, for example `5 hours`. If set, it overrides the value set in the service.
      - `metadata` object — # Metadata Additional handler metadata, as propagated by the SDKs.
      - `name` string, required — # Name The handler name.
      - `output_description` string, required — # Human readable output description If empty, no schema was provided by the user at discovery time.
      - `output_json_schema` unknown
      - `public` boolean — # Public If true, this handler can be invoked through the ingress. If false, this handler can be invoked only from another Restate service.
      - `retry_policy` HandlerRetryPolicyMetadata — # Handler retry policy overrides
        - `exponentiation_factor` number, float, nullable — # Factor The factor to use to compute the next retry attempt.
        - `initial_interval` string, nullable — # Initial Interval Initial interval for the first retry attempt. Can be configured using the [`jiff::fmt::friendly`](https://docs.rs/jiff/latest/jiff/fmt/friendly/index.html) format or ISO8601, for example `5 hours`.
        - `max_attempts` integer, nullable — # Max attempts Number of maximum attempts (including the initial) before giving up. Infinite retries if unset. No retries if set to 1.
        - `max_interval` string, nullable — # Max interval Maximum interval between retries. Can be configured using the [`jiff::fmt::friendly`](https://docs.rs/jiff/latest/jiff/fmt/friendly/index.html) format or ISO8601, for example `5 hours`.
        - `on_max_attempts` 'Pause' | 'Kill'
      - `ty` 'Exclusive' | 'Shared' | 'Workflow'
    - `idempotency_retention` string — # Idempotency retention The retention duration of idempotent requests for this service. If not configured, this returns the default idempotency retention. Can be configured using the [`jiff::fmt::friendly`](https://docs.rs/jiff/latest/jiff/fmt/friendly/index.html) format or ISO8601, for example `5 hours`.
    - `inactivity_timeout` string — # Inactivity timeout This timer guards against stalled service/handler invocations. Once it expires, Restate triggers a graceful termination by asking the service invocation to suspend (which preserves intermediate progress). The 'abort timeout' is used to abort the invocation, in case it doesn't react to the request to suspend. Can be configured using the [`jiff::fmt::friendly`](https://docs.rs/jiff/latest/jiff/fmt/friendly/index.html) format or ISO8601, for example `5 hours`. If unset, this returns the default inactivity timeout configured in invoker options.
    - `info` SchemaInfo[] — # Info List of configuration/deprecation information related to this service.
      - `code` string, nullable
      - `message` string, required
    - `journal_retention` string, nullable — # Journal retention The journal retention. When set, this applies to all requests to all handlers of this service. In case the invocation has an idempotency key, the `idempotency_retention` caps the maximum `journal_retention` time. In case the invocation targets a workflow handler, the `workflow_completion_retention` caps the maximum `journal_retention` time. Can be configured using the [`jiff::fmt::friendly`](https://docs.rs/jiff/latest/jiff/fmt/friendly/index.html) format or ISO8601, for example `5 hours`.
    - `metadata` object — # Metadata Additional service metadata, as propagated by the SDKs.
    - `name` string, required — # Name Fully qualified name of the service
    - `public` boolean — # Public If true, the service can be invoked through the ingress. If false, the service can be invoked only from another Restate service.
    - `retry_policy` ServiceRetryPolicyMetadata — # Service retry policy
      - `exponentiation_factor` number, float — # Factor The factor to use to compute the next retry attempt. Default: `2.0`.
      - `initial_interval` string — # Initial Interval Initial interval for the first retry attempt. Can be configured using the [`jiff::fmt::friendly`](https://docs.rs/jiff/latest/jiff/fmt/friendly/index.html) format or ISO8601, for example `5 hours`.
      - `max_attempts` integer, nullable — # Max attempts Number of maximum attempts (including the initial) before giving up. Infinite retries if unset. No retries if set to 1.
      - `max_interval` string, nullable — # Max interval Maximum interval between retries. Can be configured using the [`jiff::fmt::friendly`](https://docs.rs/jiff/latest/jiff/fmt/friendly/index.html) format or ISO8601, for example `5 hours`.
      - `on_max_attempts` 'Pause' | 'Kill'
    - `revision` integer, required
    - `ty` 'Service' | 'VirtualObject' | 'Workflow', required
    - `workflow_completion_retention` string, nullable — # Workflow completion retention The retention duration of workflows. Only available on workflow services. Can be configured using the [`jiff::fmt::friendly`](https://docs.rs/jiff/latest/jiff/fmt/friendly/index.html) format or ISO8601, for example `5 hours`.

## Other responses

- `201` — Deployment created successfully and services discovered
- `400` — Bad request
- `404` — Not found
- `405` — Method not allowed
- `409` — Conflict
- `500` — Internal server error

## Changes

> 8 revisions in range; 1 could not be searched.

- **2026-06-19** `7381abc4d9a3` — 1 info
  - added the new optional request property `oneOf[subschema #1: RegisterHttpDeploymentRequest]/auth`
- **2026-01-30** `059a44500a5c` — 7 breaking, 3 warning, 35 info
  - removed `subschema #1: RegisterHttpDeploymentRequest, subschema #2: RegisterLambdaDeploymentRequest` from the request body `anyOf` list
  - added `#/components/schemas/HandlerMetadataType, subschema #1` to the `services/items/handlers/items/ty` response property `oneOf` list for the response status `201`
  - the `services/items/deployment_id` response's property type/format changed from ``/`` to `string`/`` for status `201`
  - the `services/items/handlers/items/retry_policy` response's property type/format changed from ``/`` to `object`/`` for status `201`
  - …41 more

[Change history](https://skmtc.dev/restatedev/apis/admin-api/changes/deployments/post.md)

---

[API](https://skmtc.dev/restatedev/apis/admin-api.md) · [All operations](https://skmtc.dev/restatedev/apis/admin-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/restatedev/admin-api/revisions/5361f4818c71/schema)