Uma API mínima para guardar qualquer JSON.

Primeiros passos

Crie ou substitua o documento completo com PUT /:id. Para alterar somente um valor, use PUT /:id/value?path=.... O corpo pode ser objeto, array, string, número, booleano ou null. Estes métodos canônicos são a opção recomendada; aliases via GET existem somente para clientes com limitação de método HTTP.

1. Salvar

curl -X PUT https://kv.helio.me/minha_tarefa \
  -H "Content-Type: application/json" \
  -d '{"titulo":"Comprar café","feito":false}'

2. Consultar

curl https://kv.helio.me/minha_tarefa

3. Apagar

curl -X DELETE https://kv.helio.me/minha_tarefa

Endpoints

Compatibilidade via GET

Clientes que só conseguem emitir GET podem transportar o comando em method e o valor JSON em data. Continue preferindo PUT e DELETE reais sempre que possível.

Contrato completo

# Leitura atual e alias explícito
GET /meu-id
GET /meu-id?method=GET

# Substituição completa
GET /meu-id?method=PUT&data=eyJub21lIjoiQW5hIn0

# Alteração por JSON Pointer
GET /meu-id/value?method=PUT&path=%2Fnome&data=IkJpYSI

# Exclusão
GET /meu-id?method=DELETE

# Versão, sempre somente leitura
GET /meu-id/version

data contém um valor JSON completo codificado em UTF-8 e depois em base64url canônico sem padding. eyJub21lIjoiQW5hIn0 representa {"nome":"Ana"}; IkJpYSI representa a string JSON "Bia".

Gerar data no Node.js

const valor = { nome: "Ana" };
const data = Buffer.from(JSON.stringify(valor), "utf8").toString("base64url");

console.log(data); // eyJub21lIjoiQW5hIn0

Gerar data no navegador

function base64urlJson(value) {
  const bytes = new TextEncoder().encode(JSON.stringify(value));
  let binary = "";
  for (const byte of bytes) binary += String.fromCharCode(byte);
  return btoa(binary)
    .replaceAll("+", "-")
    .replaceAll("/", "_")
    .replace(/=+$/, "");
}

const data = base64urlJson({ nome: "Ana" });

Gramática estrita

• method, data e seus valores são case-sensitive. Aceite somente GET, PUT e DELETE em maiúsculas nas rotas documentadas.
• Em GET /:id, method=GET aceita somente method; method=PUT exige exatamente um data; method=DELETE aceita somente method.
• Em GET /:id/value, somente method=PUT é válido, com exatamente um method, um path e um data.
• Parâmetros duplicados ou não documentados são rejeitados. GET /:id sem o nome exato method continua sendo leitura e tolera queries alheias.
• method só altera uma requisição cujo método HTTP real é GET. Queries com esses nomes não reinterpretam um PUT ou DELETE real.
• GET /:id/version é sempre somente leitura. GET /:id/value sem method continua respondendo 405.

Limites e exposição

• O JSON decodificado de data aceita no máximo 10.000 bytes UTF-8; a forma codificada aceita no máximo 13.334 caracteres.
• A URL absoluta de um alias mutante aceita no máximo 15.000 bytes. Host, ID, nomes de parâmetros, path percent-encoded e data compartilham esse orçamento; um caminho maior deixa menos espaço para data.
• A plataforma Cloudflare aceita URLs de até 16 KB. Acima desse limite, a borda pode rejeitar a requisição antes do erro estruturado da API.
• PUTs canônicos continuam aceitando corpos de até 1.900.000 bytes. O limite menor existe apenas para JSON transportado na URL.
• Base64url é codificação, não criptografia. A URL pode aparecer em histórico, logs, analytics, proxies e referers. Não use aliases mutantes para senhas, tokens, dados pessoais ou qualquer segredo.
• Cache-Control: no-store e Referrer-Policy: no-referrer reduzem alguns riscos, mas não impedem execução automática, histórico ou logs intermediários.

Atualizar um valor por caminho

Envie um único valor JSON bruto para PUT /:id/value e informe o endereço no parâmetro path. Esta operação não é JSON Patch nem JSON Merge Patch: ela cria ou substitui exatamente um valor.

Alterar uma folha existente

curl -X PUT \
  "https://kv.helio.me/config/value?path=%2Finterface%2Ftema" \
  -H "Content-Type: application/json" \
  -d '"escuro"'

Criar ancestrais ausentes

