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 asistente: 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.

• La pides por el chat: "dame una clave de API" (solo responde), o concreta lo que quieres, "dame una clave que pueda crear recordatorios y ver mi agenda".
• Si la clave va a actuar o a leer tus datos, tu asistente te muestra 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 asistente 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 asistente. 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 asistente 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, borrar contactos o tu cuenta, ni acercarse a tus contraseñas, tu identidad, tu salud o el contenido de tu correo y tus documentos. Es irreversible o íntimo: se queda para el chat, contigo delante. Esa asimetría es deliberada, es nuestra doctrina.

Proponer lo irreversible (tú confirmas)

Lo irreversible no lo ejecuta ninguna clave, pero tu app puede proponértelo: se lo pides a tu asistente, 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 lleva "actions": [{ "tool": "propose_action", "ok": true }] y un request_id. Tu app sabe si ya lo confirmaste consultando el estado:

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 o expired (las propuestas caducan a las 72 horas).

Conéctalo a Claude o Cursor

Tu asistente 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": {
      "url": "https://vaucai.com/api/assistant/v1/mcp",
      "headers": { "Authorization": "Bearer vauk_TU_CLAVE" }
    }
  }
}

A partir de ahí, desde Claude o Cursor puedes pedir "crea un recordatorio en Vaucai" o "¿qué tengo en la agenda?" y tu asistente 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 asistente ("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, manda la cabecera Idempotency-Key con un valor único por evento (útil si un aviso automático llega duplicado): la misma petición no se ejecuta dos veces, recibes la respuesta ya calculada con idempotent_replay: true. Reutilizar la clave con otro cuerpo devuelve 409.

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 cuerpo mal formado · 401 clave ausente o inválida · 402 tope de gasto del mes alcanzado · 403 la clave no tiene ese permiso · 409 misma Idempotency-Key con otro cuerpo · 422 la clave no tiene ninguna acción autorizada · 429 demasiadas peticiones (mira la cabecera Retry-After) · 503 no disponible un momento, reintenta.