🗃️KV Store•PUT /v1/kv/{namespace}/{key}

KV Store

Tenant-isolated JSON state with CAS and TTL for durable agent memory.

What it does

Stores namespaced JSON values for each agent with optional TTL expiry and compare-and-set tokens so concurrent writes do not clobber each other.

Endpoint

Method: PUT

Path: PUT /v1/kv/{namespace}/{key}

Auth: x-agent-id + x-api-key

Request shape

•value: any JSON serializable object
•ttl_seconds?: number
•cas?: string

Example requests

Copy-pasteable examples for agents and automation.

cURL

curl -X PUT "https://www.agent-utils.com/v1/kv/state/last-seen" \
  -H "x-agent-id: poller" -H "x-api-key: agutil_agt_…" \
  -H "content-type: application/json" \
  -d '{
    "value": { "event_id": "evt_42" },
    "ttl_seconds": 86400
  }'

Python

import requests

resp = requests.put(
    "https://www.agent-utils.com/v1/kv/state/last-seen",
    headers={
        "x-agent-id": "poller",
        "x-api-key": "agutil_agt_…",
        "content-type": "application/json",
    },
    json={
        "value": {"event_id": "evt_42"},
        "ttl_seconds": 86400,
    },
)
assert resp.status_code == 200

JavaScript

const res = await fetch("https://www.agent-utils.com/v1/kv/state/last-seen", {
  method: "PUT",
  headers: {
    "x-agent-id": "poller",
    "x-api-key": "agutil_agt_…",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    value: { event_id: "evt_42" },
    ttl_seconds: 86400,
  }),
});

How agents use it

A polling agent reads the last processed event ID, fetches new events, then writes the new cursor back with CAS.

An orchestrator stores a task plan under a namespace and child agents update progress independently.

A recovery agent resumes after restart by loading the last checkpointed JSON blob.

When to use it

✓Persist an agent conversation or task state between runs.
✓Track cursors, last-seen IDs, or resumable progress markers.
✓Store feature flags or agent configuration without running your own Redis.

When not to use it

•You only need ephemeral in-process variables during one request.
•You need full relational queries, joins, or analytics.

Failure modes

•Concurrent writers should use CAS or they may overwrite each other.
•TTL expiry deletes state, so do not store only copy of important data there.
•Namespaces must be chosen consistently or agents will read the wrong state.

Machine-readable summary

This JSON block is stable for crawlers, agents, and downstream documentation pipelines.

{
  "slug": "kv-store",
  "title": "KV Store",
  "canonical": "/docs/kv-store",
  "endpoint": "PUT /v1/kv/{namespace}/{key}",
  "method": "PUT",
  "auth": "x-agent-id + x-api-key",
  "machine_readable": true,
  "request_shape": [
    "value: any JSON serializable object",
    "ttl_seconds?: number",
    "cas?: string"
  ],
  "agent_workflows": [
    "A polling agent reads the last processed event ID, fetches new events, then writes the new cursor back with CAS.",
    "An orchestrator stores a task plan under a namespace and child agents update progress independently.",
    "A recovery agent resumes after restart by loading the last checkpointed JSON blob."
  ],
  "failure_modes": [
    "Concurrent writers should use CAS or they may overwrite each other.",
    "TTL expiry deletes state, so do not store only copy of important data there.",
    "Namespaces must be chosen consistently or agents will read the wrong state."
  ]
}

Related docs

audit-log checkpoint