v1Recursos/AEO/postAdicionar prompts monitorados a um site

Adicionar prompts monitorados a um site

Adiciona prompts ao conjunto monitorado de um site como prompts ativos: de 1 a 50 por solicitação, cada um com até 500 caracteres. No máximo 16 prompts podem estar ativos ao mesmo tempo; uma solicitação que ultrapassaria esse limite retorna 409 prompt_limit e não salva nada. Cada linha é aparada e seus espaços são condensados. Uma linha vazia ou longa demais retorna 400 invalid_input; uma linha que repete um prompt atual (sem diferenciar maiúsculas nem espaços) ou outra linha da solicitação é informada em issues, como 409 duplicate_prompt quando todos os problemas são duplicados. Salvar só muda o que a próxima verificação mede: nunca inicia, compra nem reagenda uma verificação, não consome créditos e mantém o agendamento como está. Exige a permissão Manage AEO prompts — proprietários e administradores a têm, os demais membros só quando ela lhes foi concedida (caso contrário, 403 forbidden) — e o gerenciamento de prompts ativado para a agência (caso contrário, 403 feature_disabled). Responde 201 com os ids dos novos prompts, ou 200 quando repete uma solicitação anterior com o mesmo mutationId. Uma falha inesperada retorna 503 prompts_unavailable.

