Para plataformas e integradores

Si gestionas una plataforma, un mercado o una herramienta de moderación y quieres comprobar si un avatar tiene ficha en THB, o mostrar una señal «registrado/verificado» junto a un contenido, esta página es el mapa de lo que puedes construir hoy.

Toda la superficie es un único endpoint abierto: GET /api/v0/records/<slug>.json. Sin clave de API, sin cuenta, con CORS activado para llamarlo directo desde el navegador. El contrato completo, campos, cabeceras de respuesta y cuerpos de error, está documentado una sola vez, en API pública; esta página no lo repite.

Una cosa que conviene prever antes de construir: el endpoint solo sirve fichas verificadas, y la verificación de identidad todavía no está abierta, así que hoy cualquier slug responde 404 {"error":"not_found"}. Es el registro funcionando como está diseñado, no una caída: una ficha gratuita es un registro, se queda privada, y solo la verificación la hace pública. Puedes montar la integración ya, contando con que el primer 200 OK llegará cuando se abran las verificaciones.

Nivel	Qué puedes inferir
Ninguna ficha encontrada	O nadie ha registrado ese avatar en THB, o su dueño lo registró en privado y nunca lo verificó. La API devuelve el mismo 404 en ambos casos, a propósito, así que no puedes usar «no encontrado» como una señal negativa sobre el contenido en sí.
Verificado	Un humano real e identificado declaró responsabilidad sobre este avatar y pasó una comprobación de identidad. Es una señal positiva de responsabilidad, no una calificación de seguridad de contenido, y no dice nada sobre si el contenido en sí es apropiado para tu plataforma.

En resumen: trata una consulta a THB como una entrada más, «¿hay una persona responsable e identificada detrás de esto?», junto a la revisión de contenido que ya haga tu propia plataforma, no como un sustituto de ella.

Si muestras un aviso tipo «Comprobado con TheHumanBehind» junto a un contenido, enlázalo directo a la página de la ficha en /r/<slug> en lugar de mostrar solo una insignia estática. Así tus propios usuarios pueden verificar la ficha por su cuenta en lugar de fiarse a ciegas de tu integración, el mismo principio detrás de Comprobar un sello que ves por ahí.

Las respuestas llevan un access-control-allow-origin: * abierto y se cachean cinco minutos en el edge. Es suficiente para una consulta lanzada por pieza de contenido o por revisión de moderación. No está pensado para rastrear todo el registro: por favor, no construyas un raspador masivo contra el endpoint de una sola ficha.

No hay endpoint de listado ni de búsqueda en el contrato actual v0, solo consultas de una ficha cada vez. Si tu integración necesita acceso masivo, un webhook o un endpoint de listado/búsqueda, ponte en contacto, es exactamente el tipo de necesidad que un futuro v1 está pensado para cubrir, y v0 seguirá funcionando sin cambios cuando llegue.

Todo lo anterior va de CONSULTAR la ficha de otro. Si lo que necesitas es lo contrario, registrar y actualizar fichas tuyas desde tu propio sistema en vez de por el formulario, eso es otra puerta y necesita una clave.

Una empresa que lanza cincuenta agentes no debería tener que rellenar cincuenta formularios. Crea una clave de servicio en tu panel, en Claves de API, y úsala como credencial portadora contra platform.thehumanbehind.com/api/manage/v1/.

• La clave se enseña una sola vez, al crearla. Guardamos solo su SHA-256, así que no podemos volver a enseñártela: si la pierdes, creas otra y revocas la anterior.
• Viaja en la cabecera Authorization, nunca en la dirección. Una clave en la URL acaba en los registros de acceso, en las cabeceras Referer y en el historial del navegador.
• Llega a tus fichas y a nada más: ni al panel, ni a la facturación, ni a datos de otra cuenta. Pedir una ficha que no es tuya responde exactamente el mismo 404 que una que no existe.
• Es una credencial portadora: quien la tenga, eres tú. No hay firma de la petición ni ventana temporal. Trátala como una contraseña, guárdala en tu servidor y revócala desde el panel en cuanto sospeches de una fuga. La revocación es inmediata.
• 60 peticiones por minuto por clave.
• Tiene los permisos que le des al crearla, y no se pueden ampliar después. Eliges entre solo leer (consultar tus fichas y el estado de sus sellos) y leer y escribir (además, registrar y editar), y aparte puedes marcar leer el texto de las instrucciones, que va suelto porque el skill.md de tus agentes es propiedad tuya y una clave que se filtre no debería poder sacarlo. Una clave sin ese permiso ve la huella y la fecha de cada versión, nunca el texto.

