A tua primeira chamada à API em 5 minutos

O caminho mais rápido é um personal access token — sem OAuth, sem registo de aplicação. Lê e escreve os teus próprios dados do pon, que é exatamente o que precisas para scripts, Home Assistant e projetos de homelab.

1. Instala o pon no teu iPhone

   A tua conta e as tuas listas vivem na app — descarrega o pon da App Store e regista-te lá.

   

2. Inicia sessão em my.pon.app

   Usa a tua conta pon. O teu e-mail tem de estar confirmado — caso contrário, a ativação responde 403 EMAIL_UNVERIFIED.

3. Ativa o modo de programador

   my → Para programadores. Aceitas os termos da API uma única vez.

4. Cria um token

   Escolhe os scopes de que precisas. O segredo pon_pat_… é mostrado uma vez — guarda-o como uma palavra-passe. Validade: 90 dias por omissão, até 365, ou nunca.

5. Chama a API

   É tudo — Bearer simples, sem danças de assinatura:

# list your lists
curl https://api.pon.app/v3/lists \
  -H "Authorization: Bearer pon_pat_XXXX"

const res = await fetch("https://api.pon.app/v3/lists", {
  headers: { Authorization: "Bearer pon_pat_XXXX" },
});
const { data } = await res.json();
console.log(data);

import requests

res = requests.get(
    "https://api.pon.app/v3/lists",
    headers={"Authorization": "Bearer pon_pat_XXXX"},
)
print(res.json()["data"])

Adiciona um item

POST /v3/lists/{list-id}/items — o lado da escrita funciona da mesma forma:

curl -X POST https://api.pon.app/v3/lists/LIST_ID/items \
  -H "Authorization: Bearer pon_pat_XXXX" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Oat milk" }'

await fetch(`https://api.pon.app/v3/lists/${listId}/items`, {
  method: "POST",
  headers: {
    Authorization: "Bearer pon_pat_XXXX",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Oat milk" }),
});

requests.post(
    f"https://api.pon.app/v3/lists/{list_id}/items",
    headers={"Authorization": "Bearer pon_pat_XXXX"},
    json={"name": "Oat milk"},
)

Todas as respostas usam o mesmo envelope: { "data": …, "meta": … } em caso de sucesso, { "errors": [ { "code", "message" } ] } em caso de falha.

Próximos passos

• Autenticação — quando basta um token e quando queres OAuth.
• Webhooks — reage a alterações de listas sem polling.
• Limites e fair use — o que é generoso e o que é um limite duro.