Armazenamento chave-valor

Cada conta tem um store de chave-valor próprio: cada par pertence à conta do token, e o valor é JSON arbitrário (o servidor não impõe schema ao conteúdo). Os endpoints ficam sob /account-kv e exigem escopo Standard (veja Autenticação e tokens).

Corpo e resposta

• Corpo do PUT: { "key": <string>, "payload": <valor JSON> }. O payload é JSON livre.
• Resposta do PUT: sem payload útil (o envelope traz Ok nulo, Content-Type: application/json) e um cabeçalho ETag com a nova versão do valor.
• Resposta do GET /account-kv (listar): { "keys": [<string>, ...] }.
• Resposta do GET /account-kv/{chave} (ler): { "key", "payload", "created_at", "updated_at", "etag" }, mais o cabeçalho ETag.
• Resposta do DELETE: { "was_deleted": <bool> }.
• Ler uma chave inexistente devolve 404 (mensagem No data found for key).
• A chave é capturada por um wildcard de caminho, então pode conter barras (por exemplo, prefixo/sub/chave).

Escrita condicional

A leitura devolve um ETag, e o PUT aceita esse valor em If-Match para uma escrita condicional. Se o valor mudou desde a leitura, o PUT devolve 412 e não grava. O mecanismo está documentado em Convenções e erros.

Veja também

• Convenções e erros: a convenção de ETag, If-Match e códigos de erro.
• Referência das ferramentas MCP: as quatro operações pela IA (list_account_kv_keys, get_account_kv, put_account_kv, delete_account_kv); pela IA, o payload do put_account_kv tem de ser um objeto JSON, e array, string, número, booleano ou null só pelo PUT HTTP.