Prompts

As perguntas enviadas aos modelos de IA segundo a cadência de monitorização configurada na conta, com os registos correspondentes a cada execução.

GET/dimensions/prompts

Lista os Prompts de um projeto.

Parâmetros:
  • project_idobrigatório
  • modelapenas os prompts com pelo menos uma execução nesse modelo, independentemente do resultado ou da data
  • collection_id
  • promptID do prompt
  • country_code
  • language_code
  • from
  • to
  • page
  • per_page≤100

Tanto from como to filtram pela data de criação do prompt.

GET/dimensions/prompt_executions

Lista as execuções de prompts num projeto.

Parâmetros:
  • project_idobrigatório
  • model
  • collection_id
  • promptID do prompt
  • country_code
  • language_code
  • prompt_type
  • brand_kind
  • from
  • to
  • page
  • per_page
  • mention_filter
  • citation_filter
  • competitorsa matriz de dois eixos descrita em GET /answers

GET/dimensions/query_fan_outs

As subconsultas que um modelo emitiu efetivamente ao responder aos seus Prompts monitorizados, útil para descobrir a formulação que os modelos pesquisam, em vez da formulação que escreveu. view=query (predefinido) devolve uma linha por subconsulta distinta, com a respetiva contagem e percentagem de todas as ocorrências; view=prompt devolve uma linha por prompt, com o número de subconsultas distintas que produziu. O Query Fan Out é comunicado sobretudo pelo ChatGPT, pelo que um resultado vazio significa normalmente que os modelos abrangidos não o expõem.

Parâmetros:
  • project_idobrigatório
  • viewquery ou prompt
  • querysubcadeia no texto da subconsulta
  • order
  • direction
  • model
  • collection_id
  • prompt
  • country_code
  • language_code
  • prompt_type
  • brand_kind
  • range
  • from
  • to
  • page
  • per_page
  • output

GET/suggested_prompts

A fila Prompts sugeridos, a mesma lista do separador Prompts sugeridos da aplicação: as sugestões de todos os geradores, da mais antiga para a mais recente e, por predefinição, apenas as pendentes.

Parâmetros:
  • project_idobrigatório
  • sourcewebsite, magic, topic, reddit, paa, reputational, translate, gsc ou catalog
  • statuspending, accepted, rejected ou all
  • page
  • per_page≤100, predefinição 50

GET/prompt_generations/:id

Consulte periodicamente uma execução de sugestões até o estado ser completed (com as sugestões que guardou) ou failed (com um código e uma mensagem de erro). A maioria das execuções termina em menos de um minuto. As execuções são mantidas durante 24 horas; as respetivas sugestões permanecem na fila.

Parâmetros:
  • project_idobrigatório
  • :ido id da execução, no URL

POST/prompts

Crie até 100 Prompts por pedido. Os Prompts existentes (mesmo texto + idioma) são ignorados.

Corpo (JSON):
  • project_idobrigatório
  • promptsarray, obrigatório, máx. 100
  • country_codeobrigatório
  • language_codeobrigatório

POST/prompts/import

A importação CSV da aplicação, em JSON. Cada linha tem país, idioma e etiquetas próprios. As etiquetas que ainda não existem são criadas, e os prompts duplicados são ignorados, mas recebem na mesma as etiquetas da linha; se os novos prompts excederem o limite do plano, nada é importado. Uma linha é ignorada e devolvida em row_errors quando o país ou o idioma da linha não é reconhecido, quando um prompt ficaria com mais de 50 etiquetas (somam-se as etiquetas de todas as linhas que repetem o mesmo prompt) ou quando as respetivas etiquetas levariam o pedido a ultrapassar as 500 etiquetas novas. Um membro da equipa precisa de acesso de criação a Etiquetas para criar uma etiqueta (sem esse acesso, uma linha que precise de uma etiqueta nova é ignorada e devolvida em row_errors) e de acesso de atualização a Prompts para atribuir etiquetas a um prompt que já existia (sem esse acesso, a linha não adiciona etiquetas a esse prompt e é devolvida em row_errors quando teria adicionado pelo menos uma). Requer uma chave de API com permissão de escrita e, para os membros da equipa, acesso de criação a Prompts.

  • Corpo (JSON): project_id (obrigatório), rows (array obrigatório, máx. 500) com prompt (obrigatório), country_code, language_code (códigos ou nomes; predefinição: os do projeto) e tags (array de nomes).

POST/prompt_generations

Inicia uma execução de sugestões de prompts com um dos geradores por trás dos assistentes Adicionar prompts da aplicação. A execução responde com 202 e decorre em segundo plano; as respetivas sugestões chegam à fila Prompts sugeridos e nada é monitorizado até as aceitar. Requer uma chave de API com permissão de escrita.

  • Corpo (JSON): project_id (obrigatório), source (obrigatório: website, keyword, topic, reddit, paa, reputational, translate ou search_console), country_code e language_code (predefinição: os do projeto). Por origem: query (opcional em keyword; obrigatório em topic e reddit), count (keyword e topic, 1-100, predefinição 20), competitor_id (keyword), search_type (reddit: topic ou brand), keywords (paa, até 5), source_country_code e source_language_code (translate), min_words e all_countries (search_console, plano Growth ou superior).

POST /suggested_prompts/accept + /reject

Aceita sugestões pendentes para as monitorizar como prompts, cada uma com o respetivo país e idioma e, opcionalmente, numa etiqueta, ou rejeita-as para que saiam da lista de pendentes. Quando os novos prompts excederiam o limite de prompts do plano, nada é aceite (ERR_LIMIT_REACHED). Requer uma chave de API com permissão de escrita.

Corpo (JSON):
  • project_idobrigatório
  • idsarray obrigatório, máx. 100

Em accept, também pode indicar uma etiqueta através de tag_ids ou tag_names, e create_missing (bool).

PATCH/prompts/:id

Define manualmente a intenção de pesquisa (prompt_type) e/ou o foco de marca (brand_kind) de um prompt, exatamente como quando edita os respetivos distintivos na página do prompt. O prompt fica marcado como categorizado manualmente (categorization_source passa a manual), pelo que a categorização automática deixa de o alterar; na página do prompt, é possível voltar à categorização automática. Não disponível a partir de um portal de marca branca (ERR_INTEGRATION_UNAVAILABLE). Requer uma chave de API com âmbito de escrita e, para os membros da equipa, a permissão de atualização em Prompts. Também disponível como a ferramenta MCP update_prompt_categorization.

Caminho:
  • :idid do prompt

Corpo (JSON): project_id (obrigatório), prompt_type (informational|navigational|commercial|transactional), brand_kind (brand|brand_other|non_brand); pelo menos um dos dois. Qualquer outro campo, ou um valor desconhecido, devolve ERR_INVALID_PARAM.

DELETE/prompts/:id

Elimina um prompt. Irreversível; o prompt desaparece imediatamente, liberta uma vaga de prompt e o seu histórico (execuções, menções, citações e sentimento) é eliminado por uma tarefa em segundo plano. Requer uma chave de API com permissão de escrita.

Parâmetros:
  • project_idobrigatório
  • :idno URL

Devolve ERR_NOT_FOUND para prompts fora do projeto.