---
title: "Set Agent State"
method: PUT
path: "/api/v1/contexts/{context_id}/state/{key}"
tags: ["agent-state"]
---

# Set Agent State

`PUT /api/v1/contexts/{context_id}/state/{key}`

## Request

- Base URL: `https://memory.kagura-ai.com` (the document declares no server; this is the origin it was published from)
- URL: `https://memory.kagura-ai.com/api/v1/contexts/{context_id}/state/{key}`
- Auth: none declared

Upsert ``value`` at ``(context_id, key)`` (PUT = idempotent, 200 on replace).

## Path parameters

- `context_id` string, uuid, required
- `key` string, required

## Headers

- `authorization` string, nullable

## Request body

- AgentStateSetRequest: Body for upserting an agent-state entry. ``value`` is arbitrary JSON (stored in the JSONB column) but must not be null — the column is NOT NULL, and a null value is rejected up front as a 422 rather than surfacing as a DB-layer 500.
  - `value` unknown, required
  - `ttl_seconds` integer, nullable: Optional TTL in seconds (clamped server-side to 30 days). Omit to persist until explicitly deleted.

## Response `200`

Successful Response

- AgentStateKeyResponse: Envelope for a write that returns just the affected key (set / delete).
  - `key` string, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud.md) · [All operations](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud/llms.txt) · [OpenAPI document](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud/revisions/09f17f5ada29?raw)