Rutas, permisos, requisitos de idempotencia y objetivos de las 18 operaciones de la API HTTP.

Llama a cada operación con POST /api/v1/<operation> y un cuerpo que sea un objeto JSON. El nombre de operación de las tablas es el sufijo exacto después de /api/v1/.

Casos de prueba

Operación	Permiso	Idempotencia	Objetivo
`test_case.list`	`autonomy:read`	Ninguna	Enumerar los casos de prueba de la organización, del más reciente al más antiguo. Filtrar por plataforma o búsqueda de nombre. Usar antes de crear un caso para reutilizar la cobertura existente.
`test_case.get`	`autonomy:read`	Ninguna	Obtener un caso de prueba con su lista completa de pasos.
`test_case.create`	`autonomy:test_cases:write`	Obligatoria	Crear un caso de prueba a partir de pasos explícitos. Los valores de entrada son `literal`, `agent` (elegido por el Agent durante la ejecución) o `environment` (valor de ejecución con nombre del entorno); se rechazan los literales con forma de credencial salvo que se trasladen explícitamente a un secreto del entorno.
`test_case.update_steps`	`autonomy:test_cases:write`	Obligatoria	Sustituir toda la lista de pasos de un caso de prueba. Requiere `confirm: true`; sin él, la respuesta describe lo que cambiaría y no se escribe nada.

Planes de prueba

Operación	Permiso	Idempotencia	Objetivo
`test_plan.list`	`autonomy:read`	Ninguna	Enumerar los planes de prueba de la organización, que son selecciones con nombre de casos de prueba.
`test_plan.get`	`autonomy:read`	Ninguna	Obtener un plan de prueba con sus casos de prueba miembros ordenados.
`test_plan.create`	`autonomy:test_plans:write`	Obligatoria	Crear un plan de prueba y, opcionalmente, sus primeros casos de prueba miembros ordenados.
`test_plan.set_members`	`autonomy:test_plans:write`	Obligatoria	Sustituir los miembros ordenados de un plan de prueba. Eliminar casos requiere `confirm: true`; sin él, la respuesta enumera los casos que se eliminarían y no se escribe nada.

Ejecuciones

Operación	Permiso	Idempotencia	Objetivo
`run.trigger`	`autonomy:runs:write`	Obligatoria	Poner ejecuciones en cola. Proporcionar exactamente uno de `testCaseId` o `testPlanId` (un plan pone en cola una ejecución por caso miembro). Usar un entorno guardado por slug u objetivos explícitos para un despliegue o artefacto nuevo. Devuelve inmediatamente; continuar con `run.get`.
`run.list`	`autonomy:read`	Ninguna	Enumerar las ejecuciones recientes, de más nueva a más antigua. Filtrar por estado, caso de prueba, entorno o rama. Comprobar aquí antes de iniciar trabajo duplicado.
`run.get`	`autonomy:read`	Ninguna	Obtener el estado de una ejecución. Enviar el `cursor` anterior y `waitMs` (≤ `25000`) para bloquear hasta que algo cambie; `timedOut: true` significa que nada cambió y no es un error. `next` es una recomendación, nunca la autoridad.
`run.evidence`	`autonomy:read`	Ninguna	Obtener la evidencia externa de una ejecución: lo que mostró el producto y lo que se esperaba en cada paso, el veredicto y el diagnóstico, acciones neutralizadas y enlaces de medios de corta duración. Nunca incluye detalles de modelo, prompt, token o runner. Filtrar con `step`.

Entornos

Operación	Permiso	Idempotencia	Objetivo
`environment.list`	`autonomy:read`	Ninguna	Enumerar entornos, objetivos de despliegue con nombre, con sus objetivos por plataforma. Se muestran los nombres de los valores de ejecución, nunca sus valores.
`environment.get`	`autonomy:read`	Ninguna	Obtener un entorno por su slug.
`environment.upsert`	`autonomy:environments:write`	Obligatoria	Crear un entorno o actualizarlo por slug. Actualizar un slug existente sobrescribe los objetivos proporcionados y requiere `confirm: true`; sin él, la respuesta describe el cambio y no se escribe nada.

Notas

Las Notes son exclusivas de HTTP y no aparecen en el catálogo de herramientas MCP.

