APLICACIONES Y AGENTES EXTERNOS

Una API. El mismo alcance.

Genius recibe consultas estructuradas, conserva sus versiones y ejecuta el motor formal. La API usa el mismo control de acceso, cuotas y perfiles que la web. No interpreta cualquier problema en lenguaje natural, no crea modelos y no autoriza acciones sobre sistemas ajenos.

1. Creá una clave de acceso

Registrá una cuenta en la web, leé la información de privacidad y abrí Acceso API. La clave se muestra una vez y accede a los datos de esa cuenta. Guardala en un gestor de secretos o variable segura; podés revocarla desde el mismo panel.

Authorization: Bearer <CLAVE_API>
Content-Type: application/json
Accept: application/json

Usá HTTPS en instancias públicas. No incluyas la clave en una URL, un expediente, un repositorio, analítica ni logs. Los navegadores usan una cookie de sesión HttpOnly y un encabezado X-CSRF-Token para operaciones que modifican datos; un cliente con Bearer usa su clave.

2. Guardá una consulta

POST /api/cases crea un expediente. El siguiente ejemplo es sintético; ambos reconocimientos corresponden a declaraciones explícitas del consumidor. No los presupongas al actuar por otra persona.

{
  "title": "Ejemplo sintético de créditos",
  "profile": "hours",
  "consumer_type": "agent",
  "input": {
    "assignments": [
      {"id": "task1", "credit": "13/2"},
      {"id": "task2", "credit": "15/2"}
    ],
    "target": "15",
    "permission_confirmed": true,
    "scope_acknowledged": true,
    "evidence_origin": "synthetic"
  }
}

La respuesta 201 contiene case.id y su revisión. Guardar los datos no implica admitir el caso ni ejecutar el motor.

Perfil FDQ avanzado

Usá profile: "fdq" y enviá en input las siguientes claves:

{
  "query_kind": "frontier",
  "input_json": "CONTENIDO ORIGINAL DE input.json",
  "result_json": "CONTENIDO ORIGINAL DE result.json",
  "certificate_json": "CONTENIDO ORIGINAL DE certificate.json",
  "permission_confirmed": true,
  "scope_acknowledged": true,
  "evidence_origin": "user_declared"
}

El objeto input completo admite hasta 110000 bytes JSON y el cuerpo HTTP hasta 128 KiB; ese total incluye las tres cadenas y sus escapes. Las tres entradas son cadenas de texto JSON originales, no objetos reserializados. Conservá sus bytes UTF-8, saltos de línea y racionales: cambiar espacios o reordenar claves puede invalidar las referencias del certificado. La consulta debe ser frontier o selector y coincidir con la consulta y afirmación del certificado.

El verificador ejecuta el contrato recibido. Una frontera conserva un conjunto; no crea una elección. La ausencia de selector puede estar justificada bajo su norma. El certificado no demuestra que un sistema real pertenezca al modelo ni convierte una PVS formal en una probabilidad de supervivencia biológica.

Ejemplos descargables para pruebas de operación: créditos conocidos, créditos desconocidos, FDQ frontera y FDQ selector. Los documentos son sintéticos y no constituyen evidencia de campo. Para POST /api/cases, separá el profile del ejemplo y colocá el resto en input, junto con un título y tipo de consumidor.

3. Solicitá ejecución y recuperá su estado

POST /api/cases/<CASE_ID>/run
{"revision": 1}

GET /api/jobs/<JOB_ID>
GET /api/cases/<CASE_ID>

El envío devuelve 202 y un trabajo persistido. Consultá el estado con intervalos moderados. Los estados operativos son queued, running, completed, failed, cancelled e interrupted. Un trabajo terminado no implica una decisión completa o evidencia suficiente.

Si se interrumpe la conexión después de enviar una operación, recuperá primero el expediente para comprobar si el trabajo quedó registrado. No supongas que el fallo de red significa que no se creó, ni que repetir una escritura es inocuo.

POST /api/jobs/<JOB_ID>/cancel
{}

Un intento cancelado o interrumpido no prueba inviabilidad. Para corregir datos o completar desconocidos, guardá una revisión nueva con PATCH /api/cases/<CASE_ID> y un nuevo input completo; solicitá su ejecución de forma explícita.

4. Conservá el resultado con sus límites

job.result incluye la solicitud formal, el recibo response (RC01), una presentación separada y referencias de recepción. job.result_json conserva la salida JSON original como cadena para clientes que podrían redondear enteros grandes.

Conservá además quality, obligations_ref y closure. PV_UNKNOWN, PV_NOT_APPLICABLE y PV_OUTSIDE_PROFILE son estados distintos. No conviertas desconocidos en cero, puntajes de confianza o probabilidades. Las dimensiones de calidad no producen un puntaje global.

GET /api/jobs/<JOB_ID>/artifacts descarga los artefactos verificables en ZIP. GET /api/export exporta los datos de la cuenta. Las exportaciones pueden contener datos privados: aplicá los mismos controles que al almacenamiento de origen.

Otros endpoints

Creación de cuentas

Consultá GET /api/config antes del alta. Sólo con registration_open=true se admiten nuevas cuentas. El cuerpo de POST /api/register requiere usuario, contraseña, privacy_accepted: true, privacy_version igual a la versión que se mostró y adult_confirmed: true. Investigación y seguimiento son opciones separadas, desactivadas por defecto. Un cambio del aviso devuelve 409 privacy_version_changed; hay que mostrarlo de nuevo y obtener aceptación. Altas cerradas devuelven 503 registration_closed.

Errores y límites

Un error HTTP devuelve {"error":{"code":"...","message":"..."}}. No lo interpretes como resultado matemático. Respetá los límites de tamaño, cuentas, claves, expedientes y ejecución de esta instancia. Frente a un límite de cuota, evitá reintentos continuos; ante un rechazo del perfil, corregí la causa antes de volver a enviar.

La API admite consumidores externos autenticados. No expone un servidor MCP en este hito. Las interacciones y el feedback son candidatos para investigación sólo bajo las condiciones de admisión y consentimiento correspondientes; no cierran F6A ni prueban eficacia por sí mismos.