---
title: "Modify service state"
method: POST
path: "/services/{service}/state"
tags: ["service"]
---

# Modify service state

`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).

## Path parameters

- `service` string, required

## Request body

- ModifyServiceStateRequest
  - `new_state` object, required — # New State The new state to replace the previous state with
  - `object_key` string, required — # Service key To what virtual object key to apply this change
  - `scope` string, nullable — # Scope Optional scope for the virtual object instance. When set, targets the scoped instance instead of the unscoped one. Since v1.7.0.
  - `version` string, nullable — # Version If set, the latest version of the state is compared with this value and the operation will fail when the versions differ.

## Response `202`

State modification request accepted and will be applied asynchronously

## Other responses

- `400` — Bad request
- `404` — Not found
- `405` — Method not allowed
- `409` — Conflict
- `500` — Internal server error

## Changes

- **2026-06-19** `7381abc4d9a3` — 1 info
  - added the new optional request property `scope`
- **2026-01-30** `059a44500a5c` — 3 breaking, 3 info
  - the request property `version` became not nullable
  - added 'propertyNames' constraint to the request property `new_state`
  - the `new_state/additionalProperties/items/` request property type/format changed from `integer`/`uint8` to `integer`/`int32`
  - added the non-success response with the status `405`
  - …2 more

[Change history](https://skmtc.dev/restatedev/apis/admin-api/changes/services/:service/state/post.md)

---

[API](https://skmtc.dev/restatedev/apis/admin-api.md) · [All operations](https://skmtc.dev/restatedev/apis/admin-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/restatedev/admin-api/revisions/5361f4818c71/schema)