---
title: "Save JSON and append state.updated atomically"
method: PUT
path: "/api/v1/addresses/{addressId}/state/{key}"
tags: ["State"]
---

# Save JSON and append state.updated atomically

`PUT /api/v1/addresses/{addressId}/state/{key}`

## Request

- Base URL: `https://agentaddress.dev`
- URL: `https://agentaddress.dev/api/v1/addresses/{addressId}/state/{key}`
- Auth: HTTP bearer

32 keys and 65,536 bytes total, including keys and metadata. State lasts until replaced/deleted/address expiry. A full feed rolls back the mutation. Stale revisions return 409 revision_conflict.

## Path parameters

- `addressId` string, required
- `key` string, required

## Request body

- object
  - `value` unknown, required
  - `if_revision` integer: 0 creates only; omit to replace; otherwise compare against the observed revision

## Response `200`

Authorized response; never cached

- StateValue
  - `key` string, required
  - `value` unknown, required
  - `revision` integer, required
  - `updated_at` string, date-time, required
  - `event_id` string

## Other responses

- `400`: Structured API error
- `401`: Structured API error
- `404`: Structured API error
- `409`: Structured API error
- `429`: Wait Retry-After seconds; minute, hourly or UTC daily window applies

---

[API](https://skmtc.dev/agentaddress/apis/agentaddress-api.md) · [All operations](https://skmtc.dev/agentaddress/apis/agentaddress-api/llms.txt) · [OpenAPI document](https://skmtc.dev/agentaddress/apis/agentaddress-api/revisions/e41b8c27b4ca?raw)