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 decla
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/restate/refs/heads/main/openapi/restate-deployment-api-openapi.yml