Restate deployment API

openapi: 3.2.0
info:
  title: Admin cluster_health Deployment API
  description: This API exposes the admin operations of a Restate cluster, such as registering new service deployments, interacting with running invocations, register Kafka subscriptions, retrieve service metadata. For an overview, check out the [Operate documentation](https://docs.restate.dev/operate/). If you're looking for how to call your services, check out the [Ingress HTTP API](https://docs.restate.dev/invoke/http) instead.
  version: 1.4.0
servers:
- url: http://localhost:9070
  description: Base URL declared by the provider in apis.yml (roadmap#122).
tags:
- name: deployment
  description: Service Deployment management
paths:
  /deployments:
    get:
      tags:
      - deployment
      summary: List Deployments
      description: List all registered deployments.
      operationId: list_deployments
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDeploymentsResponse'
    post:
      tags:
      - deployment
      summary: Create Deployment
      description: Create deployment. Restate will invoke the endpoint to gather additional information required for registration, such as the services exposed by the deployment. If the deployment is already registered, this method will fail unless `force` is set to `true`.
      externalDocs:
        url: https://docs.restate.dev/operate/registration
      operationId: create_deployment
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterDeploymentRequest'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterDeploymentResponse'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDescriptionResponse'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDescriptionResponse'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDescriptionResponse'
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDescriptionResponse'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDescriptionResponse'
        '503':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDescriptionResponse'
  /deployments/{deployment}:
    get:
      tags:
      - deployment
      summary: Get Deployment
      description: Get deployment metadata
      operationId: get_deployment
      parameters:
      - name: deployment
        in: path
        description: Deployment identifier
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailedDeploymentResponse'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDescriptionResponse'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDescriptionResponse'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDescriptionResponse'
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDescriptionResponse'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDescriptionResponse'
        '503':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDescriptionResponse'
    put:
      tags:
      - deployment
      summary: Update Deployment
      description: Update deployment. Invokes the endpoint and replaces the existing deployment metadata with the discovered information. This is a dangerous operation that should be used only when there are failing invocations on the deployment that cannot be resolved any other way. Sense checks are applied to test that the new deployment is sufficiently similar to the old one.
      externalDocs:
        url: https://docs.restate.dev/operate/versioning
      operationId: update_deployment
      parameters:
      - name: deployment
        in: path
        description: Deployment identifier
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDeploymentRequest'
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailedDeploymentResponse'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDescriptionResponse'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDescriptionResponse'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDescriptionResponse'
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDescriptionResponse'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDescriptionResponse'
        '503':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDescriptionResponse'
    delete:
      tags:
      - deployment
      summary: Delete Deployment
      description: Delete deployment. Currently it's supported to remove a deployment only using the force flag
      operationId: delete_deployment
      parameters:
      - name: deployment
        in: path
        description: Deployment identifier
        required: true
        schema:
          type: string
      - name: force
        in: query
        description: If true, the deployment will be forcefully deleted. This might break in-flight invocations, use with caution.
        style: simple
        schema:
          type: boolean
      responses:
        '202':
          description: Accepted
        '501':
          description: Not implemented. Only using the force flag is supported at the moment.
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDescriptionResponse'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDescriptionResponse'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDescriptionResponse'
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDescriptionResponse'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDescriptionResponse'
        '503':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDescriptionResponse'
components:
  schemas:
    UpdateDeploymentRequest:
      anyOf:
      - type: object
        required:
        - uri
        properties:
          uri:
            title: Uri
            description: Uri to use to discover/invoke the http deployment.
            type: string
          additional_headers:
            title: Additional headers
            description: Additional headers added to the discover/invoke requests to the deployment.
            type:
            - object
            - 'null'
            additionalProperties:
              type: string
          use_http_11:
            title: Use http1.1
            description: 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.
            default: false
            type: boolean
          dry_run:
            title: Dry-run mode
            description: 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.
            default: false
            type: boolean
      - type: object
        required:
        - arn
        properties:
          arn:
            title: ARN
            description: ARN to use to discover/invoke the lambda deployment.
            type: string
          assume_role_arn:
            title: Assume role ARN
            description: Optional ARN of a role to assume when invoking the addressed Lambda, to support role chaining
            type:
            - string
            - 'null'
          additional_headers:
            title: Additional headers
            description: Additional headers added to the discover/invoke requests to the deployment.
            type:
            - object
            - 'null'
            additionalProperties:
              type: string
          dry_run:
            title: Dry-run mode
            description: 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.
            default: false
            type: boolean
    String:
      type: string
    HandlerMetadataType:
      type: string
      enum:
      - Exclusive
      - Shared
      - Workflow
    RegisterDeploymentResponse:
      type: object
      required:
      - id
      - services
      properties:
        id:
          $ref: '#/components/schemas/String'
        services:
          type: array
          items:
            $ref: '#/components/schemas/ServiceMetadata'
        min_protocol_version:
          title: Minimum Service Protocol version
          description: During registration, the SDKs declare a range from minimum (included) to maximum (included) Service Protocol supported version.
          default: 0
          type: integer
          format: int32
        max_protocol_version:
          title: Maximum Service Protocol version
          description: During registration, the SDKs declare a range from minimum (included) to maximum (included) Service Protocol supported version.
          default: 0
          type: integer
          format: int32
        sdk_version:
          title: SDK version
          description: SDK library and version declared during registration.
          type:
          - string
          - 'null'
    DeploymentResponse:
      anyOf:
      - title: HttpDeploymentResponse
        description: Deployment response for HTTP deployments
        type: object
        required:
        - created_at
        - http_version
        - id
        - max_protocol_version
        - min_protocol_version
        - protocol_type
        - services
        - uri
        properties:
          id:
            title: Deployment ID
            allOf:
            - $ref: '#/components/schemas/String'
          uri:
            title: Deployment URI
            description: URI used to invoke this service deployment.
            type: string
          protocol_type:
            title: Protocol Type
            description: Protocol type used to invoke this service deployment.
            allOf:
            - $ref: '#/components/schemas/ProtocolType'
          http_version:
            title: HTTP Version
            description: HTTP Version used to invoke this service deployment.
            type: string
          additional_headers:
            title: Additional headers
            description: Additional headers used to invoke this service deployment.
            type: object
            additionalProperties:
              type: string
          created_at:
            type: string
          min_protocol_version:
            title: Minimum Service Protocol version
            description: During registration, the SDKs declare a range from minimum (included) to maximum (included) Service Protocol supported version.
            type: integer
            format: int32
          max_protocol_version:
            title: Maximum Service Protocol version
            description: During registration, the SDKs declare a range from minimum (included) to maximum (included) Service Protocol supported version.
            type: integer
            format: int32
          sdk_version:
            title: SDK version
            description: SDK library and version declared during registration.
            type:
            - string
            - 'null'
          services:
            title: Services
            description: List of services exposed by this deployment.
            type: array
            items:
              $ref: '#/components/schemas/ServiceNameRevPair'
      - title: LambdaDeploymentResponse
        description: Deployment response for Lambda deployments
        type: object
        required:
        - arn
        - created_at
        - id
        - max_protocol_version
        - min_protocol_version
        - services
        properties:
          id:
            title: Deployment ID
            allOf:
            - $ref: '#/components/schemas/String'
          arn:
            title: Lambda ARN
            description: Lambda ARN used to invoke this service deployment.
            allOf:
            - $ref: '#/components/schemas/LambdaARN'
          assume_role_arn:
            title: Assume role ARN
            description: Assume role ARN used to invoke this deployment. Check https://docs.restate.dev/category/aws-lambda for more details.
            type:
            - string
            - 'null'
          additional_headers:
            title: Additional headers
            description: Additional headers used to invoke this service deployment.
            type: object
            additionalProperties:
              type: string
          created_at:
            type: string
          min_protocol_version:
            title: Minimum Service Protocol version
            description: During registration, the SDKs declare a range from minimum (included) to maximum (included) Service Protocol supported version.
            type: integer
            format: int32
          max_protocol_version:
            title: Maximum Service Protocol version
            description: During registration, the SDKs declare a range from minimum (included) to maximum (included) Service Protocol supported version.
            type: integer
            format: int32
          sdk_version:
            title: SDK version
            description: SDK library and version declared during registration.
            type:
            - string
            - 'null'
          services:
            title: Services
            description: List of services exposed by this deployment.
            type: array
            items:
              $ref: '#/components/schemas/ServiceNameRevPair'
    ServiceType:
      type: string
      enum:
      - Service
      - VirtualObject
      - Workflow
    ListDeploymentsResponse:
      type: object
      required:
      - deployments
      properties:
        deployments:
          type: array
          items:
            $ref: '#/components/schemas/DeploymentResponse'
    RegisterDeploymentRequest:
      anyOf:
      - title: RegisterHttpDeploymentRequest
        description: Register HTTP deployment request
        type: object
        required:
        - uri
        properties:
          uri:
            title: Uri
            description: Uri to use to discover/invoke the http deployment.
            type: string
          additional_headers:
            title: Additional headers
            description: Additional headers added to the discover/invoke requests to the deployment.
            type:
            - object
            - 'null'
            additionalProperties:
              type: string
          use_http_11:
            title: Use http1.1
            description: 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.
            default: false
            type: boolean
          force:
            title: Force
            description: 'If `true`, it will override, if existing, any deployment using the same `uri`. Beware that this can lead in-flight invocations to an unrecoverable error state.


              By default, this is `true` but it might change in future to `false`.


              See the [versioning documentation](https://docs.restate.dev/operate/versioning) for more information.'
            default: true
            type: boolean
          dry_run:
            title: Dry-run mode
            description: 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.
            default: false
            type: boolean
      - title: RegisterLambdaDeploymentRequest
        description: Register Lambda deployment request
        type: object
        required:
        - arn
        properties:
          arn:
            title: ARN
            description: ARN to use to discover/invoke the lambda deployment.
            type: string
          assume_role_arn:
            title: Assume role ARN
            description: Optional ARN of a role to assume when invoking the addressed Lambda, to support role chaining
            type:
            - string
            - 'null'
          additional_headers:
            title: Additional headers
            description: Additional headers added to the discover/invoke requests to the deployment.
            type:
            - object
            - 'null'
            additionalProperties:
              type: string
          force:
            title: Force
            description: 'If `true`, it will override, if existing, any deployment using the same `uri`. Beware that this can lead in-flight invocations to an unrecoverable error state.


              By default, this is `true` but it might change in future to `false`.


              See the [versioning documentation](https://docs.restate.dev/operate/versioning) for more information.'
            default: true
            type: boolean
          dry_run:
            title: Dry-run mode
            description: 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.
            default: false
            type: boolean
    ServiceNameRevPair:
      type: object
      required:
      - name
      - revision
      properties:
        name:
          type: string
        revision:
          type: integer
          format: uint32
          minimum: 0.0
    DetailedDeploymentResponse:
      anyOf:
      - title: HttpDetailedDeploymentResponse
        description: Detailed deployment response for HTTP deployments
        type: object
        required:
        - created_at
        - http_version
        - id
        - max_protocol_version
        - min_protocol_version
        - protocol_type
        - services
        - uri
        properties:
          id:
            title: Deployment ID
            allOf:
            - $ref: '#/components/schemas/String'
          uri:
            title: Deployment URI
            description: URI used to invoke this service deployment.
            type: string
          protocol_type:
            title: Protocol Type
            description: Protocol type used to invoke this service deployment.
            allOf:
            - $ref: '#/components/schemas/ProtocolType'
          http_version:
            title: HTTP Version
            description: HTTP Version used to invoke this service deployment.
            type: string
          additional_headers:
            title: Additional headers
            description: Additional headers used to invoke this service deployment.
            type: object
            additionalProperties:
              type: string
          created_at:
            type: string
          min_protocol_version:
            title: Minimum Service Protocol version
            description: During registration, the SDKs declare a range from minimum (included) to maximum (included) Service Protocol supported version.
            type: integer
            format: int32
          max_protocol_version:
            title: Maximum Service Protocol version
            description: During registration, the SDKs declare a range from minimum (included) to maximum (included) Service Protocol supported version.
            type: integer
            format: int32
          sdk_version:
            title: SDK version
            description: SDK library and version declared during registration.
            type:
            - string
            - 'null'
          services:
            title: Services
            description: List of services exposed by this deployment.
            type: array
            items:
              $ref: '#/components/schemas/ServiceMetadata'
      - title: LambdaDetailedDeploymentResponse
        description: Detailed deployment response for Lambda deployments
        type: object
        required:
        - arn
        - created_at
        - id
        - max_protocol_version
        - min_protocol_version
        - services
        properties:
          id:
            title: Deployment ID
            allOf:
            - $ref: '#/components/schemas/String'
          arn:
            title: Lambda ARN
            description: Lambda ARN used to invoke this service deployment.
            allOf:
            - $ref: '#/components/schemas/LambdaARN'
          assume_role_arn:
            title: Assume role ARN
            description: Assume role ARN used to invoke this deployment. Check https://docs.restate.dev/category/aws-lambda for more details.
            type:
            - string
            - 'null'
          additional_headers:
            title: Additional headers
            description: Additional headers used to invoke this service deployment.
            type: object
            additionalProperties:
              type: string
          created_at:
            type: string
          min_protocol_version:
            title: Minimum Service Protocol version
            description: During registration, the SDKs declare a range from minimum (included) to maximum (included) Service Protocol supported version.
            type: integer
            format: int32
          max_protocol_version:
            title: Maximum Service Protocol version
            description: During registration, the SDKs declare a range from minimum (included) to maximum (included) Service Protocol supported version.
            type: integer
            format: int32
          sdk_version:
            title: SDK version
            description: SDK library and version declared during registration.
            type:
            - string
            - 'null'
          services:
            title: Services
            description: List of services exposed by this deployment.
            type: array
            items:
              $ref: '#/components/schemas/ServiceMetadata'
    ErrorDescriptionResponse:
      title: Error description response
      description: Error details of the response
      type: object
      required:
      - message
      properties:
        message:
          type: string
        restate_code:
          title: Restate code
          description: Restate error code describing this error
          type:
          - string
          - 'null'
    ServiceMetadata:
      type: object
      required:
      - deployment_id
      - handlers
      - name
      - public
      - revision
      - ty
      properties:
        name:
          title: Name
          description: Fully qualified name of the service
          type: string
        handlers:
          type: array
          items:
            $ref: '#/components/schemas/HandlerMetadata'
        ty:
          $ref: '#/components/schemas/ServiceType'
        documentation:
          title: Documentation
          description: Documentation of the service, as propagated by the SDKs.
          type:
          - string
          - 'null'
        metadata:
          title: Metadata
          description: Additional service metadata, as propagated by the SDKs.
          type: object
          additionalProperties:
            type: string
        deployment_id:
          title: Deployment Id
          description: Deployment exposing the latest revision of the service.
          type: string
        revision:
          title: Revision
          description: Latest revision of the service.
          type: integer
          format: uint32
          minimum: 0.0
        public:
          title: Public
          description: If true, the service can be invoked through the ingress. If false, the service can be invoked only from another Restate service.
          type: boolean
        idempotency_retention:
          title: Idempotency retention
          description: The retention duration of idempotent requests for this service.
          type:
          - string
          - 'null'
        workflow_completion_retention:
          title: Workflow completion retention
          description: The retention duration of workflows. Only available on workflow services.
          type:
          - string
          - 'null'
        journal_retention:
          title: Journal retention
          description: 'The journal retention. When set, this applies to all requests to all handlers of this service.


            In case the request has an idempotency key, the `idempotency_retention` caps the maximum `journal_retention` time. In case the request targets a workflow handler, the `workflow_completion_retention` caps the maximum `journal_retention` time.'
          type:
          - string
          - 'null'
        inactivity_timeout:
          title: Inactivity timeout
          description: '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.


            This overrides the default inactivity timeout set in invoker options.'
          type:
          - string
          - 'null'
        abort_timeout:
          title: Abort timeout
          description: '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.


            This overrides the default abort timeout set in invoker options.'
          type:
          - string
          - 'null'
        enable_lazy_state:
          title: Enable lazy state
          description: If true, lazy state will be enabled for all invocations to this service. This is relevant only for Workflows and Virtual Objects.
          type:
          - boolean
          - 'null'
    HandlerMetadata:
      type: object
      required:
      - input_description
      - name
      - output_description
      properties:
        name:
          type: string
        ty:
          allOf:
          - $ref: '#/components/schemas/HandlerMetadataType'
        documentation:
          title: Documentation
          description: Documentation of the handler, as propagated by the SDKs.
          type:
          - string
          - 'null'
        metadata:
          title: Metadata
          description: Additional handler metadata, as propagated by the SDKs.
          type: object
          additionalProperties:
            type: string
        idempotency_retention:
          title: Idempotency retention
          description: The retention duration of idempotent requests for this service.
          type:
          - string
          - 'null'
        workflow_completion_retention:
          title: Workflow completion retention
          description: The retention duration of workflows. Only available on workflow services.
          type:
          - string
          - 'null'
        journal_retention:
          title: Journal retention
          description: 'The journal retention. When set, this applies to all requests to this handler.


            In case the request 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.'
          type:
          - string
          - 'null'
        inactivity_timeout:
          title: Inactivity timeout
          description: '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 [`humantime`](https://docs.rs/humantime/latest/humantime/fn.parse_duration.html) format.


            This overrides the default inactivity timeout set in invoker options.'
          type:
          - string
          - 'null'
        abort_timeout:
          title: Abort timeout
          description: '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 [`humantime`](https://docs.rs/humantime/latest/humantime/fn.parse_duration.html) format.


            This overrides the default abort timeout set in invoker options.'
          type:
          - string
          - 'null'
        enable_lazy_state:
          title: Enable lazy state
          description: If 

# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/restate/refs/heads/main/openapi/restate-deployment-api-openapi.yml