La API de Vaucai

Qué es

Una API es la puerta por la que un programa habla con otro sin una persona de por medio. La de Vaucai deja que tus apps y scripts usen tu Vaucai: preguntarle, leer tus datos y disparar acciones, con el contexto y la memoria que tiene de ti. Todo con una clave, sin montar nada.

Tu clave decide lo que puede hacer

Una clave lleva exactamente los permisos que le das al crearla, ni uno más. Una clave recién creada solo responde; tú decides si además puede leer tus listas, ejecutar acciones o proponerte las delicadas.

• Pídela por el chat: "dame una clave de API" y sale de solo responder. O concreta: "dame una clave que pueda crear recordatorios y ver mi agenda".
• Si la clave va a actuar o a leer tus datos, te muestra antes qué podrá hacer. Y te pide confirmarlo con un botón: das el permiso una vez, con la mano, en Telegram.
• Se te entrega una sola vez: cópiala, no se vuelve a mostrar, y tu Vaucai nunca la ve. Guárdala en una variable de entorno. Gestiónalas hablando: "¿qué claves tengo?", "revoca la de Zapier".

Los dos endpoints

La clave viaja en cada llamada en la cabecera Authorization: Bearer. Hay dos puertas:

• POST /api/assistant/v1/messages: le preguntas al «cerebro» de tu Vaucai. Responde con tu perfil y tu memoria, sin tocar nada. Cualquier clave sirve; aquí no puede pasar nada.
• POST /api/assistant/v1/actions: el endpoint de trabajo. Con los permisos de la clave, consulta tus datos reales, ejecuta acciones y propone las que necesitan tu visto bueno.

Preguntar

(curl es una orden de terminal para lanzar la petición.)

curl -X POST https://vaucai.com/api/assistant/v1/messages \
  -H "Authorization: Bearer vauk_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{"message": "¿Qué tengo hoy?"}'

{ "reply": "...", "model": "..." }

El cuerpo lleva un solo campo, message (hasta 4.000 caracteres). La respuesta trae el texto en reply y el modelo que lo generó en model.

Actuar y consultar

Manda la instrucción en lenguaje natural a /actions; tu Vaucai usa las herramientas que la clave tiene.

curl -X POST https://vaucai.com/api/assistant/v1/actions \
  -H "Authorization: Bearer vauk_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{"message": "recuérdame llamar al fontanero mañana a las 10"}'

{ "reply": "Hecho, te lo recuerdo mañana a las 10:00.",
  "actions": [ { "tool": "schedule_reminder", "ok": true } ],
  "model": "...", "request_id": "..." }

El campo actions te dice qué hizo y si salió bien. Consultar tus datos va por la misma puerta: "¿qué tengo en la agenda hoy y qué tareas me quedan?", si la clave tiene esos permisos de lectura.

Qué puede hacer una clave

Esto es lo que puedes autorizar, por grupos. Cada grupo permite ver y cambiar lo suyo:

• Recordatorios: verlos, crear uno (puntual o recurrente) y cancelarlo.
• Tareas: verlas, crear, completar, editar y borrar (Microsoft To Do).
• Notas: verlas, apuntar una y borrarla.
• Recuerdos: verlos, guardar algo y olvidarlo.
• Lista de la compra: verla, añadir, quitar y vaciar.
• Contactos: verlos, guardar uno nuevo y editarlo.
• Cumpleaños: verlos, guardar y quitar.
• Viajes: verlos, añadir, editar y quitar.
• Cuentas atrás: verlas, poner una y quitarla.
• Vigilar precios: ver lo que vigilas, empezar a vigilar, fijar objetivo y dejar de vigilar.
• Seguimientos de correo: descartar un seguimiento pendiente (sin tocar el correo).
• Gastos del negocio (con el Modo Negocio activo): registrar y editar gastos, guardar proveedores y consultar el cuadro de mando. Imagina una app de tickets apuntando cada gasto en tu libro.
• Agenda (solo lectura): ver los eventos de tu calendario.

Lo que ninguna clave puede hacer, por diseño y no por configuración: mandar correos, tocar tu calendario, crear facturas o borrar contactos y tu cuenta. Tampoco puede acercarse a tus contraseñas, tu identidad, tu salud ni el contenido de tu correo y tus documentos. Lo que no tiene vuelta atrás o es demasiado tuyo se queda en el chat, contigo delante. No es un hueco que nos falte por rellenar: está así a propósito y va a seguir estándolo.

Proponer lo irreversible (tú confirmas)