La cabecera Idempotency-Key es obligatoria al crear, y es lo que hace seguro repetir un despliegue: la misma clave con el mismo cuerpo devuelve la misma ficha en vez de registrar una segunda. Reutiliza el mismo valor solo con el mismo cuerpo; la misma clave con un cuerpo distinto responde 409 idempotency_key_reuse.

curl -X POST https://platform.thehumanbehind.com/api/manage/v1/records \
  -H "Authorization: Bearer thb_sk_..." \
  -H "Idempotency-Key: despliegue-2026-08-11-agente-01" \
  -H "Content-Type: application/json" \
  -d '{"avatarName":"Atlas",
       "type":"agent",
       "scope":"general",
       "responsibleName":"Nombre Apellido",
       "declaration":true}'

El "declaration": true no es relleno. Es la misma declaración de responsabilidad que una persona acepta con la casilla del formulario: estás afirmando que hay un humano real e identificable que responde por esa ficha. El servidor no la firma por ti, así que una petición sin ella responde 400 invalid_form.

curl -X PUT https://platform.thehumanbehind.com/api/manage/v1/records/<id>/instructions \
  -H "Authorization: Bearer thb_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"instructions":"# Atlas\n..."}'

Cada escritura que cambia el texto de verdad archiva el anterior, íntegro, con su huella y su fecha. Volver a escribir el mismo texto no cambia nada y responde created: false con la versión vigente, así que un despliegue que corre dos veces no inventa una versión.

Un GET en la misma dirección devuelve el histórico: versión, huella y fecha, paginado con ?limit y ?offset (la respuesta trae has_more y next_offset). El TEXTO no viene nunca ahí.

Para el texto se pide una versión concreta, con una clave que lleve el permiso de instrucciones:

curl "https://platform.thehumanbehind.com/api/manage/v1/records/<id>/instructions?include=text&version=3" \
  -H "Authorization: Bearer thb_sk_..."

Sin version responde 400 version_required, y sin ese permiso responde el mismo 401 que una clave desconocida. No hay forma de pedirlas todas de una vez, y es a propósito: unas instrucciones son propiedad intelectual de quien las escribió, así que enseñarlas es una decisión, no el estado por defecto, y vaciarlas de golpe no es algo que deba caber en una petición.

Petición	Qué hace
GET /api/manage/v1/whoami	Comprueba la clave y dice sus permisos, cuántas fichas tiene la cuenta y su techo. Empieza por aquí.
GET /api/manage/v1/records	Lista tus fichas, paginadas con ?limit y ?cursor. El cursor que devuelve (next_cursor) es opaco: reenvíalo tal cual, no lo construyas tú.
GET y PATCH en /api/manage/v1/records/<id>	Consulta o edita una tuya.

Los errores son estables: 400 (invalid_json, invalid_form, idempotency_key_required, reserved_name, immutable_field), 401 unauthorized (el mismo cuerpo para una clave ausente, mal formada, desconocida, revocada o caducada, y para una sin el permiso adecuado), 404 not_found, 409 (idempotency_key_reuse, idempotency_in_flight, verified_identity_locked, constraint_violation, record_removed), 413 too_large, 429 (rate_limited, quota_exceeded, lifetime_quota_exceeded), 500 server_error.

Tres merecen una frase, porque son los que paran un bucle y no una petición suelta. immutable_field es un PATCH que toca algo que no cambia nunca (el número, la dirección, la fecha de registro). record_removed es una escritura contra una ficha retirada: la constancia se conserva, la ficha ya no admite cambios. Y lifetime_quota_exceeded no es el límite por minuto, sino el techo de fichas que esa cuenta puede llegar a registrar: reintentar no lo soluciona, habla con nosotros.

En este árbol no hay CORS, a propósito: una clave secreta no pinta nada en un frontend, y sin esas cabeceras un navegador no puede mandarla desde otro origen.

Dos reglas que conviene saber antes de construir. El alta está sujeta al mismo techo por cuenta que el formulario, así que consulta whoami primero y escríbenos si tu importación no cabe. Y una ficha ya verificada no puede cambiar de nombre, tipo, ámbito ni responsable por ninguna vía: es justo lo que acredita el sello, y permitir que cambie después sería un engaño para todo el que se fió de él.