# Guía de la API HTTP

El SDK para capturar; la API para lo puntual y tu backend. Lo habitual es combinar las dos.

Junto al SDK, la API sirve para leer resultados más tarde, sondear, el catálogo, los participantes y los contextos, las tareas de tu backend y cualquier lenguaje. La captura completa por HTTP se queda aquí, para quien captura fuera del navegador o ya tiene los frames.

## Con el SDK

Estos son los usos habituales de la API junto al SDK, cada uno con su llamada:

- Leer los resultados más tarde, desde tu backend: `GET /results/{userProtocolId}/{protocolMechanicId}`.
- Seguir una captura mientras ocurre: `GET /stream/{userProtocolId}`.
- Listar los protocolos en los que puedes inscribir personas: `GET /catalog/protocols`.
- Ver en qué punto está una persona: `GET /users/{externalId}/status` y `GET /users/{externalId}/user-protocols`.
- Leer la interpretación o pedirla de nuevo: `POST /analyze`.

Desde Node, `@neurologyca/capture-server` envuelve estas llamadas: ver [Los resultados en tu backend](/docs/es/sdk/results-backend/). La key va en tu backend como `process.env.ENGINE_API_KEY`, nunca en la página.

## La captura completa por HTTP

Úsala desde tu servidor, en cualquier lenguaje, cuando capturas fuera del navegador o ya tienes los frames. Esta guía recorre un protocolo de **uno de tus contextos con taxonomía**, del contexto a la interpretación. Para medir sin interpretación, ver [Solo medir](/docs/es/guides/measurement/).

Los comandos son `bash` con `curl` y `jq`, como en el [quickstart](/docs/es/start/quickstart/). Tu contexto, tu protocolo y tus ids serán otros: la guía los lee de tu catálogo.

## Antes de empezar

Un token y un usuario, como en los pasos 1 y 2 del quickstart:

```bash
export ENGINE="<engine base URL>"
export ENGINE_API_KEY="<your-api-key>"

TOKEN=$(curl -s -X POST "$ENGINE/token" -H "Content-Type: application/json" \
  -d "{\"apiKey\":\"$ENGINE_API_KEY\"}" | jq -r .token)
EXT="guide-$(date +%s)"
curl -s -X POST "$ENGINE/users" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"externalId\":\"$EXT\",\"name\":\"guide-user\"}" > /dev/null
```

Engine recomienda un [baseline](/docs/es/concepts/baseline/) antes de cualquier protocolo; esta guía se lo salta.

## 1. Elige un protocolo con taxonomía

Cada protocolo pertenece a un **grupo**, y el grupo lleva la taxonomía que necesita la interpretación: el id del contexto y, si lo hay, el indicador objetivo. Lista los grupos de tus contextos que la tienen y tus protocolos publicados:

```bash
curl -s "$ENGINE/catalog/protocol_group" -H "Authorization: Bearer $TOKEN" \
  | jq '.[] | select(.constellationContextId != null) | {pid, name, constellationContextId, targetConstellationHciId}'
curl -s "$ENGINE/catalog/protocols" -H "Authorization: Bearer $TOKEN" \
  | jq '.[] | select(.status == "published") | {pid, name, protocolGroupPid}'
```

Elige un protocolo cuyo `protocolGroupPid` sea uno de esos grupos y guarda la taxonomía de su grupo:

```bash
PROTOCOL="<pid of a published protocol of your context>"
GROUP=$(curl -s "$ENGINE/catalog/protocols" -H "Authorization: Bearer $TOKEN" \
  | jq -r --arg p "$PROTOCOL" '.[] | select(.pid == $p) | .protocolGroupPid')
TAXONOMY=$(curl -s "$ENGINE/catalog/protocol_group" -H "Authorization: Bearer $TOKEN" \
  | jq -c --arg g "$GROUP" '.[] | select(.pid == $g)
      | {constellationContextId, constellationHciId: .targetConstellationHciId} | with_entries(select(.value != null))')
echo "$TAXONOMY"
```

