Guía de la API HTTP
La API HTTP junto al SDK: llamadas puntuales y tu backend, y la captura completa por HTTP para quien captura fuera del navegador.
En esta página
- Con el SDK
- La captura completa por HTTP
- Antes de empezar
- 1. Elige un protocolo con taxonomía
- 2. Inscribe y lee el plan
- 3. Abre el stream en vivo
- 4. Fija el contexto
- 5. Envía cada step
- El formato del frame
- Envía la transcripción
- 6. Espera la interpretación
- 7. Pide otra audiencia
- Sin el evento
- Interpretación en streaming
- Tus usuarios, desde tu backend
- Qué puede fallar
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
Sección titulada «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}/statusyGET /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. La key va en tu backend como process.env.ENGINE_API_KEY, nunca en la página.
La captura completa por HTTP
Sección titulada «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.
Los comandos son bash con curl y jq, como en el quickstart. Tu contexto, tu protocolo y tus ids serán otros: la guía los lee de tu catálogo.
Antes de empezar
Sección titulada «Antes de empezar»Un token y un usuario, como en los pasos 1 y 2 del quickstart:
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/nullEngine recomienda un baseline antes de cualquier protocolo; esta guía se lo salta.
1. Elige un protocolo con taxonomía
Sección titulada «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:
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:
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
Sección titulada «2. Inscribe y lee el plan»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.
{ "mechanic": { "flowMode": "fixed", "steps": [ { "order": 1, "type": "<step type>", "media": [ { "pid": "<media pid>" } ] }, { "order": 2, "type": "<step type>" } ] }}3. Abre el stream en vivo
Sección titulada «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.
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.
4. Fija el contexto
Sección titulada «4. Fija el contexto»Envía la taxonomía antes del primer frame de la posición:
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:
{ "constellationContextId": "<your context id>", "constellationHciId": "<your target HCI id>"}Engine responde 201 y lo guarda:
{ "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
201y lo lista entaxonomyWarnings(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 quePOST /analyzeresponda. 409si la posición ya está completada o si la inscripción está retirada.
5. Envía cada step
Sección titulada «5. Envía cada step»Cada step del plan necesita sus propios lotes y su propio Final:
stepes elorderdel step, ykpnfile.orderempieza en 1 en cada step.mediaIdes elpidde 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
Finaldel último step,triggerAnalysis: truepide a Engine que interprete cuando la posición se complete. - En una mecánica con
flowMode: "free", envía tambiénmechanicComplete: trueen ese últimoFinal. - Deja unos segundos antes de cada
Final: Engine agrega el step cuando llega elFinal, y el lote justo anterior puede seguir procesándose. El SDK espera 2,5 segundos.
El formato del frame
Sección titulada «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 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 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.
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)"doneCada lote responde 202. El Final del último step tiene esta forma (sin los frames):
{ "userProtocolId": "<UP>", "protocolMechanicId": "<PM>", "step": 2, "mediaId": "<media pid>", "kpnfile": { "order": 10, "status": "Final" }, "triggerAnalysis": true, "frames": []}Envía la transcripción
Sección titulada «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, conlanguage,accuracy(null),text,list([]) yspokenMs(milisegundos con voz), ystartMsyendMscuando los sepas.sttByStep: la misma voz partida por step,[{ step, text, startMs, endMs, spokenMs }], dondestepes el order del step (el SDK mandanullpara la voz que no pudo situar en un step; si lo calculas tú, manda siempre el order) ystartMsyendMsson milisegundos desde epoch (el reloj declientTsMs) onull.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
Sección titulada «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).
for _ in $(seq 1 60); do grep -q 'event: *constellation.complete' stream.log && break; sleep 5; donekill "$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):
{ "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:
{ "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; solo en el Engine del entorno de pruebas).
7. Pide otra audiencia
Sección titulada «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.
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}'{ "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_appliedy se genera como una interpretación más, con la lectura por defecto. Usa solo las audiencias que te da Neurologyca. POST /analyzeusa la última sesión completada de la posición.
Sin el evento
Sección titulada «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.
Interpretación en streaming
Sección titulada «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
Sección titulada «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). @neurologyca/capture-server ofrece listUsers().
Qué puede fallar
Sección titulada «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:
{ "status": 404, "body": { "code": 404, "message": "Not found." } }{ "status": 404, "body": { "code": 404, "message": "No results found." } }