La API local

Para qué sirve

El daemon del compañero es un servidor HTTP normal. Expone la cuenta en la que está conectado — conexiones, códigos, invitaciones, etiquetas, plantillas, enlaces abiertos, administración de organización — como JSON sobre /api/v1/.

Así es como un script, un sistema de back-office o una cuenta de máquina usa Trusted Codes sin una persona ni un teléfono. El daemon guarda la sesión y las claves; quien llama solo tiene un token y habla HTTP normal.

Dónde escucha

La dirección por defecto es http://127.0.0.1:19821. Esa es la única entrada de servidor en el documento OpenAPI, y es el puerto fijo — solo loopback.

Dos variables de entorno la mueven: TCC_HTTP_BIND y TCC_HTTP_PORT. Quien llame sin interfaz debe respetar ambas en lugar de asumir el valor por defecto.

Que el puerto sea fijo es deliberado. Se puede añadir a una lista de permitidos una vez y dejarlo así.

Los dos documentos

El daemon sirve dos documentos OpenAPI en dos rutas, para dos públicos.

GET /api/v1/openapi.json es el documento REST tipado — las rutas que describen estas páginas. Se genera a partir de las estructuras de Rust que serializan las respuestas, así que un campo no puede escribirse de una forma en el documento y de otra en la conexión. El mismo documento está incluido en el repositorio, y los tipos de respuesta en TypeScript de la interfaz web del compañero se generan a partir de él.

GET /openapi.json, en la ruta sin prefijo, es otra cosa: el catálogo de las herramientas MCP del daemon, para clientes MCP y GPT personalizados. La sección de MCP cubre esa superficie.

GET /api/v1/docs sirve una página interactiva que renderiza el documento REST. Tanto esa página como /api/v1/openapi.json son públicas — sin token.

Salud y estado

GET /health (también GET /api/v1/health) no necesita token. Úsalo para responder «¿está vivo el daemon?». Es la única ruta documentada que responde antes de que el daemon haya iniciado sesión.

GET /api/v1/status necesita un token y responde más: si el daemon está autenticado, si el dispositivo está registrado, si la clave global está activa, el nombre del entorno con el que arrancó, el backend que realmente resolvió, la versión del daemon, cuántas conexiones tiene en caché, la última hora de sincronización, y un resumen de una línea.

El nombre del entorno y el backend resuelto son campos separados a propósito. Un daemon iniciado con un nombre de entorno se puede apuntar a otro sitio con una anulación, y solo el valor resuelto te dice con quién está hablando de verdad.

Algunos de esos campos son nulos para quien llama de máquina a máquina, que no tiene caché local y no es el propio usuario del daemon. Un nulo ahí significa «no aplica», no «desconocido».

Prefijo de ruta y compatibilidad

Los puntos finales de herramienta y MCP están registrados dos veces: una en una ruta plana para clientes antiguos, y otra bajo /api/v1/. Las integraciones nuevas deberían apuntar a la forma con prefijo. Las rutas sin prefijo se mantienen estables durante todo el ciclo de vida de v1 y solo se eliminan cuando llega /api/v2/.

Las rutas REST de estas páginas existen solo bajo /api/v1/.