API para desenvolvedores

Início rápido

1. No painel, abra Conta → Tokens de API e crie um token. Ele aparece uma única vez; guarde em local seguro.
2. Guarde o token numa variável de ambiente e teste quem você é:

export LINKUS_TOKEN="lk_..."
curl "https://linkus.click/api/v1/me" -H "Authorization: Bearer $LINKUS_TOKEN"

3. Liste suas páginas, leia o rascunho de uma delas, altere e publique:

curl "https://linkus.click/api/v1/pages" -H "Authorization: Bearer $LINKUS_TOKEN"
curl "https://linkus.click/api/v1/pages/pg_Ab3dE5gH7jK9/document" -H "Authorization: Bearer $LINKUS_TOKEN"
curl -X POST "https://linkus.click/api/v1/pages/pg_Ab3dE5gH7jK9/publish" -H "Authorization: Bearer $LINKUS_TOKEN"

Autenticação e permissões

Envie o token no cabeçalho Authorization: Bearer lk_.... Com token, o cookie de sessão e o CSRF não são usados.

Por segurança, tokens não acessam conta, tokens nem administração (respondem 403): essas telas só funcionam no painel. Revogue um token a qualquer momento em Conta; só o hash dele fica guardado.

Os ids são públicos e opacos: pg_… página, med_… mídia, lead_… contato, msg_… mensagem. Um recurso de outra conta responde 404, como se não existisse.

Erros e limites

Todo erro tem o mesmo formato. Em details, path aponta o campo (JSON Pointer) e message diz o que fazer.

{
  "ok": false,
  "error": {
    "code": "validation_failed",
    "message": "Corrija os itens destacados antes de publicar.",
    "details": [
      { "path": "/sections/0/children/1/props/items/0/url", "rule": "pattern",
        "message": "Use um link que comece com https://, http://, mailto: ou tel:." }
    ]
  }
}

Documento de blocos

Cada página é um documento JSON (seções, colunas e blocos), independente do HTML. GET /api/v1/registry devolve os tipos de bloco, valores padrão e os JSON Schemas usados na validação.

• Rascunho: leia com /document (vem com revision) e salve com PUT /draft enviando a mesma revisão em If-Match. Se alguém salvou antes, a resposta é 409.
• Publicação: POST /publish aplica a validação completa e os limites do plano. A página pública só muda depois disso.
• Estilo: qualquer bloco aceita style (fundo, espaçamentos, cantos, borda, fonte, CSS personalizado com escopo no bloco). Campos que o tipo não conhece são recusados com a mensagem O campo "x" não existe neste bloco.
• Mídia: imagens entram por POST /api/v1/media e são usadas no documento como {"mediaId": "med_…"}. Só mídias da própria conta são aceitas.