Fala, pessoal. De boa?

Depois do 3x0 do Brasil e de ter recebido o alerta da defesa civil na madrugada, queria listar alguns endpoints da API do TabNews. A API em sim tem uma série de outros endpoints voltados para analytics e monitoramento. Não vou considerá-los aqui por que ainda não usei pra nada. Aqui vou focar em Session, User e Contents. Acho que esses são os principais.

API TabNews

URL Base: https://www.tabnews.com.br/api/v1

---

Autenticação & Sessões

POST /sessions

Cria uma nova sessão (login). Define um cookie de sessão em caso de sucesso. Se o usuário ainda não estiver ativado, envia um novo e-mail de ativação e retorna 403.

• Autenticação: pública
• Body:

  Campo	Obrigatório
  email	obrigatório
  password	obrigatório

• Resposta 201: objeto de sessão

---

DELETE /sessions

Expira a sessão atual (logout). Limpa o cookie de sessão.

• Autenticação: requer feature read:session (sessão ativa)
• Resposta 200: objeto de sessão expirada

---

PATCH /activation

Ativa uma conta de usuário usando o token enviado por e-mail.

• Autenticação: pública
• Body:

  Campo	Obrigatório
  token_id	obrigatório

• Resposta 200: objeto do token

---

PATCH /email-confirmation

Confirma uma alteração de e-mail usando um token enviado para o novo endereço.

• Autenticação: pública
• Body:

  Campo	Obrigatório
  token_id	obrigatório

• Resposta 200: objeto do token

---

POST /recovery

Solicita um token de recuperação de senha, enviado para o e-mail do usuário.

• Autenticação: pública
• Body (ao menos um obrigatório):

  Campo	Obrigatório
  username	opcional
  email	opcional

• Resposta 201: objeto do token de recuperação

---

PATCH /recovery

Redefine a senha do usuário usando um token de recuperação.

• Autenticação: pública
• Body:

  Campo	Obrigatório
  token_id	obrigatório
  password	obrigatório

• Resposta 200: objeto do token

---

Usuários

POST /users

Cria uma nova conta de usuário. Envia um e-mail de ativação.

• Autenticação: pública
• Body:

  Campo	Obrigatório
  username	obrigatório
  email	obrigatório
  password	obrigatório

• Resposta 201: objeto de usuário

---

GET /users/:username

Retorna o perfil público de um usuário, incluindo saldos de TabCoin e TabCash.

• Autenticação: pública
• Cache: SWR 10s
• Path: username (obrigatório)
• Resposta 200: objeto de usuário

---

PATCH /users/:username

Atualiza o perfil de um usuário. Usuários só podem atualizar o próprio perfil, a menos que tenham a feature update:user:others.

• Autenticação: requer feature update:user
• Path: username (obrigatório)
• Body:

  Campo	Obrigatório
  username	opcional
  email	opcional
  description	opcional
  notifications	opcional

• Resposta 200: objeto de usuário atualizado
• Observação: a alteração de senha por este endpoint está atualmente desabilitada.

---

GET /user

Retorna o perfil do próprio usuário autenticado, incluindo saldo, features e recompensa diária de TabCoins. Renova a sessão automaticamente se ela expirar em menos de 3 semanas.

• Autenticação: requer feature read:session
• Resposta 200: objeto de usuário (visão própria)

---

Conteúdos

GET /contents

Lista todos os conteúdos raiz publicados. Paginado.

• Autenticação: pública
• Cache: SWR 10s
• Query:

  Parâmetro	Obrigatório	Observações
  page	opcional
  per_page	opcional
  strategy	opcional	ex.: new, relevant
  with_children	opcional	Incluir comentários
  with_root	opcional	Incluir posts raiz

• Resposta 200: array de objetos de conteúdo (com cabeçalhos de paginação)

---

POST /contents

Cria um novo conteúdo (post ou comentário). Pode transmitir a resposta como NDJSON ao criar um comentário, caso o cliente envie Accept: application/x-ndjson.