Algunos contextos definen además **subcontextos** (`taxonomy.subcontexts` en `GET /catalog/contexts`). Qué subcontexto usa cada mecánica forma parte de la guía de tu contexto; añádelo como `subcontextId`. Es opcional: sin él, Engine usa el subcontexto de la mecánica (`constellationSubcontextId` en el catálogo y en el guion) y, si la mecánica no declara ninguno, el subcontexto por defecto del contexto; si mandas uno, gana el tuyo. Uno mal escrito cae al de por defecto sin dar error. Hoy ninguna mecánica declara aún el suyo.

## 2. Inscribe y lee el plan

```bash
UP=$(curl -s -X POST "$ENGINE/user-protocols" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"user\":\"$EXT\",\"protocol\":\"$PROTOCOL\"}" | jq -r .userProtocolId)
PM=$(curl -s "$ENGINE/user-protocols/$UP" -H "Authorization: Bearer $TOKEN" \
  | jq -r .nextProtocolMechanic.protocolMechanicId)
curl -s "$ENGINE/user-protocols/$UP/mechanics/$PM" -H "Authorization: Bearer $TOKEN" \
  | jq '.mechanic | {flowMode, steps: [.steps[] | {order, type, media: [.media[]?.pid]}]}'
```

El plan lista los steps de la posición en orden, con sus medias: lo que la persona ve u oye en cada step.

```json
{
  "mechanic": {
    "flowMode": "fixed",
    "steps": [
      {
        "order": 1,
        "type": "<step type>",
        "media": [
          {
            "pid": "<media pid>"
          }
        ]
      },
      {
        "order": 2,
        "type": "<step type>"
      }
    ]
  }
}
```

## 3. Abre el stream en vivo

Abre el stream **antes** del primer lote y mantenlo abierto: te dice cuándo está lista la interpretación.

```bash
curl -sN "$ENGINE/stream/$UP" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: text/event-stream" > stream.log &
STREAM=$!
```

El primer evento es `connected`; cada 30 segundos llega un comentario `: ping`. Ver [HCIs y resultados](/docs/es/concepts/results/).

## 4. Fija el contexto

Envía la taxonomía **antes del primer frame** de la posición:

```bash
curl -s -X POST "$ENGINE/user-protocols/$UP/$PM/context" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "$TAXONOMY" | jq '{contextStored, taxonomyWarnings}'
```

El cuerpo que envías tiene esta forma:

```json
{
  "constellationContextId": "<your context id>",
  "constellationHciId": "<your target HCI id>"
}
```

Engine responde `201` y lo guarda:

```json
{
  "status": 201,
  "body": {
    "contextStored": true,
    "constellationContextId": "<your-constellationContext-id>",
    "constellationHciId": "<your-constellationHci-id>",
    "subcontextId": null,
    "situationId": null
  }
}
```

- Los campos que omites en una llamada posterior conservan su valor anterior: no se pueden vaciar.
- Un id que Engine no reconoce **no** se rechaza hoy: la respuesta sigue siendo `201` y lo lista en `taxonomyWarnings` (`field`, `value`, `code`, `message`). Lee esa lista. Engine comprueba los ids contra su copia local de la taxonomía, que en el Engine del entorno de pruebas se refresca al arrancar y cada 6 horas y aun así puede ir con retraso: un aviso sobre los ids que te da tu kit no frena el análisis, y lo que confirma que el contexto funciona es que `POST /analyze` responda.
- `409` si la posición ya está completada o si la inscripción está retirada.

## 5. Envía cada step

Cada step del plan necesita sus propios lotes y su propio `Final`:

- `step` es el `order` del step, y `kpnfile.order` empieza en 1 **en cada step**.
- `mediaId` es el `pid` de la media que mostraste, en todos los lotes de ese step. Con una sola media, Engine la resuelve; con varias, la interpretación necesita saber cuál vio la persona.
- En el `Final` del **último** step, `triggerAnalysis: true` pide a Engine que interprete cuando la posición se complete.
- En una mecánica con `flowMode: "free"`, envía también `mechanicComplete: true` en ese último `Final`.
- Deja unos segundos antes de cada `Final`: Engine agrega el step cuando llega el `Final`, y el lote justo anterior puede seguir procesándose. El SDK espera 2,5 segundos.

