openapi: 3.0.0
info:
  title: Admin cluster_health service 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: service
  description: Service management
paths:
  /services:
    get:
      tags:
      - service
      summary: List Services
      description: List all registered services.
      operationId: list_services
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListServicesResponse'
        '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'
  /services/{service}:
    get:
      tags:
      - service
      summary: Get Service
      description: Get a registered service.
      operationId: get_service
      parameters:
      - name: service
        in: path
        description: Fully qualified service name.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceMetadata'
        '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'
    patch:
      tags:
      - service
      summary: Modify A Service
      description: Modify a registered service.
      operationId: modify_service
      parameters:
      - name: service
        in: path
        description: Fully qualified service name.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModifyServiceRequest'
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceMetadata'
        '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'
  /services/{service}/openapi:
    get:
      tags:
      - service
      summary: Get Service OpenAPI
      description: Get the service OpenAPI 3.1 contract.
      operationId: get_service_openapi
      parameters:
      - name: service
        in: path
        description: Fully qualified service name.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OpenAPI 3.1 of the service
          content:
            application/json:
              schema: {}
        '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'
  /services/{service}/state:
    post:
      tags:
      - service
      summary: Modify A Service State
      description: Modify service state
      operationId: modify_service_state
      parameters:
      - name: service
        in: path
        description: Fully qualified service name.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModifyServiceStateRequest'
        required: true
      responses:
        '202':
          description: Accepted
        '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:
    ServiceType:
      type: string
      enum:
      - Service
      - VirtualObject
      - Workflow
    HandlerMetadataType:
      type: string
      enum:
      - Exclusive
      - Shared
      - Workflow
    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
    ModifyServiceRequest:
      type: object
      properties:
        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.
          default: null
          type: boolean
          nullable: true
        idempotency_retention:
          title: Idempotency retention
          description: 'Modify the retention of idempotent requests for this service.


            Can be configured using the [`jiff::fmt::friendly`](https://docs.rs/jiff/latest/jiff/fmt/friendly/index.html) format or ISO8601.'
          default: null
          type: string
          nullable: true
        workflow_completion_retention:
          title: Workflow completion retention
          description: 'Modify the retention of the workflow completion. This can be modified only for workflow services!


            Can be configured using the [`jiff::fmt::friendly`](https://docs.rs/jiff/latest/jiff/fmt/friendly/index.html) format or ISO8601.'
          default: null
          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.'
          default: null
          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.'
          default: null
          type: string
          nullable: true
    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
    ModifyServiceStateRequest:
      type: object
      required:
      - new_state
      - object_key
      properties:
        version:
          title: Version
          description: If set, the latest version of the state is compared with this value and the operation will fail when the versions differ.
          type: string
          nullable: true
        object_key:
          title: Service key
          description: To what virtual object key to apply this change
          type: string
        new_state:
          title: New State
          description: The new state to replace the previous state with
          type: object
          additionalProperties:
            type: array
            items:
              type: integer
              format: uint8
              minimum: 0.0
    ListServicesResponse:
      type: object
      required:
      - services
      properties:
        services:
          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
          nullable: true
externalDocs:
  url: https://docs.restate.dev/operate/