openapi: 3.0.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
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
            additionalProperties:
              type: string
            nullable: true
          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
            nullable: true
          additional_headers:
            title: Additional headers
            description: Additional headers added to the discover/invoke requests to the deployment.
            type: object
            additionalProperties:
              type: string
            nullable: true
          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
    ServiceType:
      type: string
      enum:
      - Service
      - VirtualObject
      - Workflow
    HandlerMetadataType:
      type: string
      enum:
      - Exclusive
      - Shared
      - Workflow
    LambdaARN:
      type: string
      format: arn
    HandlerMetadata:
      type: object
      required:
      - input_description
      - name
      - output_description
      properties:
        name:
          type: string
        ty:
          allOf:
          - $ref: '#/components/schemas/HandlerMetadataType'
          nullable: true
        documentation:
          title: Documentation
          description: Documentation of the handler, as propagated by the SDKs.
          type: string
          nullable: true
        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
          nullable: true
        workflow_completion_retention:
          title: Workflow completion retention
          description: The retention duration of workflows. Only available on workflow services.
          type: string
          nullable: true
        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
          nullable: true
        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
          nullable: true
        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
          nullable: true
        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
          nullable: true
        public:
          title: Public
          description: If true, this handler can be invoked through the ingress. If false, this handler can be invoked only from another Restate service.
          default: true
          type: boolean
        input_description:
          title: Human readable input description
          description: If empty, no schema was provided by the user at discovery time.
          type: string
        output_description:
          title: Human readable output description
          description: If empty, no schema was provided by the user at discovery time.
          type: string
        input_json_schema:
          title: Input JSON Schema
          description: JSON Schema of the handler input
          nullable: true
        output_json_schema:
          title: Output JSON Schema
          description: JSON Schema of the handler output
          nullable: true
    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
            additionalProperties:
              type: string
            nullable: true
          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
            nullable: true
          additional_headers:
            title: Additional headers
            description: Additional headers added to the discover/invoke requests to the deployment.
            type: object
            additionalProperties:
              type: string
            nullable: true
          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
    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
          nullable: true
        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
          nullable: true
        workflow_completion_retention:
          title: Workflow completion retention
          description: The retention duration of workflows. Only available on workflow services.
          type: string
          nullable: true
        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
          nullable: true
        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
          nullable: true
        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
          nullable: true
        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
          nullable: true
    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
            nullable: true
          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
            nullable: true
          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
            nullable: true
          services:
            title: Services
            description: List of services exposed by this deployment.
            type: array
            items:
              $ref: '#/components/schemas/ServiceMetadata'
    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
            nullable: true
          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
            nullable: true
          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
            nullable: true
          services:
            title: Services
            description: List of services exposed by this deployment.
            type: array
            items:
              $ref: '#/components/schemas/ServiceNameRevPair'
    ProtocolType:
      type: string
      enum:
      - RequestResponse
      - BidiStream
    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
          nullable: true
    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
          nullable: true
    String:
      type: string
    ListDeploymentsResponse:
      type: object
      required:
      - deployments
      properties:
        deployments:
          type: array
          items:
            $ref: '#/components/schemas/DeploymentResponse'
    ServiceNameRevPair:
      type: object
      required:
      - name
      - revision
      properties:
        name:
          type: string
        revision:
          type: integer
          format: uint32
          minimum: 0.0
externalDocs:
  url: https://docs.restate.dev/operate/