JSON storage at the edge

Uma API mínima para guardar qualquer JSON.

Use um identificador como chave, envie um valor JSON e recupere-o de qualquer cliente HTTP. Cada alteração recebe uma versão e timestamps automáticos.

Serviço disponível

Base URL https://kv.helio.me

API pública e sem autenticação. Quem conhecer um ID poderá ler, substituir ou apagar seu conteúdo. Não armazene senhas, tokens, dados pessoais ou qualquer informação confidencial.

Quick start

Primeiros passos

Crie ou substitua um valor com PUT. O corpo pode ser objeto, array, string, número, booleano ou null.

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

HTTP reference

Endpoints

GET/:id

Retorna o valor atual, sua versão e os timestamps. Responde 404 quando o ID não existe.

GET/:id/version

Retorna somente id e version. Útil para verificar mudanças sem baixar o valor completo.

PUT/:id

Cria o ID com versão 1 ou substitui completamente o valor existente e incrementa a versão. Não faz merge de objetos.

DELETE/:id

Apaga definitivamente o item. Se ele for recriado depois, começará novamente na versão 1.

OPTIONSqualquer caminho

Responde ao preflight CORS. São permitidos os headers Content-Type, Authorization, If-None-Match e If-Match.

Data model

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
  }
}

version

Começa em 1 e aumenta a cada PUT bem-sucedido, mesmo quando o valor enviado é igual.

created_at

Instante UTC da criação. Registros antigos podem retornar null.

updated_at

Instante UTC da última gravação. Na criação, é igual a created_at. Registros antigos ainda não atualizados podem retornar null.

json

Qualquer valor JSON válido, sem campos obrigatórios como feito.

Consulta de versão

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

Exclusão

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

Browser & Node.js

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);
}

Constraints

Regras e limites

Regra	Valor
ID	De 1 a 100 caracteres: letras ASCII, números, hífen e sublinhado.
Expressão	`^[A-Za-z0-9_-]{1,100}$`
Payload	Máximo de 1.900.000 bytes em UTF-8.
Rate limit	30 requisições por IP a cada 10 segundos.
Cache	Respostas da API usam `Cache-Control: no-store`.
CORS	Qualquer origem pode chamar a API; `OPTIONS` responde ao preflight.
Autenticação	Nenhuma.

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

Failures

Erros

Status	Significado
400	ID fora do formato permitido ou corpo JSON inválido.
404	Rota inválida ou ID inexistente.
405	Método HTTP não suportado.
413	Corpo maior que 1.900.000 bytes.
429	Limite de requisições excedido; tente novamente após alguns segundos.
500	Falha interna ao persistir o item.

Exemplo de ID inexistente

{
  "error": "id não existe",
  "id": "minha_tarefa"
}