Synup
Créer une clé
v1Ressources/AEO/postAjouter des prompts suivis à un site web

Ajouter des prompts suivis à un site web

Ajoute des prompts à l'ensemble suivi d'un site web en tant que prompts actifs : de 1 à 50 par requête, chacun de 500 caractères au plus. Au plus 16 prompts peuvent être actifs en même temps ; une requête qui dépasserait cette limite renvoie 409 prompt_limit et n'enregistre rien. Chaque ligne est nettoyée et ses espaces regroupés. Une ligne vide ou trop longue renvoie 400 invalid_input ; une ligne qui répète un prompt existant (sans tenir compte de la casse ni des espaces) ou une autre ligne de la requête est signalée dans issues, en 409 duplicate_prompt quand tous les problèmes sont des doublons. L'enregistrement change seulement ce que mesure la prochaine vérification : il ne lance, n'achète ni ne reprogramme jamais de vérification, ne consomme aucun crédit et laisse le calendrier tel quel. Nécessite l'autorisation Manage AEO prompts — les propriétaires et les administrateurs l'ont, les autres membres seulement si elle leur a été accordée (sinon 403 forbidden) — et la gestion des prompts activée pour l'agence (sinon 403 feature_disabled). Répond 201 avec les ids des nouveaux prompts, ou 200 quand la requête rejoue une requête précédente avec le même mutationId. Une erreur inattendue renvoie 503 prompts_unavailable.

