Ir al contenido
DevLab

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.

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. La key va en tu backend como process.env.ENGINE_API_KEY, nunca en la página.

Ú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.

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

Shell
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 antes de cualquier protocolo; esta guía se lo salta.

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:

Shell
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:

Shell
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.

Shell
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>"
}
]
}
}

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

Shell
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.

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

Shell
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.

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.

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.

Shell
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": []
}

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.

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).

Shell
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; solo en el Engine del entorno de pruebas).

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.

Shell
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.

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.

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.

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é 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." } }