• Autenticação: requer feature create:content:text_root (posts) ou create:content:text_child (comentários)
• Body:

  Campo	Obrigatório	Observações
  body	obrigatório
  parent_id	opcional	Definido para criar um comentário
  title	opcional
  slug	opcional
  status	opcional	draft ou published
  source_url	opcional
  content_type	opcional

• Resposta 201: objeto de conteúdo (ou stream NDJSON)

---

GET /contents/:username

Lista os conteúdos publicados por um usuário específico. Paginado.

• Autenticação: pública
• Cache: SWR 10s
• Path: username (obrigatório)
• Query:

  Parâmetro	Obrigatório
  page	opcional
  per_page	opcional
  strategy	opcional
  with_root	opcional
  with_children	opcional

• Resposta 200: array de objetos de conteúdo (com cabeçalhos de paginação)

---

GET /contents/:username/:slug

Retorna um único conteúdo publicado, identificado pelo nome do autor e pelo slug.

• Autenticação: pública
• Cache: SWR 10s
• Path: username, slug (ambos obrigatórios)
• Resposta 200: objeto de conteúdo

---

PATCH /contents/:username/:slug

Atualiza um conteúdo. Usuários só podem editar o próprio conteúdo, a menos que tenham a feature update:content:others.

• Autenticação: requer feature update:content
• Path: username, slug (ambos obrigatórios)
• Body:

  Campo	Obrigatório
  title	opcional
  body	opcional
  slug	opcional
  status	opcional
  source_url	opcional

• Resposta 200: objeto de conteúdo atualizado

---

GET /contents/:username/:slug/children

Retorna a árvore completa de comentários de um conteúdo.

• Autenticação: pública
• Cache: SWR 10s
• Path: username, slug (ambos obrigatórios)
• Resposta 200: array de objetos de conteúdo filho (árvore)

---

GET /contents/:username/:slug/parent

Retorna o conteúdo pai direto de um comentário. Retorna 404 se o conteúdo já for um post raiz.

• Autenticação: pública
• Cache: SWR 10s
• Path: username, slug (ambos obrigatórios)
• Resposta 200: objeto de conteúdo pai

---

GET /contents/:username/:slug/root

Retorna o conteúdo raiz (ancestral) de uma thread de comentários. Retorna 404 se o conteúdo já for raiz.

• Autenticação: pública
• Cache: SWR 10s
• Path: username, slug (ambos obrigatórios)
• Resposta 200: objeto de conteúdo raiz

---

POST /contents/:username/:slug/tabcoins

Vota em um conteúdo (upvote ou downvote). Custa 2 TabCoins do votante. Limitado a 2 votos por conteúdo a cada 72 horas, por usuário/IP. Não é possível votar no próprio conteúdo.

• Autenticação: requer feature update:content
• Path: username, slug (ambos obrigatórios)
• Body:

  Campo	Obrigatório	Observações
  transaction_type	obrigatório	credit ou debit

• Resposta 201: { "tabcoins": <saldo atualizado> }

---

GET /contents/:username/:slug/thumbnail

Retorna uma miniatura PNG gerada pelo servidor para um conteúdo.

• Autenticação: pública
• Cache: SWR 60s
• Path: username, slug (ambos obrigatórios)
• Resposta 200: binário PNG (Content-Type: image/png)

---

GET /contents/rss

Retorna um feed RSS 2.0 com os 30 conteúdos raiz publicados mais recentes.

• Autenticação: pública
• Cache: SWR 60s
• Resposta 200: feed XML (Content-Type: text/xml)

A POST /sessions funcionava no passado mas foi "removida". Deve ter dado algum problema com a criação indiscriminada de usuários.

Aproveitando, caso alguém esteja trabalhando com Kotlin e não queria reiventar a roda, tenho mantido essa biblioteca aqui TabNews para Kotlin e acabei de publicar a versão 1.5.0 com um endpoint que tinha deixado de fora.

E aí? Vocês usam a API do TabNews para alguma coisa?