Armazenamento chave-valor

Guarde e leia pares chave-valor sem subir banco nenhum. Cada cliente só vê as próprias chaves, não tem como ler ou sobrescrever a chave de outra conta, mesmo que o nome seja igual.

Key-value storage

Store and read key-value pairs without standing up a database. Each client only ever sees its own keys, there's no way to read or overwrite another account's key, even with the same name.

SYNC resposta na mesma chamada answers in the same call

Endpoints

PUT/api/v1/kv/{key} grava (ou atualiza) uma chavewrites (or updates) a key

GET/api/v1/kv/{key} lê uma chavereads a key

DELETE/api/v1/kv/{key} remove uma chavedeletes a key

GET/api/v1/kv lista suas chaves (paginado)lists your keys (paginated)

A listagem devolve só os nomes das chaves, nunca os valores. Mantém a resposta pequena não importa o tamanho do que está guardado. Pra ver um valor, é um GET por chave.

Listing returns only the key names, never the values. Keeps the response small regardless of how much is stored. To see a value, it's a GET per key.

Corpo do PUT

PUT body

Campo	Field	Descrição	Description
`value`	o valor a guardar, como string. Dado binário fica por conta de quem chama, em base64: não é um endpoint de bytes crus	the value to store, as a string. Binary data is the caller's own base64 responsibility: this isn't a raw-bytes endpoint
`ttl_seconds`	opcional, padrão `0` (sem expiração): depois desse tempo a chave some sozinha	optional, defaults to `0` (no expiry): the key disappears on its own after this long

Exemplo

Example

# grava# write
        curl -X PUT https://api.alicercelabs.com.br/api/v1/kv/preferencia-tema \
          -H "Authorization: Bearer <token>" \
          -d '{"value": "escuro", "ttl_seconds": 0}'
        
        # lê# read
        curl https://api.alicercelabs.com.br/api/v1/kv/preferencia-tema \
          -H "Authorization: Bearer <token>"

{
          "success": true,
          "data": { "key": "preferencia-tema", "value": "escuro" },
          "meta": { "elapsed_ms": 3, "request_id": "..." }
        }

Erros possíveis

Possible errors

Status	Motivo	Reason
400	chave vazia ou maior que 256 caracteres, corpo inválido, valor maior que a cota, ou limite de chaves atingido pra uma chave nova (atualizar uma já existente sempre é permitido, mesmo no limite)	empty/too-long key, invalid body, value over quota, or key-count limit reached for a new key (updating an existing one is always allowed, even at the limit)
401	token ausente ou inválido	missing or invalid token
404	chave não encontrada: nunca existiu, foi removida, ou expirou	key not found: never existed, was deleted, or expired
429	limite de taxa excedido: leitura e escrita têm cotas separadas	rate limit exceeded: reads and writes have separate quotas

Usando o SDK

Using the SDK

Quatro operações: chave-valor simples, com TTL opcional no put.

Four operations: simple key-value, with an optional TTL on put.

SDKs oficiais: Go · Python · JavaScript.

Official SDKs: Go · Python · JavaScript.

Gravar / ler um valor

Write / read a value

import (
	"context"
	"fmt"

	alicercelabs "github.com/alicercelabs/alicercesdk-go"
)

client := alicercelabs.New("alk_...")
ctx := context.Background()

err := client.KV.Put(ctx, "tema", "escuro", 3600) // TTL em segundos, 0 = sem expiração
valor, err := client.KV.Get(ctx, "tema")
fmt.Println(valor) // "escuro"

from alicercelabs import AlicerceLabs

client = AlicerceLabs(api_key="alk_...")

client.kv.put("tema", "escuro", ttl_seconds=3600)  # 0 = sem expiração
valor = client.kv.get("tema")
print(valor)  # "escuro"

import { AlicerceLabs } from "alicercesdk-javascript";

const client = new AlicerceLabs("alk_...");

await client.kv.put("tema", "escuro", 3600); // 0 = sem expiração
const valor = await client.kv.get("tema");
console.log(valor); // "escuro"

Listar chaves

List keys

paginado por cursor, varredura incremental sem travar a listagem.

cursor-paginated, incremental scan that never locks the listing.

res, err := client.KV.List(ctx, 0, 100)
fmt.Println(res.Keys, res.NextCursor)

res = client.kv.list(cursor=0, count=100)
print(res["keys"], res["next_cursor"])

const res = await client.kv.list({ cursor: 0, count: 100 });
console.log(res.keys, res.next_cursor);

Remover uma chave

Delete a key

err := client.KV.Delete(ctx, "tema")

client.kv.delete("tema")

await client.kv.delete("tema");

Limites

Limits

1.000/dia · 41/hora por operação (leitura e escrita contam separado). Cotas de armazenamento, por cliente: até 1000 chaves, até 64KB por valor.

1,000/day · 41/hour per operation (reads and writes counted separately). Storage quotas, per client: up to 1000 keys, up to 64KB per value.