Nova API de Afirmações

Nova API de Afirmações

De loops infinitos a bem-estar instantâneo: a API de Afirmações foi reconstruída para entregar positividade diária e personalizada com zero atrito. Cada afirmação agora vem com um ID estável, dados limpos e sem espaços extras, e um schema rico — além de busca, paginação, endpoints de lote e diário, um kit completo de bem-estar e respostas em texto simples para SMS e assistentes de voz.

🚀 Novidades

  • IDs estáveis – Cada afirmação carrega um id consistente baseado em hash, para que widgets, notificações e caches permaneçam sincronizados.
  • Dados limpos, automaticamente – Os campos de texto e categoria têm espaços em branco extras removidos antes de chegar ao seu app.
  • Categorias inteligentes – As 19 categorias são derivadas diretamente do conjunto de dados e ordenadas, sem desvios de valores fixos no código.
  • Erros úteis – Categorias desconhecidas retornam um 404 claro em vez de travar ou entrar em loop.
  • Schema mais rico – Cada afirmação retorna id, text, category, mood, lang e length.
  • Encontre o que você precisa – Busca e paginação no endpoint de listagem, além de um endpoint de lote configurável.
  • Escolhas diárias determinísticas – /today retorna a mesma afirmação do dia para todos os usuários.
  • Kit de bem-estar – Personalize por nome, reformule pensamentos negativos e combine afirmações com exercícios de respiração.

🛠 Endpoints da API

1. Listar Afirmações

GET /v1/affirmations

Parâmetros:

  • category (opcional): Filtre a lista por categoria, como confidence ou self-love.
  • search (opcional): Busca em texto completo no texto das afirmações.
  • page (padrão: 1): Número da página para paginação.
  • limit (padrão: 10): Resultados por página, até um máximo de 50.
  • lang (padrão: en): Código de idioma. Nesta versão, o conteúdo retornado é em inglês.

2. Afirmação Aleatória

GET /v1/affirmations/random

Parâmetros:

  • category (opcional): Retorna uma afirmação aleatória de uma categoria específica.
  • lang (padrão: en): Código de idioma. Nesta versão, o conteúdo retornado é em inglês.
  • format (padrão: json): Use json para o objeto completo ou text para uma resposta em texto simples.

3. Afirmação Aleatória por Categoria

GET /v1/affirmations/categories/{category}/random

Parâmetros:

  • category (obrigatório): A categoria de onde escolher, como sleep. Categorias desconhecidas retornam um 404 claro.

4. Listar Categorias

GET /v1/affirmations/categories

Retorna a lista completa e ordenada de categorias — de anxiety-relief e calm a confidence, focus, gratitude, parenting, resilience, self-love, sleep, success e muito mais.

5. Afirmações em Lote

GET /v1/affirmations/batch

Parâmetros:

  • category (opcional): Filtre o lote por categoria.
  • limit (padrão: 10): Número de afirmações a retornar, até um máximo de 50.
  • lang (padrão: en): Código de idioma. Nesta versão, o conteúdo retornado é em inglês.

6. Afirmação de Hoje

GET /v1/affirmations/today

Parâmetros:

  • category (opcional): Retorna a escolha diária determinística dentro de uma categoria.
  • lang (padrão: en): Código de idioma. Nesta versão, o conteúdo retornado é em inglês.

O alias /daily retorna a mesma afirmação do dia.

7. Personalizar

POST /v1/affirmations/personalize

Corpo:

  • mood (opcional): Humor ou categoria de onde extrair, como confidence. O padrão é happiness.
  • goal (opcional): A intenção por trás da afirmação.
  • name (opcional): Um nome para inserir na afirmação, por exemplo “I am confident, Ava.”

8. Reformule um Pensamento Negativo

POST /v1/affirmations/reframe

Corpo:

  • negativeThought (obrigatório): O pensamento a reformular, por exemplo “I always fail”.

Retorna uma declaração reformulada junto com uma afirmação de resiliência correspondente.

9. Pacote de Afirmação + Respiração

GET /v1/affirmations/bundle

Parâmetros:

  • category (opcional): A categoria de onde extrair. A categoria sleep retorna o exercício de respiração 4-7-8; todas as outras categorias retornam respiração box.

10. Agenda Sugerida

GET /v1/affirmations/schedule

Parâmetros:

  • timezone (opcional): Rótulo de fuso horário para os horários sugeridos, por exemplo Europe/Berlin. O padrão é UTC.

📦 Exemplos de Resposta

Afirmação aleatória:

{
  "id": 1874329517,
  "text": "I am confident, capable, and ready for today.",
  "category": "confidence",
  "mood": "confidence",
  "lang": "en",
  "length": 42
}

Afirmação personalizada:

{
  "id": 55123874,
  "text": "I am confident, Ava.",
  "category": "confidence",
  "mood": "confidence",
  "lang": "en",
  "length": 20
}

Pensamento reformulado:

{
  "reframe": "Even though \"I always fail\", I choose to believe: I am learning and growing every day.",
  "affirmation": {
    "id": 912345678,
    "text": "I am learning and growing every day.",
    "category": "resilience",
    "mood": "resilience",
    "lang": "en",
    "length": 36
  }
}

Pacote de bem-estar:

{
  "affirmation": {
    "id": 44556677,
    "text": "I release the day and welcome rest.",
    "category": "sleep",
    "mood": "sleep",
    "lang": "en",
    "length": 36
  },
  "breathing": {
    "name": "4-7-8",
    "steps": ["Inhale 4s", "Hold 7s", "Exhale 8s"]
  }
}

Agenda sugerida:

{
  "morning": "08:00 Europe/Berlin",
  "evening": "21:00 Europe/Berlin",
  "timezone": "Europe/Berlin"
}

✨ Respostas em Múltiplos Formatos

O endpoint random fala tanto JSON quanto texto simples. Use ?format=json (o padrão) para o objeto estruturado completo em apps web e mobile, ou ?format=text para uma string pronta para envio em fluxos de SMS, assistentes de voz e widgets.

🎯 Feito Para

  • Desenvolvedores que criam apps de bem-estar, chatbots e recursos de motivação e querem uma API estável e bem documentada.
  • Product managers que aumentam o engajamento com notificações diárias, sequências (streaks) e conteúdo diário determinístico.
  • Criadores de apps de bem-estar que precisam de conteúdo de afirmações confiável e categorizado em escala.
  • Equipes corporativas que esperam endpoints escaláveis no estilo SDK com onboarding pronto para o Postman.

🌟 Por Que Escolher a API de Afirmações?

  • Confiável por design: IDs estáveis, dados sem espaços extras e 404s claros significam menos surpresas em produção.
  • Profundidade quando você precisa: 19 categorias que vão do alívio da ansiedade ao amor-próprio.
  • Mais do que uma chamada: Personalização, reformulação, pacotes de respiração e agendamento em uma única API.
  • Amigável para desenvolvedores: Busca, paginação, processamento em lote, respostas em múltiplos formatos e snippets prontos para uso.
  • Pronto para bem-estar: 99.99% de uptime com respostas de baixa latência para momentos positivos do dia a dia.

🚀 Comece Agora

  • Coleção do Postman: Importe docs/affirmations-postman.json para explorar todos os endpoints com um clique.
  • Snippets de código: Copie exemplos prontos para executar em cURL, JavaScript e Python de docs/affirmations-snippets.md.
  • Pronto para LLM: docs/llms.txt oferece aos agentes de IA um resumo estruturado da API.

Comece a criar momentos positivos hoje mesmo — chame o endpoint today para uma afirmação diária determinística e depois adicione personalização e pacotes de respiração para completar a experiência de bem-estar.