Recomendações

As mesmas execuções de recomendações que alimentam a página Recomendações da aplicação, mais o endpoint que lança uma nova.

GET/recommendations

Lista as execuções de recomendações de um projeto com filtros de tipo e estado.

Parâmetros:
  • project_idobrigatório
  • recommendation_typeai_visibility|social_community|brand_building|sentiment_reputation
  • statuspending|processing|completed|failed
  • page
  • per_page

Valores de enum inválidos devolvem ERR_INVALID_PARAM.

GET/recommendations/:id

Uma execução de recomendações com os respetivos itens e dados do relatório: array de itens com título, prioridade, passos de ação, metadados, referências de origem, além da contagem de itens agrupada por active, completed, archived.

Parâmetros:
  • project_idobrigatório
  • :idno URL
  • item_statusactive|completed|archived
  • resolve_source_refspredefinido true

POST/recommendations

Inicia uma nova geração (o mesmo motor da página Recomendações na aplicação). A execução é assíncrona (1 a 3 minutos); consulte GET /recommendations/:id até o estado indicar completed. Consome o orçamento semanal de itens de recomendação do projeto (ERR_LIMIT_REACHED quando se esgota ou quando já existe uma execução do mesmo tipo pendente). sentiment_reputation requer o plano Scale ou superior. Requer uma chave de API com permissão de escrita.

Corpo (JSON):
  • project_idobrigatório
  • recommendation_typeai_visibility predefinido | social_community | brand_building | sentiment_reputation

PATCH/recommendations/:id/items/:item_id

Marca um item de uma execução de recomendações como completed, arquiva-o (archived) ou devolve-o a active, tal como os botões da página Recomendações. Ao arquivar, um reason opcional ensina as execuções seguintes: not_relevant e too_complex afastam as próximas recomendações de outras semelhantes e, num item de relações públicas e criação de citações que aponta para um domínio, competitor ou not_relevant impedem que esse site volte a ser sugerido. Devolve o item com a mesma estrutura com que GET /recommendations/:id lista os itens. Requer uma chave de API com âmbito de escrita e, para os membros da equipa, a permissão de criação em Recomendações. Também disponível como a ferramenta MCP update_recommendation_item.

Caminho:
  • :idid da execução de recomendações
  • :item_id

Corpo (JSON): project_id (obrigatório), status (obrigatório: completed|archived|active), reason (opcional, apenas com archived: not_relevant|too_complex|competitor; competitor apenas em itens com metadata.domain). Devolve ERR_NOT_FOUND para uma execução ou um item fora do projeto e ERR_INVALID_PARAM para um motivo que não se aplica.