Hay dos acciones importantes que ninguna clave ejecuta pero que tu app sí puede proponerte: enviar un correo y crear un evento en tu calendario. Se lo pides a tu Vaucai, te llega un botón a Telegram y solo se hace si pulsas «Sí».

curl -X POST https://vaucai.com/api/assistant/v1/actions \
  -H "Authorization: Bearer vauk_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{"message": "propón enviar a ana@x.com un correo recordando la reunión"}'

La respuesta trae el identificador de la propuesta dentro de actions. Guárdalo: es el que necesitas para saber si ya lo confirmaste. (El request_id de primer nivel es otra cosa: identifica la llamada, y sirve para soporte.)

{ "actions": [{ "tool": "propose_action", "ok": true,
                "request_id": "3f2a…" }], "request_id": "…" }

Con ese identificador consultas el estado cuando quieras:

curl https://vaucai.com/api/assistant/v1/actions/requests/REQUEST_ID \
  -H "Authorization: Bearer vauk_TU_CLAVE"

{ "id": "...", "status": "confirmed",
  "summary": "Enviar un correo a ana@x.com", "resolved_at": "..." }

El status va de pending a confirmed, rejected, expired o failed (este último es cuando la confirmaste pero la acción no llegó a salir). Las propuestas caducan a las 72 horas.

Conéctalo a Claude o Cursor

Tu Vaucai también habla MCP (Model Context Protocol), el estándar que usan Claude Desktop, Cursor y otras herramientas de IA para enchufar capacidades. Con tu clave, esas apps ven como herramientas justo lo que autorizaste y las usan por ti. Configúralo como un servidor remoto:

{
  "mcpServers": {
    "vaucai": {
      "type": "http",
      "url": "https://vaucai.com/api/assistant/v1/mcp",
      "headers": { "Authorization": "Bearer vauk_TU_CLAVE" }
    }
  }
}

A partir de ahí, pídeselo desde Claude o Cursor: "crea un recordatorio en Vaucai", "¿qué tengo en la agenda?". Tu Vaucai lo hace, con los permisos y límites de tu clave.

Recibe avisos (webhooks)

Hasta aquí llama tu app a Vaucai. También al revés: que Vaucai avise a tu app cuando pasa algo, sin sondear. Registras una URL https tuya diciéndoselo a tu Vaucai ("avisa a https://miapp.com/hook cuando se dispare un recordatorio"); te entrega un secreto de firma una sola vez y, a partir de ahí, hace POST a tu URL en cada evento. Eventos: reminder.fired, price.drop y proposal.resolved.

POST https://miapp.com/hook
X-Vaucai-Event: reminder.fired
X-Vaucai-Signature: t=1782940000,v1=HMAC_SHA256

{ "id": "...", "type": "reminder.fired", "created_at": "...",
  "data": { "text": "llamar al fontanero", "reminder_id": "..." } }

Para comprobar que el aviso es de verdad de Vaucai, calcula HMAC-SHA256 de la cadena "timestamp.cuerpo" con tu secreto y compáralo con el valor v1 de la cabecera. Gestiónalos hablando: "¿qué webhooks tengo?", "quita el webhook de …".

Referencia

Límites. Disponible en todos los planes. /messages: 30 peticiones por minuto por origen y 30 por cuenta. /actions: 20 por minuto por cuenta, más un tope de acciones por petición. Todo cuenta contra el tope de gasto mensual de tu plan.

Idempotencia. En /actions la protección contra duplicados está siempre puesta, mandes o no la cabecera. Durante 10 minutos, dos peticiones con el mismo texto se ejecutan una sola vez. La segunda recibe la respuesta ya calculada, con idempotent_replay: true. Manda Idempotency-Key cuando quieras decidir tú qué cuenta como el mismo evento (útil si un aviso automático llega duplicado). Si repites la clave con otro cuerpo tampoco se ejecuta lo nuevo: recibes la respuesta de la primera llamada. El 409 llega solo cuando la primera petición todavía está en marcha.

Trazabilidad. Cada respuesta de /actions trae un request_id (también en la cabecera X-Request-Id): guárdalo, es el identificador que citar en soporte.

Contrato OpenAPI. Lo tienes completo en openapi.json, listo para importar en Postman o en tu generador de SDKs.

Códigos de respuesta. 200 correcto · 400 el campo message llega vacío · 401 clave ausente o inválida · 402 tope de gasto del mes alcanzado · 403 la clave no tiene ese permiso · 409 la petición anterior con esa misma Idempotency-Key sigue en marcha · 422 el cuerpo no trae message, no es JSON válido, o la clave no tiene ninguna acción autorizada · 429 demasiadas peticiones (mira la cabecera Retry-After) · 503 no disponible un momento, reintenta.