# Cluster state endpoint Source: https://docs.restate.dev/admin-api/cluster_health/cluster-state-endpoint schemas/openapi-admin.json get /cluster-health # Delete deployment Source: https://docs.restate.dev/admin-api/deployment/delete-deployment schemas/openapi-admin.json delete /deployments/{deployment} Delete a deployment. Currently, only forced deletions are supported. **Use with caution**: forcing a deployment deletion can break in-flight invocations. # Get deployment Source: https://docs.restate.dev/admin-api/deployment/get-deployment schemas/openapi-admin.json get /deployments/{deployment} Returns detailed information about a registered deployment, including deployment metadata and the services it exposes. # List deployments Source: https://docs.restate.dev/admin-api/deployment/list-deployments schemas/openapi-admin.json get /deployments Returns a list of all registered deployments, including their endpoints and associated services. # Register deployment Source: https://docs.restate.dev/admin-api/deployment/register-deployment schemas/openapi-admin.json post /deployments Registers a new deployment (HTTP or Lambda). Restate will invoke the endpoint to discover available services and handlers, and make them available for invocation. For more information, see the [deployment documentation](https://docs.restate.dev/services/versioning#registering-a-deployment). # Update deployment Source: https://docs.restate.dev/admin-api/deployment/update-deployment schemas/openapi-admin.json patch /deployments/{deployment} Updates an existing deployment configuration, such as the endpoint address or invocation headers. By default, service schemas are not re-discovered. Set `overwrite: true` to trigger re-discovery. # Health check endpoint Source: https://docs.restate.dev/admin-api/health/health-check-endpoint schemas/openapi-admin.json get /health # Query the system and service state by using SQL. Source: https://docs.restate.dev/admin-api/introspection/query-the-system-and-service-state-by-using-sql schemas/openapi-admin.json post /query # Cancel an invocation Source: https://docs.restate.dev/admin-api/invocation/cancel-an-invocation schemas/openapi-admin.json patch /invocations/{invocation_id}/cancel Gracefully cancels an invocation. The invocation is terminated, but its progress is persisted, allowing consistency guarantees to be maintained. For more information, see the [cancellation documentation](https://docs.restate.dev/services/invocation/managing-invocations#cancel). # Delete an invocation Source: https://docs.restate.dev/admin-api/invocation/delete-an-invocation schemas/openapi-admin.json delete /invocations/{invocation_id} Use kill_invocation/cancel_invocation/purge_invocation instead. # Kill an invocation Source: https://docs.restate.dev/admin-api/invocation/kill-an-invocation schemas/openapi-admin.json patch /invocations/{invocation_id}/kill Forcefully terminates an invocation. **Warning**: This operation does not guarantee consistency for virtual object instance state, in-flight invocations to other services, or other side effects. Use with caution. For more information, see the [cancellation documentation](https://docs.restate.dev/services/invocation/managing-invocations#kill). # Pause an invocation Source: https://docs.restate.dev/admin-api/invocation/pause-an-invocation schemas/openapi-admin.json patch /invocations/{invocation_id}/pause # Purge a completed invocation Source: https://docs.restate.dev/admin-api/invocation/purge-a-completed-invocation schemas/openapi-admin.json patch /invocations/{invocation_id}/purge Deletes all state associated with a completed invocation, including its journal and metadata. This operation only applies to invocations that have already completed. For more information, see the [purging documentation](https://docs.restate.dev/services/invocation/managing-invocations#purge). # Purge invocation journal Source: https://docs.restate.dev/admin-api/invocation/purge-invocation-journal schemas/openapi-admin.json patch /invocations/{invocation_id}/purge-journal Deletes only the journal entries for a completed invocation, while retaining its metadata. This operation only applies to invocations that have already completed. # Restart invocation as new Source: https://docs.restate.dev/admin-api/invocation/restart-invocation-as-new schemas/openapi-admin.json patch /invocations/{invocation_id}/restart-as-new Creates a new invocation from a completed invocation, optionally copying partial progress from the original invocation's journal. The new invocation will have a different invocation ID. Use the `from` parameter to specify how much of the original journal to preserve. # Resume an invocation Source: https://docs.restate.dev/admin-api/invocation/resume-an-invocation schemas/openapi-admin.json patch /invocations/{invocation_id}/resume Resumes a paused or suspended invocation. If the invocation is backing off due to a retry, this will immediately trigger the retry. Optionally, you can change the deployment ID that will be used when the invocation resumes. For more information see [resume documentation](https://docs.restate.dev/services/invocation/managing-invocations#resume) # Get service Source: https://docs.restate.dev/admin-api/service/get-service schemas/openapi-admin.json get /services/{service} Returns detailed metadata about a specific service, including its type, handlers, and configuration settings. # Get service OpenAPI definition Source: https://docs.restate.dev/admin-api/service/get-service-openapi-definition schemas/openapi-admin.json get /services/{service}/openapi Returns the OpenAPI 3.1 specification for the service, describing all handlers and their request/response schemas. # List services Source: https://docs.restate.dev/admin-api/service/list-services schemas/openapi-admin.json get /services Returns a list of all registered services, including their metadata and configuration. # Modify service configuration Source: https://docs.restate.dev/admin-api/service/modify-service-configuration schemas/openapi-admin.json patch /services/{service} Updates the configuration of a registered service, such as public visibility, retention policies, and timeout settings. Note: Service re-discovery will update these settings based on the service endpoint configuration. # Modify service state Source: https://docs.restate.dev/admin-api/service/modify-service-state schemas/openapi-admin.json post /services/{service}/state Modifies the K/V state of a Virtual Object. For a detailed description of this API and how to use it, see the [state documentation](https://docs.restate.dev/operate/invocation#modifying-service-state). # Get service handler Source: https://docs.restate.dev/admin-api/service_handler/get-service-handler schemas/openapi-admin.json get /services/{service}/handlers/{handler} Returns detailed metadata about a specific handler within a service, including its input/output types and handler type. # List service handlers Source: https://docs.restate.dev/admin-api/service_handler/list-service-handlers schemas/openapi-admin.json get /services/{service}/handlers Returns a list of all handlers (methods) available in the specified service. # Create subscription Source: https://docs.restate.dev/admin-api/subscription/create-subscription schemas/openapi-admin.json post /subscriptions Creates a new subscription that connects an event source (e.g., a Kafka topic) to a Restate service handler. For more information, see the [subscription documentation](https://docs.restate.dev/operate/invocation#managing-kafka-subscriptions). # Delete subscription Source: https://docs.restate.dev/admin-api/subscription/delete-subscription schemas/openapi-admin.json delete /subscriptions/{subscription} Deletes a subscription. This will stop events from the source from being forwarded to the sink. # Get subscription Source: https://docs.restate.dev/admin-api/subscription/get-subscription schemas/openapi-admin.json get /subscriptions/{subscription} Returns the details of a specific subscription, including its source, sink, and configuration options. # List subscriptions Source: https://docs.restate.dev/admin-api/subscription/list-subscriptions schemas/openapi-admin.json get /subscriptions Returns a list of all registered subscriptions, optionally filtered by source or sink. # Get version information Source: https://docs.restate.dev/admin-api/version/get-version-information schemas/openapi-admin.json get /version Returns the server version, supported Admin API versions, and the advertised ingress endpoint. # AI Agent Quickstart Source: https://docs.restate.dev/ai-quickstart Build and run your first AI agent with Restate and popular AI SDKs This guide takes you through building your first AI agent with Restate and popular AI SDKs. We will run a simple weather agent that can answer questions about the weather using durable execution to ensure reliability. AI Agent Quickstart Select your AI SDK: **Prerequisites**: * [Node.js](https://nodejs.org/en/) >= v20 * OpenAI API key (get one at [OpenAI](https://platform.openai.com/)) Restate is a single self-contained binary. No external dependencies needed. ```shell theme={null} brew install restatedev/tap/restate-server restatedev/tap/restate ``` Start the server: ```shell theme={null} restate-server ``` Download prebuilt binaries from the [releases page](https://github.com/restatedev/restate/releases/latest): ```shell MacOS-x64 theme={null} BIN=/usr/local/bin && RESTATE_PLATFORM=x86_64-apple-darwin && \ curl -L --remote-name-all https://restate.gateway.scarf.sh/latest/restate-{server,cli}-$RESTATE_PLATFORM.tar.xz && \ tar -xvf restate-server-$RESTATE_PLATFORM.tar.xz --strip-components=1 restate-server-$RESTATE_PLATFORM/restate-server && \ tar -xvf restate-cli-$RESTATE_PLATFORM.tar.xz --strip-components=1 restate-cli-$RESTATE_PLATFORM/restate && \ chmod +x restate restate-server && \ sudo mv restate $BIN && \ sudo mv restate-server $BIN ``` ```shell MacOS-arm64 theme={null} BIN=/usr/local/bin && RESTATE_PLATFORM=aarch64-apple-darwin && \ curl -L --remote-name-all https://restate.gateway.scarf.sh/latest/restate-{server,cli}-$RESTATE_PLATFORM.tar.xz && \ tar -xvf restate-server-$RESTATE_PLATFORM.tar.xz --strip-components=1 restate-server-$RESTATE_PLATFORM/restate-server && \ tar -xvf restate-cli-$RESTATE_PLATFORM.tar.xz --strip-components=1 restate-cli-$RESTATE_PLATFORM/restate && \ chmod +x restate restate-server && \ sudo mv restate $BIN && \ sudo mv restate-server $BIN ``` ```shell Linux-x64 theme={null} BIN=$HOME/.local/bin && RESTATE_PLATFORM=x86_64-unknown-linux-musl && \ curl -L --remote-name-all https://restate.gateway.scarf.sh/latest/restate-{server,cli}-$RESTATE_PLATFORM.tar.xz && \ tar -xvf restate-server-$RESTATE_PLATFORM.tar.xz --strip-components=1 restate-server-$RESTATE_PLATFORM/restate-server && \ tar -xvf restate-cli-$RESTATE_PLATFORM.tar.xz --strip-components=1 restate-cli-$RESTATE_PLATFORM/restate && \ chmod +x restate restate-server && \ mv restate $BIN && \ mv restate-server $BIN ``` ```shell Linux-arm64 theme={null} BIN=$HOME/.local/bin && RESTATE_PLATFORM=aarch64-unknown-linux-musl && \ curl -L --remote-name-all https://restate.gateway.scarf.sh/latest/restate-{server,cli}-$RESTATE_PLATFORM.tar.xz && \ tar -xvf restate-server-$RESTATE_PLATFORM.tar.xz --strip-components=1 restate-server-$RESTATE_PLATFORM/restate-server && \ tar -xvf restate-cli-$RESTATE_PLATFORM.tar.xz --strip-components=1 restate-cli-$RESTATE_PLATFORM/restate && \ chmod +x restate restate-server && \ mv restate $BIN && \ mv restate-server $BIN ``` Start the server: ```shell theme={null} restate-server ``` ```shell theme={null} npm install --global @restatedev/restate-server@latest @restatedev/restate@latest ``` Start the server: ```shell theme={null} restate-server ``` Run the Restate Server: ```shell theme={null} docker run --name restate_dev --rm \ -p 8080:8080 -p 9070:9070 -p 9071:9071 \ --add-host=host.docker.internal:host-gateway \ docker.restate.dev/restatedev/restate:latest ``` Run CLI commands: ```shell theme={null} docker run -it --network=host \ docker.restate.dev/restatedev/restate-cli:latest \ invocations ls ``` Replace `invocations ls` with any CLI subcommand. You can find the Restate UI running on port 9070 (`http://localhost:9070`) after starting the Restate Server. Get the weather agent template for the [Vercel AI SDK](https://ai-sdk.dev/docs/foundations/overview) and Restate: ```shell theme={null} git clone https://github.com/restatedev/ai-examples.git && cd ai-examples/vercel-ai/template && npm install ``` Export your OpenAI key and run the agent: ```shell theme={null} export OPENAI_API_KEY=your_openai_api_key_here npm run dev ``` The weather agent is now listening on port 9080. Tell Restate where the service is running (`http://localhost:9080`), so Restate can discover and register the services and handlers behind this endpoint. You can do this via the UI (`http://localhost:9070`) or via: ```shell CLI theme={null} restate deployments register http://localhost:9080 ``` ```shell curl theme={null} curl localhost:9070/deployments --json '{"uri": "http://localhost:9080"}' ``` ```shell CLI theme={null} ❯ SERVICES THAT WILL BE ADDED: - agent Type: Service HANDLER INPUT OUTPUT run value of content-type 'application/json' value of content-type 'application/json' ✔ Are you sure you want to apply those changes? · yes ✅ DEPLOYMENT: SERVICE REV agent 1 ``` ```shell curl theme={null} { "id": "dp_17sztQp4gnEC1L0OCFM9aEh", "services": [ { "name": "Agent", "handlers": [ { "name": "run", "ty": "Shared", "input_description": "one of [\"none\", \"value of content-type 'application/json'\"]", "output_description": "value of content-type 'application/json'" } ], "ty": "Service", "deployment_id": "dp_17sztQp4gnEC1L0OCFM9aEh", "revision": 1, "public": true, "idempotency_retention": "1day" } ] } ``` If you run Restate with Docker, register `http://host.docker.internal:9080` instead of `http://localhost:9080`. When using [Restate Cloud](https://restate.dev/cloud), your service must be accessible over the public internet so Restate can invoke it. If you want to develop with a local service, you can expose it using our [tunnel](/deploy/server/cloud/#registering-restate-services-with-your-environment) feature. Invoke the agent via the Restate UI playground: go to `http://localhost:9070`, click on your service and then on playground. Restate UI Playground Or invoke via `curl`: ```shell theme={null} curl localhost:8080/agent/run --json '"What is the weather in Detroit?"' ``` Output: `The weather in Detroit is currently 17°C with misty conditions.`. The agent you just invoked uses Durable Execution to make agents resilient to failures. Restate persisted all LLM calls and tool execution steps, so if anything fails, the agent can resume exactly where it left off. We did this by using Restate's `durableCalls` middleware to persist LLM responses and using [Restate Context actions](/foundations/actions) (e.g. `ctx.run`) to make the tool executions resilient: ```ts expandable {"CODE_LOAD::https://raw.githubusercontent.com/restatedev/ai-examples/refs/heads/main/vercel-ai/template/src/app.ts?collapse_imports"} theme={null} async function weatherAgent(restate: restate.Context, prompt: string) { // The durableCalls middleware persists each LLM response in Restate, // so they can be restored on retries without re-calling the LLM const model = wrapLanguageModel({ model: openai("gpt-4o"), middleware: durableCalls(restate, { maxRetryAttempts: 3 }), }); const { text } = await generateText({ model, system: "You are a helpful agent that provides weather updates.", prompt, tools: { getWeather: tool({ description: "Get the current weather for a given city.", inputSchema: z.object({ city: z.string() }), execute: async ({ city }) => { // call tool wrapped as Restate durable step return await restate.run("get weather", () => fetchWeather(city)); }, }), }, stopWhen: [stepCountIs(5)], providerOptions: { openai: { parallelToolCalls: false } }, }); return text; } // create a Restate Service as the callable entrypoint // for our durable agent function const agent = restate.service({ name: "agent", handlers: { run: async (ctx: restate.Context, prompt: string) => { return weatherAgent(ctx, prompt); }, }, }); // Serve the entry-point via an HTTP/2 server restate.serve({ services: [agent], }); ``` The Invocations tab of the Restate UI shows us how Restate captured each LLM call and tool step in a journal: Restate UI Journal Entries Ask about the weather in Denver: ```shell theme={null} curl localhost:8080/agent/run --json '"What is the weather in Denver?"' ``` You can see in the service logs and in the Restate UI how each LLM call and tool step gets durably executed. We can see how the weather tool is currently stuck, because the weather API is down. Restate UI Durable Execution This was a mimicked failure. To fix the problem, remove the line `failOnDenver` from the `fetchWeather` function in the `utils.ts` file: ```ts {"CODE_LOAD::https://raw.githubusercontent.com/restatedev/ai-examples/refs/heads/main/vercel-ai/template/src/utils/weather.ts#weather"} theme={null} export async function fetchWeather(city: string) { failOnDenver(city); const output = await fetchWeatherFromAPI(city); return parseWeatherResponse(output); } ``` Once you restart the service, the agent resumes at the weather tool call and successfully completes the request. **Next step:** Follow the [Tour of Agents](/tour/vercel-ai-agents) to learn how to build agents with Restate and Vercel AI SDK, OpenAI Agents SDK, etc. **Prerequisites**: * Python >= v3.12 * [uv](https://docs.astral.sh/uv/getting-started/installation/) * OpenAI API key (get one at [OpenAI](https://platform.openai.com/))