v1Recursos/AEO/postAñadir prompts seguidos a un sitio web

Añadir prompts seguidos a un sitio web

Añade prompts al conjunto seguido de un sitio web como prompts activos: de 1 a 50 por solicitud, cada uno de hasta 500 caracteres. Como máximo puede haber 16 prompts activos a la vez; una solicitud que superaría ese límite devuelve 409 prompt_limit y no guarda nada. Cada línea se recorta y sus espacios se condensan. Una línea vacía o demasiado larga devuelve 400 invalid_input; una línea que repite un prompt actual (sin distinguir mayúsculas ni espacios) u otra línea de la solicitud se indica en issues, como 409 duplicate_prompt cuando todos los problemas son duplicados. Guardar solo cambia lo que mide la próxima comprobación: nunca inicia, compra ni reprograma una comprobación, no consume créditos y deja la programación como está. Requiere el permiso Manage AEO prompts — los propietarios y administradores lo tienen, los demás miembros solo si se les concedió (si no, 403 forbidden) — y la gestión de prompts activada para la agencia (si no, 403 feature_disabled). Responde 201 con los ids de los nuevos prompts, o 200 cuando repite una solicitud anterior con el mismo mutationId. Un fallo inesperado devuelve 503 prompts_unavailable.

post/api/v1/aeo/prompts
aeo:write
Cuerpo de la solicitud
locationIdstringobligatorio
El id de ubicación de la entidad de sitio web. Un sitio web que no puedes ver, o que no existe, devuelve 404; una ubicación física devuelve 422 entity_type_not_supported.
textsarray of stringobligatorio
Los prompts que se añaden, uno por elemento: de 1 a 50 por solicitud, cada uno de 1 a 500 caracteres tras recortarlo. Se añaden como prompts activos después de los existentes.
expectedRevisionintegerobligatorio
La revisión del conjunto que leíste por última vez (revision en la vista de lista). El cambio solo se aplica si sigue coincidiendo; si no, devuelve 409 prompt_set_changed con latestRevision, para que vuelvas a leer el conjunto y decidas.
mutationIdstringobligatorio
Tu id para este cambio: de 8 a 100 letras, dígitos, _ o -. En DELETE, envíalo como encabezado Idempotency-Key. Una vez guardado un cambio con un id, repetir la misma solicitud devuelve replayed true y la vista actual sin volver a aplicarlo, y reutilizar ese id para otra solicitud devuelve 409 mutation_reused. Una solicitud que no cambió nada no guarda ningún id: al repetirla se decide de nuevo contra la revisión actual (noop true, o 409 prompt_set_changed si el conjunto cambió entretanto). Si no sabes si una escritura se aplicó, repítela con el mismo id, o lee la lista y concilia, antes de enviar un id nuevo.
Respuesta
dataobjectopcional
viewobjectopcional
locationIdstringopcional
El id de ubicación de la entidad de sitio web.
namestringopcional
El nombre del sitio web.
eligibleboolean (true)opcional
Siempre true: solo una entidad de sitio web tiene una lista de prompts seguidos.
canEditbooleanopcional
Si la persona que emitió el token puede cambiar este conjunto ahora: tiene el permiso Manage AEO prompts, la gestión de prompts está activada para la agencia y la lista de prompts anterior no necesita conciliación.
managedbooleanopcional
false mientras el sitio web siga usando su lista de prompts existente en caché (mostrados como prompts importados de procedencia desconocida); true desde el primer cambio guardado.
revisionintegeropcional
La revisión del conjunto, que aumenta con cada cambio guardado. Envíala como expectedRevision, o en If-Match en DELETE.
maxActiveintegeropcional
El máximo de prompts activos a la vez (16).
maxLengthintegeropcional
La longitud máxima de un prompt, en caracteres (500).
countsobjectopcional
Cantidad de prompts activos y en pausa.
activeintegeropcional
pausedintegeropcional
itemsarray of objectopcional
Los prompts en el orden del conjunto, filtrados por el parámetro status.
idstringopcional
Identificador único del prompt.
textstringopcional
La redacción del prompt. En una comprobación o una entrada del historial, la redacción que midió esa comprobación.
normalizedTextstringopcional
La redacción recortada, con los espacios condensados y en minúsculas: la clave para detectar duplicados.
wordingVersionintegeropcional
La versión de la redacción: 1 al crearse, una más tras cada cambio de redacción. Devuélvela como expectedWordingVersion.
statusstring (active | paused)opcional
active (lo mide la próxima comprobación) o paused (se conserva, pero queda fuera de las comprobaciones).
originstring (existing | custom | generated | integration)opcional
De dónde viene el prompt: existing (importado de la lista de prompts anterior del sitio web, procedencia desconocida), custom (añadido en la app), generated o integration (añadido mediante la API o MCP).
createdViastring (ui | api | mcp | import)opcional
Cómo se creó el prompt: ui, api, mcp o import.
createdByUserIdstringopcional
La persona que creó el prompt, o null si se desconoce (prompts importados).
updatedByUserIdstringopcional
La persona que cambió el prompt por última vez, o null si se desconoce.
positionintegeropcional
El lugar del prompt en el orden del conjunto.
createdAtstringopcional
Cuándo se creó el prompt, como marca de tiempo ISO 8601.
updatedAtstringopcional
Cuándo se cambió el prompt por última vez, como marca de tiempo ISO 8601.
deletedAtstringopcional
Cuándo se eliminó el prompt, o null. Los prompts eliminados no se listan, pero siguen en las comprobaciones que los capturaron.
latestobjectopcional
El resultado utilizable más reciente de la redacción actual, de una comprobación cerrada complete, partial o failed, o de una redacción heredada importada que coincide de forma demostrable: state checked con at, measured y expected. Una comprobación held queda en el historial y no lo actualiza. Si no, state not_checked, también justo después de una edición.
editedbooleanopcional
Si la redacción cambió desde que se creó el prompt.
workloadobjectopcional
Aproximadamente lo que implica una comprobación de los prompts activos. Leerlo no cuesta nada, y guardar prompts no consume créditos.
activePromptsintegeropcional
Prompts activos que mediría la próxima comprobación.
enginesarray of stringopcional
Los motores de IA que consulta una comprobación.
answerChecksintegeropcional
Prompts activos × motores: las respuestas que solicita una comprobación. Un recuento, no créditos.
estimatedCreditsnumberopcional
Créditos aproximados de una comprobación de los prompts activos, según las tarifas de créditos de tu agencia. null cuando la tarifa se desconoce o hay más de 16 prompts activos — desconocido, no cero. Una estimación, no un cargo.
creditsPerPromptnumberopcional
Créditos aproximados por prompt en todos los motores, o null si se desconocen.
approximateboolean (true)opcional
Siempre true: las cifras de carga son estimaciones.
scheduleobjectopcional
La programación actual de comprobaciones de AEO del sitio web. Cambiar prompts no la modifica.
frequencystring (weekly | monthly | quarterly | never)opcional
Con qué frecuencia se ejecutan las comprobaciones: weekly, monthly, quarterly o never.
nextRunAtstringopcional
Cuándo toca la próxima comprobación programada, como marca de tiempo ISO 8601, o null cuando la frecuencia es never o las comprobaciones aún no han empezado para este sitio web.
activatedbooleanopcional
Si las comprobaciones ya empezaron para este sitio web (se inició una primera comprobación o existe un informe). Guardar prompts no las inicia.
checkInFlightbooleanopcional
Si hay ahora una comprobación en cola, en ejecución o retenida para este sitio web. Esa comprobación conserva los prompts que capturó; los cambios se aplican desde la siguiente.
listChangedSinceReportbooleanopcional
Si los prompts activos difieren de los que midió el informe actual, de modo que el informe aún no refleja la lista actual.
needsReconciliationbooleanopcional
Si la lista de prompts anterior del sitio web tiene entradas mal formadas o duplicadas. Hasta que soporte la concilie, los cambios devuelven 409 legacy_prompts_need_reconciliation.
noopbooleanopcional
true cuando la solicitud coincidía con lo ya guardado y no se guardó nada.
replayedbooleanopcional
true cuando repite un cambio ya guardado con el mismo mutationId; el cambio no se vuelve a aplicar y view es la vista actual.
createdIdsarray of stringopcional
Ids de los prompts que añadió esta solicitud, en orden. Vacío en otros cambios y en una repetición.
Errores
400A la solicitud le falta un parámetro obligatorio o es inválida de otra forma.
401La clave de API falta, es inválida, expiró o fue revocada.
403A la clave le falta el permiso requerido, o no está autorizada para este cliente/ubicación.
404El recurso no se encontró, o no pertenece a su agencia.
409La solicitud entra en conflicto con el estado actual del recurso — por ejemplo, cambiar el correo electrónico o el teléfono de un destinatario al que ya se le ha enviado un mensaje, o una invitación de equipo que ya fue aceptada (o que aún no ha sido aceptada).
422A la solicitud le falta un parámetro obligatorio o es inválida de otra forma.
429Demasiadas solicitudes. Reintente tras el número de segundos indicado en el encabezado Retry-After.
503El servicio no está disponible temporalmente. Siga las indicaciones de reintento para esta operación.
post/api/v1/aeo/prompts
Su clave de API
Cuerpo de la solicitud*
{}

Guías que usan este recurso