post/api/v1/aeo/prompts
aeo:write
Corps de la requête
locationIdstringobligatoire
L'id d'établissement de l'entité site web. Un site web que vous ne pouvez pas voir, ou qui n'existe pas, renvoie 404 ; un établissement physique renvoie 422 entity_type_not_supported.
textsarray of stringobligatoire
Les prompts à ajouter, un par élément : de 1 à 50 par requête, chacun de 1 à 500 caractères après nettoyage. Ils sont ajoutés comme prompts actifs après les prompts existants.
expectedRevisionintegerobligatoire
La révision de l'ensemble que vous avez lue en dernier (revision dans la vue de liste). La modification n'est appliquée que si elle correspond toujours ; sinon elle renvoie 409 prompt_set_changed avec latestRevision, pour que vous relisiez l'ensemble et décidiez.
mutationIdstringobligatoire
Votre id pour cette modification : de 8 à 100 lettres, chiffres, _ ou -. Pour DELETE, envoyez-le dans l'en-tête Idempotency-Key. Une fois une modification enregistrée sous un id, répéter la même requête renvoie replayed true et la vue actuelle sans l'appliquer une seconde fois, et réutiliser cet id pour une autre requête renvoie 409 mutation_reused. Une requête qui n'a rien changé n'enregistre aucun id : sa répétition est de nouveau évaluée par rapport à la révision actuelle (noop true, ou 409 prompt_set_changed si l'ensemble a changé entre-temps). Si vous ne savez pas si une écriture a abouti, réessayez avec le même id, ou relisez la liste et rapprochez, avant d'envoyer un nouvel id.
Réponse
dataobjectfacultatif
viewobjectfacultatif
locationIdstringfacultatif
L'id d'établissement de l'entité site web.
namestringfacultatif
Le nom du site web.
eligibleboolean (true)facultatif
Toujours true : seule une entité site web a une liste de prompts suivis.
canEditbooleanfacultatif
Indique si la personne qui a émis le jeton peut modifier cet ensemble maintenant : elle a l'autorisation Manage AEO prompts, la gestion des prompts est activée pour l'agence, et l'ancienne liste de prompts n'a pas besoin de rapprochement.
managedbooleanfacultatif
false tant que le site web utilise encore sa liste de prompts existante mise en cache (affichés comme prompts importés de provenance inconnue) ; true dès la première modification enregistrée.
revisionintegerfacultatif
La révision de l'ensemble, incrémentée à chaque modification enregistrée. Envoyez-la comme expectedRevision, ou dans If-Match pour DELETE.
maxActiveintegerfacultatif
Le nombre maximal de prompts actifs en même temps (16).
maxLengthintegerfacultatif
La longueur maximale d'un prompt, en caractères (500).
countsobjectfacultatif
Nombre de prompts actifs et en pause.
activeintegerfacultatif
pausedintegerfacultatif
itemsarray of objectfacultatif
Les prompts dans l'ordre de l'ensemble, filtrés par le paramètre status.
idstringfacultatif
Identifiant unique du prompt.
textstringfacultatif
La formulation du prompt. Dans une vérification ou une entrée d'historique, la formulation mesurée par cette vérification.
normalizedTextstringfacultatif
La formulation nettoyée, espaces regroupés et en minuscules : la clé utilisée pour détecter les doublons.
wordingVersionintegerfacultatif
La version de la formulation : 1 à la création, augmentée de un à chaque modification de formulation. Renvoyez-la comme expectedWordingVersion.
statusstring (active | paused)facultatif
active (mesuré par la prochaine vérification) ou paused (conservé mais exclu des vérifications).
originstring (existing | custom | generated | integration)facultatif
Provenance du prompt : existing (importé de l'ancienne liste de prompts du site web, provenance inconnue), custom (ajouté dans l'application), generated ou integration (ajouté via l'API ou MCP).
createdViastring (ui | api | mcp | import)facultatif
Comment le prompt a été créé : ui, api, mcp ou import.
createdByUserIdstringfacultatif
La personne qui a créé le prompt, ou null si elle est inconnue (prompts importés).
updatedByUserIdstringfacultatif
La personne qui a modifié le prompt en dernier, ou null si elle est inconnue.
positionintegerfacultatif
La place du prompt dans l'ordre de l'ensemble.
createdAtstringfacultatif
Quand le prompt a été créé, sous forme d'horodatage ISO 8601.
updatedAtstringfacultatif
Quand le prompt a été modifié en dernier, sous forme d'horodatage ISO 8601.
deletedAtstringfacultatif
Quand le prompt a été supprimé, ou null. Les prompts supprimés ne sont pas listés mais restent dans les vérifications qui les ont capturés.
latestobjectfacultatif
Le dernier résultat exploitable pour la formulation actuelle, issu d'une vérification clôturée complete, partial ou failed, ou d'une ancienne formulation importée dont la correspondance est prouvée : state checked avec at, measured et expected. Une vérification held reste dans l'historique et ne le fait pas avancer. Sinon state not_checked, y compris juste après une modification.
editedbooleanfacultatif
Indique si la formulation a changé depuis la création du prompt.
workloadobjectfacultatif
Approximativement ce qu'implique une vérification des prompts actifs. La lire ne coûte rien, et l'enregistrement de prompts ne consomme aucun crédit.
activePromptsintegerfacultatif
Prompts actifs que la prochaine vérification mesurerait.
enginesarray of stringfacultatif
Les moteurs d'IA interrogés par une vérification.
answerChecksintegerfacultatif
Prompts actifs × moteurs : les réponses demandées par une vérification. Un décompte, pas des crédits.
estimatedCreditsnumberfacultatif
Crédits approximatifs pour une vérification des prompts actifs, selon les tarifs de crédits de votre agence. null quand le tarif est inconnu ou que plus de 16 prompts sont actifs — inconnu, pas zéro. Une estimation, pas un débit.
creditsPerPromptnumberfacultatif
Crédits approximatifs par prompt sur tous les moteurs, ou null s'ils sont inconnus.
approximateboolean (true)facultatif
Toujours true : les chiffres de charge sont des estimations.
scheduleobjectfacultatif
Le calendrier actuel des vérifications AEO du site web. Modifier les prompts ne le change pas.
frequencystring (weekly | monthly | quarterly | never)facultatif
Fréquence des vérifications : weekly, monthly, quarterly ou never.
nextRunAtstringfacultatif
Quand la prochaine vérification planifiée est prévue, sous forme d'horodatage ISO 8601, ou null quand la fréquence est never ou que les vérifications n'ont pas encore commencé pour ce site web.
activatedbooleanfacultatif
Indique si les vérifications ont commencé pour ce site web (une première vérification a été lancée ou un rapport existe). L'enregistrement de prompts ne les lance pas.
checkInFlightbooleanfacultatif
Indique si une vérification est en file, en cours ou retenue pour ce site web en ce moment. Cette vérification conserve les prompts qu'elle a capturés ; les modifications s'appliquent à partir de la suivante.
listChangedSinceReportbooleanfacultatif
Indique si les prompts actifs diffèrent de ceux mesurés par le rapport actuel, de sorte que le rapport ne reflète pas encore la liste actuelle.
needsReconciliationbooleanfacultatif
Indique si l'ancienne liste de prompts du site web contient des entrées mal formées ou en double. Tant que le support ne l'a pas rapprochée, les modifications renvoient 409 legacy_prompts_need_reconciliation.
noopbooleanfacultatif
true quand la requête correspondait à ce qui était déjà enregistré et que rien n'a été enregistré.
replayedbooleanfacultatif
true quand la requête répète une modification déjà enregistrée sous le même mutationId ; la modification n'est pas appliquée de nouveau et view est la vue actuelle.
createdIdsarray of stringfacultatif
Ids des prompts ajoutés par cette requête, dans l'ordre. Vide pour les autres modifications et lors d'un rejeu.
Erreurs
400Il manque un paramètre requis à la requête, ou elle est invalide.
401Clé API manquante, invalide, expirée ou révoquée.
403La clé n'a pas la permission requise, ou n'est pas autorisée pour ce client/établissement.
404La ressource est introuvable, ou n'appartient pas à votre agence.
409La requête entre en conflit avec l'état actuel de la ressource — par exemple, modifier l'e-mail ou le téléphone d'un destinataire à qui un message a déjà été envoyé, ou une invitation d'équipe déjà acceptée (ou pas encore acceptée).
422Il manque un paramètre requis à la requête, ou elle est invalide.
429Trop de requêtes. Réessayez après le nombre de secondes indiqué dans l'en-tête Retry-After.
503Le service est temporairement indisponible. Suivez les consignes de nouvelle tentative propres à cette opération.
post/api/v1/aeo/prompts
Votre clé API
Corps de la requête*
{}

Guides qui utilisent cette ressource