post/api/v1/aeo/prompts
aeo:write
Corpo da solicitação
locationIdstringobrigatório
O id de local da entidade de site. Um site que você não pode ver, ou que não existe, retorna 404; um local físico retorna 422 entity_type_not_supported.
textsarray of stringobrigatório
Os prompts a adicionar, um por item: de 1 a 50 por solicitação, cada um com 1 a 500 caracteres após aparar. Eles são adicionados como prompts ativos depois dos existentes.
expectedRevisionintegerobrigatório
A revisão do conjunto que você leu por último (revision na visualização da lista). A alteração só é aplicada se ela ainda corresponder; caso contrário, retorna 409 prompt_set_changed com latestRevision, para que você leia o conjunto de novo e decida.
mutationIdstringobrigatório
Seu id para esta alteração: de 8 a 100 letras, dígitos, _ ou -. Em DELETE, envie-o no cabeçalho Idempotency-Key. Depois que uma alteração é salva com um id, repetir a mesma solicitação retorna replayed true e a visualização atual sem aplicá-la outra vez, e reutilizar esse id para outra solicitação retorna 409 mutation_reused. Uma solicitação que não alterou nada não guarda id: a repetição é decidida de novo com base na revisão atual (noop true, ou 409 prompt_set_changed se o conjunto mudou nesse meio-tempo). Se você não sabe se uma escrita foi aplicada, repita-a com o mesmo id, ou leia a lista e concilie, antes de enviar um novo id.
Resposta
dataobjectopcional
viewobjectopcional
locationIdstringopcional
O id de local da entidade de site.
namestringopcional
O nome do site.
eligibleboolean (true)opcional
Sempre true: só uma entidade de site tem uma lista de prompts monitorados.
canEditbooleanopcional
Se a pessoa que emitiu o token pode alterar este conjunto agora: ela tem a permissão Manage AEO prompts, o gerenciamento de prompts está ativado para a agência e a lista de prompts anterior não precisa de conciliação.
managedbooleanopcional
false enquanto o site ainda usa sua lista de prompts existente em cache (mostrados como prompts importados de procedência desconhecida); true a partir da primeira alteração salva.
revisionintegeropcional
A revisão do conjunto, que aumenta a cada alteração salva. Envie-a como expectedRevision, ou em If-Match no DELETE.
maxActiveintegeropcional
O máximo de prompts ativos ao mesmo tempo (16).
maxLengthintegeropcional
O comprimento máximo de um prompt, em caracteres (500).
countsobjectopcional
Quantidade de prompts ativos e pausados.
activeintegeropcional
pausedintegeropcional
itemsarray of objectopcional
Os prompts na ordem do conjunto, filtrados pelo parâmetro status.
idstringopcional
Identificador único do prompt.
textstringopcional
O texto do prompt. Em uma verificação ou entrada de histórico, o texto que essa verificação mediu.
normalizedTextstringopcional
O texto aparado, com espaços condensados e em minúsculas: a chave usada para detectar duplicados.
wordingVersionintegeropcional
A versão do texto: 1 ao ser criado, uma a mais após cada alteração de texto. Envie-a de volta como expectedWordingVersion.
statusstring (active | paused)opcional
active (medido pela próxima verificação) ou paused (mantido, mas fora das verificações).
originstring (existing | custom | generated | integration)opcional
De onde veio o prompt: existing (importado da lista de prompts anterior do site, procedência desconhecida), custom (adicionado no app), generated ou integration (adicionado pela API ou MCP).
createdViastring (ui | api | mcp | import)opcional
Como o prompt foi criado: ui, api, mcp ou import.
createdByUserIdstringopcional
A pessoa que criou o prompt, ou null quando desconhecida (prompts importados).
updatedByUserIdstringopcional
A pessoa que alterou o prompt por último, ou null quando desconhecida.
positionintegeropcional
A posição do prompt na ordem do conjunto.
createdAtstringopcional
Quando o prompt foi criado, como carimbo de data/hora ISO 8601.
updatedAtstringopcional
Quando o prompt foi alterado por último, como carimbo de data/hora ISO 8601.
deletedAtstringopcional
Quando o prompt foi removido, ou null. Prompts removidos não são listados, mas continuam nas verificações que os capturaram.
latestobjectopcional
O resultado aproveitável mais recente do texto atual, de uma verificação concluída complete, partial ou failed, ou de um texto legado importado com correspondência comprovada: state checked com at, measured e expected. Uma verificação held fica no histórico e não o atualiza. Caso contrário, state not_checked, inclusive logo após uma edição.
editedbooleanopcional
Se o texto mudou desde que o prompt foi criado.
workloadobjectopcional
Aproximadamente o que uma verificação dos prompts ativos envolve. Ler isso não custa nada, e salvar prompts não consome créditos.
activePromptsintegeropcional
Prompts ativos que a próxima verificação mediria.
enginesarray of stringopcional
Os mecanismos de IA que uma verificação consulta.
answerChecksintegeropcional
Prompts ativos × mecanismos: as respostas que uma verificação solicita. Uma contagem, não créditos.
estimatedCreditsnumberopcional
Créditos aproximados de uma verificação dos prompts ativos, pelas tarifas de créditos da sua agência. null quando a tarifa é desconhecida ou há mais de 16 prompts ativos — desconhecido, não zero. Uma estimativa, não uma cobrança.
creditsPerPromptnumberopcional
Créditos aproximados por prompt em todos os mecanismos, ou null quando desconhecidos.
approximateboolean (true)opcional
Sempre true: os números de carga são estimativas.
scheduleobjectopcional
O agendamento atual de verificações de AEO do site. Alterar prompts não o muda.
frequencystring (weekly | monthly | quarterly | never)opcional
Com que frequência as verificações são executadas: weekly, monthly, quarterly ou never.
nextRunAtstringopcional
Quando vence a próxima verificação agendada, como carimbo de data/hora ISO 8601, ou null quando a frequência é never ou as verificações ainda não começaram para este site.
activatedbooleanopcional
Se as verificações já começaram para este site (uma primeira verificação foi iniciada ou existe um relatório). Salvar prompts não as inicia.
checkInFlightbooleanopcional
Se há agora uma verificação na fila, em execução ou retida para este site. Essa verificação mantém os prompts que capturou; as alterações valem a partir da próxima.
listChangedSinceReportbooleanopcional
Se os prompts ativos diferem dos que o relatório atual mediu, de modo que o relatório ainda não reflete a lista atual.
needsReconciliationbooleanopcional
Se a lista de prompts anterior do site tem entradas malformadas ou duplicadas. Até o suporte conciliá-la, as alterações retornam 409 legacy_prompts_need_reconciliation.
noopbooleanopcional
true quando a solicitação correspondia ao que já estava salvo e nada foi salvo.
replayedbooleanopcional
true quando repete uma alteração já salva com o mesmo mutationId; a alteração não é aplicada de novo e view é a visualização atual.
createdIdsarray of stringopcional
Ids dos prompts que esta solicitação adicionou, em ordem. Vazio em outras alterações e em uma repetição.
Erros
400Falta um parâmetro obrigatório na solicitação, ou ela é inválida de outra forma.
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
404O recurso não foi encontrado, ou não pertence à sua agência.
409A solicitação entra em conflito com o estado atual do recurso — por exemplo, alterar o e-mail ou telefone de um destinatário que já recebeu uma mensagem, ou um convite de equipe que já foi aceito (ou que ainda não foi aceito).
422Falta um parâmetro obrigatório na solicitação, ou ela é inválida de outra forma.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
503O serviço está temporariamente indisponível. Siga as orientações de nova tentativa para esta operação.
post/api/v1/aeo/prompts
Sua chave de API
Corpo da solicitação*
{}

Guias que usam este recurso