Operación	Permiso	Idempotencia	Objetivo
`note.list`	`autonomy:read`	Ninguna	Enumerar las Notes de un entorno, de más nueva a más antigua. Filtrar por estado.
`note.create`	`autonomy:notes:write`	Obligatoria	Crear una Note en un entorno. El cuerpo es texto sin formato y cada salto de línea inicia un párrafo. Citar ejecuciones con `runIds`.
`note.comment`	`autonomy:notes:write`	Obligatoria	Añadir un comentario de texto sin formato a la actividad de una Note.

Cada mutación marcada como Obligatoria debe incluir una cadena idempotencyKey en su cuerpo JSON. Reutiliza la misma clave al reintentar la misma mutación prevista; usa una clave nueva para otra mutación. Las operaciones de lectura no usan una clave de idempotencia.

Crear un caso de prueba

Esta solicitud usa únicamente campos aceptados por test_case.create. Los objetos valueSpec distinguen un literal ordinario de un valor de entorno que se resuelve durante la ejecución.

test_case.createbash

curl --request POST "$AUTONOMY_API_BASE/api/v1/test_case.create" \
--header "Authorization: Bearer $AUTONOMY_API_KEY" \
--header "Content-Type: application/json" \
--data '{
  "idempotencyKey": "ci-test-case-checkout-smoke-v1",
  "name": "Checkout smoke",
  "description": "A customer can complete checkout.",
  "platforms": ["web"],
  "tags": ["checkout", "smoke"],
  "steps": [
    { "action": "navigate", "target": "/checkout" },
    {
      "action": "fill",
      "target": "Email",
      "valueSpec": { "kind": "literal", "text": "qa@example.com" }
    },
    {
      "action": "fill",
      "target": "Password",
      "valueSpec": { "kind": "environment", "variable": "LOGIN_PASSWORD" }
    },
    { "action": "click", "target": "Place order" }
  ]
}'

Asigna a AUTONOMY_API_BASE el valor de NEXT_PUBLIC_CONVEX_SITE_URL y guarda la clave aut_ en AUTONOMY_API_KEY.

Iniciar una ejecución

Proporciona exactamente uno de testCaseId o testPlanId. Este ejemplo apunta a una vista previa web nueva; usa environmentSlug cuando el objetivo ya esté guardado.

run.triggerbash

curl --request POST "$AUTONOMY_API_BASE/api/v1/run.trigger" \
--header "Authorization: Bearer $AUTONOMY_API_KEY" \
--header "Content-Type: application/json" \
--data '{
  "idempotencyKey": "ci-run-pr-128-checkout-smoke-9f3a2c1",
  "testCaseId": "jh7exampletestcaseid",
  "platforms": ["web"],
  "targets": {
    "web": { "baseUrl": "https://preview-128.example.com" }
  },
  "branch": "feature/checkout-copy",
  "pr": "128",
  "deployment": { "commitSha": "9f3a2c1d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b" },
  "scope": "changed",
  "changedFiles": ["src/checkout/page.tsx"]
}'

La respuesta contiene runIds y, para un plan de prueba, puede contener planGroupRunId. La activación devuelve inmediatamente; sigue cada id con run.get.

Confirmación antes de sustituir

confirm: true nunca es necesario para crear ni para run.trigger. Solo se exige cuando una operación sustituiría configuración existente:

test_case.update_steps siempre lo exige porque se sustituye toda la lista de pasos.
test_plan.set_members solo lo exige si se eliminan casos.
environment.upsert lo exige cuando se actualizaría un slug existente con los campos u objetivos proporcionados.

Sin confirmación, la API devuelve INVALID_ARGUMENT con details.confirmRequired: true y una vista previa details.wouldChange. Revísala antes de reintentar; no añadas confirm: true automáticamente.

Paginación por cursor

Cada solicitud *.list acepta limit y un cursor opaco opcionales:

Codejson

1{2  "limit": 20,3  "cursor": "<nextCursor from the previous response>"4}

El valor predeterminado de limit es 20 y debe ser un entero entre 1 y 100. Cada respuesta tiene { items, nextCursor }. Pasa nextCursor sin modificar para obtener la página siguiente; null indica que no hay más páginas. Los filtros van en el mismo cuerpo y deben mantenerse entre páginas.

Operaciones