### El formato del frame

Cada elemento de `frames` describe un frame de vídeo tal como lo da MediaPipe FaceLandmarker. El SDK lo calcula por ti; la [captura de ejemplo](/docs/samples/sample-capture.json) es uno válido. Si calculas tus propios frames, ajústate a esto:

| Campo | Qué lleva |
| --- | --- |
| `clientTsMs` | Cuándo se capturó el frame, en milisegundos desde epoch, creciente (unos 33 ms entre frames a 30 fps) |
| `landmarks` | 478 puntos `[x, y, z]`: los 468 de la cara y los 10 del iris (FaceLandmarker con iris). `x` e `y` normalizados de 0 a 1 sobre la imagen |
| `blendshapes` | Las 52 categorías de FaceLandmarker, en su orden: `_neutral` en el índice 0 y después los nombres de ARKit (`jawOpen` 25, `mouthSmileLeft` 44, `mouthSmileRight` 45), sin `tongueOut`. Desde un diccionario de ARKit (iOS), pon cada valor en su índice de MediaPipe |
| `headPose` | `pitch`, `yaw` y `roll` en radianes |
| `featuresMeta` | Sin él, ese frame no tiene valencia ni arousal. Las claves de la muestra: `space: "frame"`, `z: "mediapipe_width"`, `image_width`, `image_height` (píxeles) y `client_ts_ms` (el `clientTsMs` del frame) |

Un frame sin cara sale del codec con `landmarks: []` y `blendshapes: []`; el SDK no lo envía (descarta todo frame sin pose de la cabeza), y tú tampoco deberías. Se esperan 478 (468 de la cara + 10 del iris). Con 468, medido el 9-ago-2026, Engine aceptó todos los lotes y la sesión no se cerró nunca; un frame sin cara (`landmarks: []`) no está medido.

Esta guía reutiliza la [captura de ejemplo](/docs/samples/sample-capture.json) del quickstart en cada step (descárgala desde tu navegador en esta carpeta). Es **sintética** y sin voz, así que la interpretación que obtienes no tiene significado: enseña el flujo, no una lectura.

```bash
send_step() {  # $1 = step order, $2 = media pid or "", $3 = true on the last step
  LAST=$(jq 'length' sample-capture.json); i=0
  jq -c '.[]' sample-capture.json | while read -r packet; do
    i=$((i + 1)); [ "$i" -eq "$LAST" ] && sleep 3
    echo "$packet" | jq --arg up "$UP" --arg pm "$PM" --argjson step "$1" --arg media "$2" --argjson last "$3" \
      '. + {userProtocolId: $up, protocolMechanicId: $pm, step: $step}
         + (if $media != "" then {mediaId: $media} else {} end)
         + (if $last and .kpnfile.status == "Final" then {triggerAnalysis: true} else {} end)' \
    | curl -s -o /dev/null -w "step $1: %{http_code}\n" \
      -X POST "$ENGINE/process-kpn-emo" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      --data-binary @-
  done
}

STEPS=$(curl -s "$ENGINE/user-protocols/$UP/mechanics/$PM" \
  -H "Authorization: Bearer $TOKEN" \
  | jq -c '[.mechanic.steps[] | {order, media: (.media[0].pid // "")}]')
N=$(echo "$STEPS" | jq 'length')
for k in $(seq 0 $((N - 1))); do
  ORDER=$(echo "$STEPS" | jq ".[$k].order"); MEDIA=$(echo "$STEPS" | jq -r ".[$k].media")
  send_step "$ORDER" "$MEDIA" "$([ "$k" -eq $((N - 1)) ] && echo true || echo false)"
done
```

Cada lote responde `202`. El `Final` del último step tiene esta forma (sin los frames):

```json
{
  "userProtocolId": "<UP>",
  "protocolMechanicId": "<PM>",
  "step": 2,
  "mediaId": "<media pid>",
  "kpnfile": {
    "order": 10,
    "status": "Final"
  },
  "triggerAnalysis": true,
  "frames": []
}
```

### Envía la transcripción