curl -X PUT \
  "https://kv.helio.me/config/value?path=%2Fpreferencias%2Fnotificacoes%2Femail" \
  -H "Content-Type: application/json" \
  -d 'true'

Se o ID não existir, ele começa como {}. Objetos ausentes são criados recursivamente. Assim, /items/0/name em um item ausente cria chaves de objeto chamadas items, 0 e name; a API nunca infere um array a partir de um token numérico.

Objetos e arrays

Escaping e codificação

O caminho usa JSON Pointer. Dentro de um segmento, escreva ~0 para a chave ~ e ~1 para a chave /. Primeiro monte o JSON Pointer e depois codifique-o como parâmetro de URL. path= é proibido porque apontaria para o documento completo; path=/ é válido e aponta para uma chave vazia.

const query = new URLSearchParams({ path: "/a~1b/tema" });
const response = await fetch(
  "https://kv.helio.me/config/value?" + query,
  {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify("escuro"),
  },
);

Semântica e limites

• Cada gravação aceita incrementa version, mesmo quando o valor final não muda.
• A resposta contém o item completo com timestamps e o novo valor.
• O caminho decodificado aceita até 4.096 bytes UTF-8 e 64 segmentos.
• O corpo e o documento final têm limite de 1.900.000 bytes UTF-8.
• O documento final aceita até 1.000 níveis aninhados de objetos e arrays, limite do parser JSON1 usado pela operação.
• PUT /:id pode armazenar JSON mais profundo, mas ele precisa ser substituído por um documento de até 1.000 níveis antes de aceitar atualizações por caminho.
• Uma atualização por caminho pode normalizar espaços insignificantes, mas preserva literais numéricos não alterados, como 9007199254740993 e 1e400.
• PUT /:id continua preservando o texto JSON bruto e substituindo o documento completo.
• Não há remoção por caminho, múltiplas mutações, inserção no meio de arrays, JSON Patch, JSON Merge Patch ou precondições If-Match.

Formato das respostas

Uma criação ou consulta retorna o envelope abaixo. O campo json contém exatamente o tipo de valor enviado.

{
  "id": "minha_tarefa",
  "version": 1,
  "created_at": "2026-07-12T22:32:19.374Z",
  "updated_at": "2026-07-12T22:32:19.374Z",
  "json": {
    "titulo": "Comprar café",
    "feito": false
  }
}

Consulta de versão

{
  "id": "minha_tarefa",
  "version": 1
}

Exclusão

{
  "ok": true,
  "id": "minha_tarefa"
}

Uso com JavaScript

A API aceita CORS de qualquer origem e pode ser chamada diretamente pelo navegador.

Salvar um valor

const response = await fetch("https://kv.helio.me/preferencias", {
  method: "PUT",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ tema: "escuro", idioma: "pt-BR" }),
});

if (!response.ok) throw new Error("Falha ao salvar");
const item = await response.json();
console.log(item.version);

Consultar um valor

const response = await fetch("https://kv.helio.me/preferencias");

if (response.status === 404) {
  console.log("O ID ainda não existe");
} else if (response.ok) {
  const item = await response.json();
  console.log(item.json);
}

Atualizar só um valor

const query = new URLSearchParams({ path: "/interface/tema" });
const updated = await fetch(
  "https://kv.helio.me/preferencias/value?" + query,
  {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify("claro"),
  },
).then((response) => response.json());

Regras e limites

Exemplos de IDs válidos

tarefa_1
config-app
usuario123
01J2Y8N7R6K5M4

IDs inválidos

minha tarefa   # espaço
perfil.json    # ponto
ação           # caracteres fora de ASCII
pasta/item     # barra cria outro segmento de rota

Contrato de erros

Falhas da API retornam JSON estruturado. code é estável para automação, retryable informa se repetir pode resolver o problema e hint sugere a próxima ação. Campos de contexto variam por código e nunca incluem o documento armazenado, data, seus bytes decodificados ou o JSON recebido.

{
  "error": "O caminho atravessa um valor que não é objeto nem array.",
  "code": "PATH_TYPE_CONFLICT",
  "retryable": false,
  "hint": "Substitua primeiro o valor bloqueador por um objeto ou use PUT /:id para substituir o documento completo.",
  "path": "/perfil/tema",
  "blocked_at": "/perfil",
  "actual_type": "string",
  "required_type": "object_or_array"
}

O WAF pode retornar 429 antes de a requisição chegar à API. Nesse caso, aguarde o período de bloqueio e tente novamente; o corpo não segue necessariamente o contrato estruturado acima.