The Vaucai API

What it is

An API is the door one program uses to talk to another with no person in between. Vaucai's lets your apps and scripts use your Vaucai: ask it questions, read your data and trigger actions, with the context and the memory it holds about you. All with a key, nothing to set up.

Your key decides what it can do

A key carries exactly the permissions you give it when you create it, not one more. A brand new key only answers; you decide whether it can also read your lists, run actions or propose the delicate ones.

• Ask for it in the chat: "give me an API key" and it comes as answer-only. Or be specific: "give me a key that can create reminders and see my calendar".
• If the key is going to act or read your data, it shows you first what it will be able to do. And it asks you to confirm with a button: you give the permission once, by hand, in Telegram.
• It is handed to you once: copy it, it is never shown again, and your Vaucai never sees it. Keep it in an environment variable. Manage them by talking: "what keys do I have?", "revoke the Zapier one".

The two endpoints

The key travels in every call in the Authorization: Bearer header. There are two doors:

• POST /api/assistant/v1/messages: you ask your Vaucai's "brain". It answers with your profile and your memory, touching nothing. Any key works; nothing can happen here.
• POST /api/assistant/v1/actions: the working endpoint. With the key's permissions, it queries your real data, runs actions and proposes the ones that need your say-so.

Asking

(curl is a terminal command for firing the request.)

curl -X POST https://vaucai.com/api/assistant/v1/messages \
  -H "Authorization: Bearer vauk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "What do I have on today?"}'

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

The body carries a single field, message (up to 4,000 characters). The response returns the text in reply and the model that produced it in model.

Acting and querying

Send the instruction in plain language to /actions; your Vaucai uses the tools the key holds.

curl -X POST https://vaucai.com/api/assistant/v1/actions \
  -H "Authorization: Bearer vauk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "remind me to call the plumber tomorrow at 10"}'

{ "reply": "Done, I will remind you tomorrow at 10:00.",
  "actions": [ { "tool": "schedule_reminder", "ok": true } ],
  "model": "...", "request_id": "..." }

The actions field tells you what it did and whether it worked. Querying your data goes through the same door: "what do I have on today and what tasks are left?", if the key holds those read permissions.

What a key can do

This is what you can authorise, by group. Each group allows viewing and changing its own things:

• Reminders: view, create one (one-off or recurring) and cancel it.
• Tasks: view, create, complete, edit and delete (Microsoft To Do).
• Notes: view, jot one down and delete it.
• Keepsakes: view, save something and forget it.
• Shopping list: view, add, remove and empty.
• Contacts: view, save a new one and edit it.
• Birthdays: view, save and remove.
• Trips: view, add, edit and remove.
• Countdowns: view, set one and remove it.
• Price watches: see what you watch, start watching, set a target and stop.
• Email follow-ups: dismiss a pending follow-up (without touching the email).
• Business expenses (with Business Mode on): record and edit expenses, save suppliers and read the dashboard. Picture a receipts app logging every expense in your ledger.
• Calendar (read only): see your calendar events.

What no key can do, by design and not by configuration: send emails, touch your calendar, create invoices or delete contacts and your account. Nor can it go near your passwords, your identity, your health or the content of your email and your documents. Anything with no way back, or too much yours, stays in the chat with you in front of it. This is not a gap we have yet to fill: it is deliberate and it is going to stay that way.

Proposing the irreversible (you confirm)

There are two important actions no key executes but your app can propose: sending an email and creating a calendar event. You ask your Vaucai, a button arrives in Telegram, and it only happens if you tap "Yes".

curl -X POST https://vaucai.com/api/assistant/v1/actions \
  -H "Authorization: Bearer vauk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "propose sending ana@x.com an email about the meeting"}'

The response carries the proposal's identifier inside actions. Keep it: that is the one you need to check whether you confirmed it. (The top-level request_id is a different thing: it identifies the call, and is for support.)

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

With that identifier you can check the status whenever you like:

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

{ "id": "...", "status": "confirmed",
  "summary": "Send an email to ana@x.com", "resolved_at": "..." }

The status goes from pending to confirmed, rejected, expired or failed. That last one means you confirmed it but the action did not go out. Proposals expire after 72 hours.

Plug it into Claude or Cursor

Your Vaucai also speaks MCP (Model Context Protocol), the standard Claude Desktop, Cursor and other AI tools use to plug in capabilities. With your key, those apps see exactly what you authorised as tools and use them for you. Set it up as a remote server:

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

From then on, ask from Claude or Cursor: "create a reminder in Vaucai", "what do I have on today?". Your Vaucai does it, with your key's permissions and limits.

Receiving notifications (webhooks)

So far your app calls Vaucai. It also works the other way: Vaucai notifies your app when something happens, with no polling. Register an https URL of yours by telling your Vaucai ("notify https://myapp.com/hook when a reminder fires"); it hands you a signing secret once and from then on POSTs to your URL on each event. Events: reminder.fired, price.drop and proposal.resolved.

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

{ "id": "...", "type": "reminder.fired", "created_at": "...",
  "data": { "text": "call the plumber", "reminder_id": "..." } }

To check the notification really came from Vaucai, compute HMAC-SHA256 of the string "timestamp.body" with your secret. Compare it with the v1 value in the header. Manage them by talking: "what webhooks do I have?", "remove the webhook for …".

Reference

Limits. Available on every plan. /messages: 30 requests per minute per origin and 30 per account. /actions: 20 per minute per account, plus a cap on actions per request. Everything counts against your plan's monthly spending cap.

Idempotency. On /actions duplicate protection is always on, whether or not you send the header. For 10 minutes, two requests with the same text run only once. The second gets the already computed response, with idempotent_replay: true. Send Idempotency-Key when you want to decide yourself what counts as the same event (useful if an automated alert arrives twice). Repeat the key with a different body and the new one does not run either: you get the first call's response. The 409 only arrives while the first request is still in flight.

Traceability. Every /actions response carries a request_id (also in the X-Request-Id header): keep it, that is the identifier to quote in support.

OpenAPI contract. The full thing is at openapi.json, ready to import into Postman or your SDK generator.

Response codes. 200 fine · 400 the message field arrives empty · 401 key missing or invalid · 402 monthly spending cap reached · 403 the key does not hold that permission · 409 the previous request with that same Idempotency-Key is still running · 422 the body has no message, is not valid JSON, or the key has no authorised action · 429 too many requests (check the Retry-After header) · 503 briefly unavailable, retry.