Si transcribes la sesión, envía el texto una vez, como claves de primer nivel del `Final` del último step, junto a `triggerAnalysis` (el SDK hace lo mismo):

- `speech`: la sesión entera, con `language`, `accuracy` (`null`), `text`, `list` (`[]`) y `spokenMs` (milisegundos con voz), y `startMs` y `endMs` cuando los sepas.
- `sttByStep`: la misma voz partida por step, `[{ step, text, startMs, endMs, spokenMs }]`, donde `step` es el order del step (el SDK manda `null` para la voz que no pudo situar en un step; si lo calculas tú, manda siempre el order) y `startMs` y `endMs` son milisegundos desde epoch (el reloj de `clientTsMs`) o `null`.
- `sttCutBy`, solo si la transcripción se cortó.

El spec público aún no tipa `sttByStep`, y su esquema de `speech` solo lista `language`, `accuracy`, `text` y `list`: esta es la forma que manda el SDK y Engine acepta, y Engine la guarda tal cual. El idioma de la interpretación es el `narrative.language` de la persona, no el de la transcripción.

## 6. Espera la interpretación

Cuando la posición se completa y la interpretación queda guardada, el stream emite `constellation.complete`. Úsalo como señal y luego lee la interpretación con `POST /analyze`. Una posición que pidió la interpretación normalmente no envía `results.ready`: ese evento es para las posiciones sin interpretación que esperar (ver [Eventos en vivo](/docs/es/concepts/results/#eventos-en-vivo)).

```bash
for _ in $(seq 1 60); do grep -q 'event: *constellation.complete' stream.log && break; sleep 5; done
kill "$STREAM"
curl -s -X POST "$ENGINE/analyze" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"userProtocolId\":\"$UP\",\"protocolMechanicId\":\"$PM\"}" \
  | jq '{from_cache, audience_applied, headline: .structured_data.headline}'
```

Con un protocolo de seis steps que pide la interpretación en su último `Final`, el stream trajo esto (`resultsReady` lista los eventos `results.ready`: ninguno, como corresponde a una posición que pide la interpretación):

```json
{
  "events": [
    "connected",
    "hci.warning",
    "constellation.complete"
  ],
  "constellationComplete": true,
  "steps": 6,
  "resultsReady": []
}
```

`hci.warning` es un aviso sobre un indicador que tu contexto incluye: llega una vez por lote y no es una alerta; DevLab no enseña el nivel que lo dispara (`threshold`), así que no construyas sobre él; que se envíe depende del entorno, así que no lo esperes. La lista de arriba muestra cada nombre de evento una sola vez.

`POST /analyze` responde entonces con la interpretación guardada (`from_cache: true`). `audience_applied` es la audiencia que pediste (en la petición o en el perfil del usuario), o `null` si no hay ninguna; no prueba que la lectura cambiara. La forma, con los textos sustituidos:

```json
{
  "status": 200,
  "body": {
    "interpretation": "<text>",
    "from_cache": true,
    "audience_applied": "<audience>",
    "structured_data": {
      "headline": "<text>",
      "sections": [
        {
          "title": "<text>",
          "body": "<text>"
        }
      ]
    },
    "metadata": {
      "status": "complete"
    }
  }
}
```

Los indicadores están en `GET /results/{userProtocolId}/{protocolMechanicId}`, una entrada por step, como en el quickstart. La misma respuesta lleva `speech`, la pregunta y lo dicho en cada step, cuando los hay ([`speech`](/docs/es/concepts/results/#speech); solo en el Engine del entorno de pruebas).

## 7. Pide otra audiencia

La interpretación se escribe para una **audiencia**. Sin `audience`, Engine usa la del perfil del usuario (`audience` en `PATCH /users/{external_id}`) o la de por defecto. Neurologyca te da las audiencias disponibles en tus contextos: el kit lista las de cada contexto y, cuando Neurologyca la publica, marca la de por defecto.

```bash
curl -s -X POST "$ENGINE/analyze" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"userProtocolId\":\"$UP\",\"protocolMechanicId\":\"$PM\",\"audience\":\"<audience>\"}" \
  | jq '{from_cache, audience_applied}'
```

```json
{ "userProtocolId": "<UP>", "protocolMechanicId": "<PM>", "audience": "<audience>" }
```

- Cada audiencia se genera una vez por sesión y después se sirve desde la caché: la primera petición de una audiencia tarda lo que una interpretación.
- Engine no comprueba la etiqueta: una audiencia que no conoce se acepta **sin error**, se devuelve en `audience_applied` y se genera como una interpretación más, con la lectura por defecto. Usa solo las audiencias que te da Neurologyca.
- `POST /analyze` usa la última sesión completada de la posición.

## Sin el evento

Si no puedes mantener un stream abierto, no envíes `triggerAnalysis` y llama a `POST /analyze` cuando los resultados estén listos. Espera a la interpretación, que puede tardar unos dos minutos, así que da a tu cliente HTTP un timeout largo: también se ha visto una llamada bloqueante acabar en `504` mientras la interpretación aún se generaba. Ver [Timeouts](/docs/es/guides/timeouts/).

## Interpretación en streaming

`POST /analyze/stream` recibe el mismo cuerpo y responde con un stream de eventos de progreso que termina con la interpretación. Siempre genera una interpretación nueva y Engine no la guarda. Los nombres de los eventos son del servicio de interpretación y **no** forman parte del contrato: úsalo para enseñar progreso, y `POST /analyze` para guardar el resultado.

## Tus usuarios, desde tu backend

Dos lecturas ayudan a tu backend a seguir a las personas que creó. Las dos van con tu key, nunca desde el navegador.

| Ruta | Devuelve |
| --- | --- |
| `GET /users` | Las personas de tu organización, de la más reciente a la más antigua, con quién registró a cada una, su baseline y cuántos protocolos tiene. Filtros opcionales: `externalId`, `developerName`, `role`, `hasBaseline`, `baselineIsValid` y `limit` |
| `GET /users/{external_id}/status` | Cada protocolo de esa persona (salvo el de baseline) con su estado, calculado al pedirlo (`capturing`, `awaiting_processing`, `completed`, `abandoned`…), su progreso y las sesiones que faltan |

Una key `read_all` también lista a todas las personas de la organización con `GET /users` (ver [Modelo de acceso](/docs/es/access/model/)). `@neurologyca/capture-server` ofrece `listUsers()`.

## Qué puede fallar

| Qué ves | Por qué |
| --- | --- |
| `201` con `taxonomyWarnings` | Un id que Engine no reconoce; hoy avisa en lugar de rechazar |
| `202` en cada lote, pero la posición nunca se completa | Un step sin su `Final` o una mecánica de flujo libre sin `mechanicComplete` |
| `400` con `KPN-EMO-MISSING-PACKETS` en un `Final` | Un hueco en `kpnfile.order`: reenvía los lotes de `missingOrders` y después el `Final` |
| Un agregado al que le faltan los últimos lotes | El `Final` llegó justo después del lote anterior: deja unos segundos |
| `400` que menciona la media | Un `mediaId` que no existe |
| Una interpretación que no encaja con la audiencia que pediste | Engine acepta sin error una etiqueta que no conoce; usa las audiencias que te da Neurologyca |
| `404 { "code": 404, "message": "Not found." }` en `/analyze` | Un id que no existe o no es tuyo |
| `404 { "code": 404, "message": "No results found." }` en `/analyze` | La posición aún no tiene una captura completada |
| `409` con `reason: PROTOCOL_NOT_ANALYSED` en `/analyze` | Un protocolo que no se interpreta, como Measurement: lee sus indicadores con `GET /results` |
| `504` en un `/analyze` bloqueante | La llamada esperó demasiado a la interpretación; usa el evento o vuelve a pedirla más tarde |

Los dos `404`, tal como los envía Engine:

```json
{ "status": 404, "body": { "code": 404, "message": "Not found." } }
```

```json
{ "status": 404, "body": { "code": 404, "message": "No results found." } }
```

> La interpretación de cada contexto la diseña Neurologyca contigo: qué taxonomía, subcontextos y audiencias aplican forma parte de la guía de tu contexto.
