Sviluppatori

Authorization: Bearer vt_live_…

// server.js (Node 18+, Express)
import express from "express";

const app = express();

app.post("/voice/session", async (req, res) => {
  // Applica qui la tua autenticazione e il tuo rate limiting.
  const r = await fetch("https://hubvocal.com/v1/web-calls", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.VT_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ agent_id: "front-desk" }),
  });
  res.status(r.status).json(await r.json());
});

app.listen(3000);

# app.py (Flask)
import os

import requests
from flask import Flask, jsonify

app = Flask(__name__)


@app.post("/voice/session")
def voice_session():
    # Applica qui la tua autenticazione e il tuo rate limiting.
    r = requests.post(
        "https://hubvocal.com/v1/web-calls",
        headers={"Authorization": f"Bearer {os.environ['VT_API_KEY']}"},
        json={"agent_id": "front-desk"},
        timeout=15,
    )
    return jsonify(r.json()), r.status_code

<button id="talk" type="button">Inizia a parlare</button>

<script type="module">
  import { Room, RoomEvent, Track } from "https://cdn.jsdelivr.net/npm/livekit-client@2.23.0/dist/livekit-client.esm.mjs";

  const button = document.getElementById("talk");
  let room;

  button.addEventListener("click", async () => {
    if (room) {
      await room.disconnect();
      return;
    }
    button.disabled = true;
    // Il tuo server restituisce così com'è la risposta di POST /v1/web-calls.
    const res = await fetch("/voice/session", { method: "POST" });
    const session = await res.json();
    if (!res.ok) {
      button.disabled = false;
      alert(session.detail);
      return;
    }

    room = new Room();
    // Collega l'audio dell'agente a un elemento <audio> quando arriva.
    room.on(RoomEvent.TrackSubscribed, (track) => {
      if (track.kind === Track.Kind.Audio) document.body.appendChild(track.attach());
    });
    room.on(RoomEvent.Disconnected, () => {
      room?.remoteParticipants.forEach((p) =>
        p.audioTrackPublications.forEach((pub) => pub.track?.detach().forEach((el) => el.remove())),
      );
      room = undefined;
      button.textContent = "Inizia a parlare";
    });

    await room.connect(session.server_url, session.token);
    await room.localParticipant.setMicrophoneEnabled(true);
    button.disabled = false;
    button.textContent = "Riaggancia";
  });
</script>

curl -X POST "https://hubvocal.com/v1/calls" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "from": "+908501234567",
  "to": "+905321234567",
  "agent_id": "front-desk"
}'

const res = await fetch("https://hubvocal.com/v1/calls", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "from": "+908501234567",
    "to": "+905321234567",
    "agent_id": "front-desk"
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status}: ${data.detail}`);
console.log(data);

import os

import requests

resp = requests.post(
    "https://hubvocal.com/v1/calls",
    headers={"Authorization": f"Bearer {os.environ['VT_API_KEY']}"},
    json={
        "from": "+908501234567",
        "to": "+905321234567",
        "agent_id": "front-desk",
    },
    timeout=30,
)
if not resp.ok:
    raise RuntimeError(f"{resp.status_code}: {resp.json()['detail']}")
print(resp.json())

{
  "room": "tel-out-9c41e0b7",
  "provider": "didww",
  "sip_call_id": "SCL_7mVt2kQb9xRa"
}

curl -X PUT "https://hubvocal.com/v1/numbers/%2B908501234567" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_id": "front-desk",
  "label": "Main line"
}'

const res = await fetch("https://hubvocal.com/v1/numbers/%2B908501234567", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.VT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "agent_id": "front-desk",
    "label": "Main line"
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status}: ${data.detail}`);
console.log(data);

import os

import requests

resp = requests.put(
    "https://hubvocal.com/v1/numbers/%2B908501234567",
    headers={"Authorization": f"Bearer {os.environ['VT_API_KEY']}"},
    json={
        "agent_id": "front-desk",
        "label": "Main line",
    },
    timeout=30,
)
if not resp.ok:
    raise RuntimeError(f"{resp.status_code}: {resp.json()['detail']}")
print(resp.json())

curl -X POST "https://hubvocal.com/v1/agents/front-desk/publish" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "note": "Shorter greeting"
}'

const res = await fetch("https://hubvocal.com/v1/agents/front-desk/publish", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "note": "Shorter greeting"
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status}: ${data.detail}`);
console.log(data);

import os

import requests

resp = requests.post(
    "https://hubvocal.com/v1/agents/front-desk/publish",
    headers={"Authorization": f"Bearer {os.environ['VT_API_KEY']}"},
    json={
        "note": "Shorter greeting",
    },
    timeout=30,
)
if not resp.ok:
    raise RuntimeError(f"{resp.status_code}: {resp.json()['detail']}")
print(resp.json())

curl -X POST "https://hubvocal.com/v1/web-calls" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_id": "front-desk",
  "version": "draft"
}'

{
  "scenarios": [
    {
      "name": "Booking without a name",
      "persona": "A caller in a hurry who gives short answers",
      "goal": "Book an appointment tomorrow afternoon",
      "max_turns": 12,
      "expect": [
        "Asks for the caller's name before booking",
        "Reads the time back and asks for confirmation"
      ],
      "mocks": {
        "check_availability": {
          "ok": true,
          "slots": [
            "2026-11-06T14:00",
            "2026-11-06T15:30"
          ]
        }
      }
    }
  ],
  "version": "draft"
}

curl -X POST "https://hubvocal.com/v1/tools" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "check_order",
  "description": "Looks up the shipping status of an order by its number.",
  "kind": "read",
  "url": "https://crm.example.com/hooks/order",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "Order number"
      }
    },
    "required": [
      "order_id"
    ]
  },
  "timeout_s": 8,
  "enabled": true,
  "secret": "whsec_2b7f…"
}'

const res = await fetch("https://hubvocal.com/v1/tools", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "check_order",
    "description": "Looks up the shipping status of an order by its number.",
    "kind": "read",
    "url": "https://crm.example.com/hooks/order",
    "parameters": {
      "type": "object",
      "properties": {
        "order_id": {
          "type": "string",
          "description": "Order number"
        }
      },
      "required": [
        "order_id"
      ]
    },
    "timeout_s": 8,
    "enabled": true,
    "secret": "whsec_2b7f…"
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status}: ${data.detail}`);
console.log(data);

import os

import requests

resp = requests.post(
    "https://hubvocal.com/v1/tools",
    headers={"Authorization": f"Bearer {os.environ['VT_API_KEY']}"},
    json={
        "name": "check_order",
        "description": "Looks up the shipping status of an order by its number.",
        "kind": "read",
        "url": "https://crm.example.com/hooks/order",
        "parameters": {
            "type": "object",
            "properties": {
                "order_id": {
                    "type": "string",
                    "description": "Order number",
                },
            },
            "required": [
                "order_id",
            ],
        },
        "timeout_s": 8,
        "enabled": True,
        "secret": "whsec_2b7f…",
    },
    timeout=30,
)
if not resp.ok:
    raise RuntimeError(f"{resp.status_code}: {resp.json()['detail']}")
print(resp.json())

POST /hooks/order HTTP/1.1
Host: crm.example.com
Content-Type: application/json
X-VT-Timestamp: 1793832421
X-VT-Signature: sha256=5f0c9a…

{
  "tool": "check_order",
  "arguments": {
    "order_id": "A-10234"
  },
  "call": {
    "room": "tel-6b1f04d2",
    "org_id": "6f1c2a40-3b7e-4d0c-9a51-2f8e7c1d9b03",
    "agent": "front-desk",
    "channel": "phone_in",
    "caller": "+905321234567",
    "called": "+908501234567",
    "lang": "en"
  }
}

// server.js (Node 18+, Express)
import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.VT_TOOL_SECRET;

// La firma copre i byte esatti: leggi il corpo grezzo.
app.post("/hooks/order", express.raw({ type: "*/*" }), (req, res) => {
  const ts = req.get("X-VT-Timestamp") ?? "";
  const sig = req.get("X-VT-Signature") ?? "";

  // Rifiuta le richieste vecchie (protezione dal replay).
  if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.sendStatus(401);

  const expected = "sha256=" + crypto.createHmac("sha256", SECRET).update(ts + ".").update(req.body).digest("hex");
  const a = Buffer.from(sig);
  const b = Buffer.from(expected);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return res.sendStatus(401);

  const { tool, arguments: args, call } = JSON.parse(req.body.toString("utf8"));
  // Rispondi in breve: al modello arrivano solo i primi 4 KB.
  res.json({ order_id: args.order_id, status: "shipped", eta: "2026-11-07" });
});

app.listen(3000);

# app.py (Flask)
import hashlib
import hmac
import json
import os
import time

from flask import Flask, abort, jsonify, request

app = Flask(__name__)
SECRET = os.environ["VT_TOOL_SECRET"].encode()


@app.post("/hooks/order")
def order():
    ts = request.headers.get("X-VT-Timestamp", "")
    sig = request.headers.get("X-VT-Signature", "")

    # Rifiuta le richieste vecchie (protezione dal replay).
    if not ts.isdigit() or abs(time.time() - int(ts)) > 300:
        abort(401)

    # La firma copre i byte esatti: leggi il corpo grezzo.
    body = request.get_data()
    expected = "sha256=" + hmac.new(SECRET, ts.encode() + b"." + body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(sig, expected):
        abort(401)

    payload = json.loads(body)
    args = payload["arguments"]
    # Rispondi in breve: al modello arrivano solo i primi 4 KB.
    return jsonify(order_id=args["order_id"], status="shipped", eta="2026-11-07")

curl -X POST "https://hubvocal.com/v1/tools/tl_8f3a2c/test" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "arguments": {
    "order_id": "A-10234"
  }
}'

const res = await fetch("https://hubvocal.com/v1/tools/tl_8f3a2c/test", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "arguments": {
      "order_id": "A-10234"
    }
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status}: ${data.detail}`);
console.log(data);

import os

import requests

resp = requests.post(
    "https://hubvocal.com/v1/tools/tl_8f3a2c/test",
    headers={"Authorization": f"Bearer {os.environ['VT_API_KEY']}"},
    json={
        "arguments": {
            "order_id": "A-10234",
        },
    },
    timeout=30,
)
if not resp.ok:
    raise RuntimeError(f"{resp.status_code}: {resp.json()['detail']}")
print(resp.json())

curl -X POST "https://hubvocal.com/v1/knowledge" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -F "file=@price-list-2026.pdf"

import fs from "node:fs";

const form = new FormData();
form.append("file", new Blob([await fs.promises.readFile("price-list-2026.pdf")]), "price-list-2026.pdf");

const res = await fetch("https://hubvocal.com/v1/knowledge", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.VT_API_KEY}` },
  body: form,
});
console.log(await res.json());

import os

import requests

with open("price-list-2026.pdf", "rb") as f:
    resp = requests.post(
        "https://hubvocal.com/v1/knowledge",
        headers={"Authorization": f"Bearer {os.environ['VT_API_KEY']}"},
        files={"file": ("price-list-2026.pdf", f, "application/pdf")},
        timeout=60,
    )
print(resp.json())

curl -X POST "https://hubvocal.com/v1/knowledge/search" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "how much is a scale and polish"
}'

const res = await fetch("https://hubvocal.com/v1/knowledge/search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "query": "how much is a scale and polish"
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status}: ${data.detail}`);
console.log(data);

import os

import requests

resp = requests.post(
    "https://hubvocal.com/v1/knowledge/search",
    headers={"Authorization": f"Bearer {os.environ['VT_API_KEY']}"},
    json={
        "query": "how much is a scale and polish",
    },
    timeout=30,
)
if not resp.ok:
    raise RuntimeError(f"{resp.status_code}: {resp.json()['detail']}")
print(resp.json())

{
  "calendar": {
    "integration_id": "int_4a7c10",
    "calendar_id": "primary",
    "duration_min": 30,
    "buffer_min": 10,
    "timezone": "Europe/Istanbul",
    "working_hours": {
      "mon": [
        [
          "09:00",
          "18:00"
        ]
      ],
      "tue": [
        [
          "09:00",
          "18:00"
        ]
      ],
      "wed": [
        [
          "09:00",
          "18:00"
        ]
      ],
      "thu": [
        [
          "09:00",
          "18:00"
        ]
      ],
      "fri": [
        [
          "09:00",
          "17:00"
        ]
      ]
    },
    "min_notice_h": 2,
    "max_days_ahead": 30
  }
}

curl -X POST "https://hubvocal.com/v1/mcp-servers" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "crm",
  "url": "https://mcp.example.com/mcp",
  "auth": "bearer",
  "secret": "sk_live_…"
}'

const res = await fetch("https://hubvocal.com/v1/mcp-servers", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "crm",
    "url": "https://mcp.example.com/mcp",
    "auth": "bearer",
    "secret": "sk_live_…"
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status}: ${data.detail}`);
console.log(data);

import os

import requests

resp = requests.post(
    "https://hubvocal.com/v1/mcp-servers",
    headers={"Authorization": f"Bearer {os.environ['VT_API_KEY']}"},
    json={
        "name": "crm",
        "url": "https://mcp.example.com/mcp",
        "auth": "bearer",
        "secret": "sk_live_…",
    },
    timeout=30,
)
if not resp.ok:
    raise RuntimeError(f"{resp.status_code}: {resp.json()['detail']}")
print(resp.json())

claude mcp add --transport http hubvocal https://hubvocal.com/mcp \
  --header "Authorization: Bearer vt_live_…"

{
  "mcpServers": {
    "hubvocal": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://hubvocal.com/mcp",
        "--header",
        "Authorization:${VT_AUTH}"
      ],
      "env": {
        "VT_AUTH": "Bearer vt_live_…"
      }
    }
  }
}

{
  "mcpServers": {
    "hubvocal": {
      "url": "https://hubvocal.com/mcp",
      "headers": {
        "Authorization": "Bearer vt_live_…"
      }
    }
  }
}

from openai import OpenAI

client = OpenAI()
resp = client.responses.create(
    model="gpt-5.6-luna",
    tools=[{
        "type": "mcp",
        "server_label": "hubvocal",
        "server_url": "https://hubvocal.com/mcp",
        "headers": {"Authorization": "Bearer vt_live_…"},
        "require_approval": "always",
    }],
    input="Summarise yesterday's calls.",
)
print(resp.output_text)

<script src="https://hubvocal.com/widget.js" data-agent="pk_…" async></script>

{
  "widget": {
    "color": "#2563eb",
    "position": "bottom-right",
    "label": "Talk to us"
  }
}

{
  "post_call": {
    "summary": true,
    "fields": [
      {
        "name": "appointment_date",
        "type": "date",
        "description": "Requested appointment date"
      },
      {
        "name": "service",
        "type": "enum",
        "enum": [
          "checkup",
          "cleaning",
          "whitening"
        ],
        "description": "Service the caller asked about"
      },
      {
        "name": "callback",
        "type": "boolean",
        "required": true,
        "description": "Does the caller want a callback?"
      }
    ]
  }
}

{
  "extracted": {
    "appointment_date": "2026-11-12",
    "service": "cleaning",
    "callback": true
  }
}

curl -X POST "https://hubvocal.com/v1/webhooks" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://crm.example.com/hooks/voice",
  "events": [
    "call.ended"
  ]
}'

const res = await fetch("https://hubvocal.com/v1/webhooks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "url": "https://crm.example.com/hooks/voice",
    "events": [
      "call.ended"
    ]
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status}: ${data.detail}`);
console.log(data);

import os

import requests

resp = requests.post(
    "https://hubvocal.com/v1/webhooks",
    headers={"Authorization": f"Bearer {os.environ['VT_API_KEY']}"},
    json={
        "url": "https://crm.example.com/hooks/voice",
        "events": [
            "call.ended",
        ],
    },
    timeout=30,
)
if not resp.ok:
    raise RuntimeError(f"{resp.status_code}: {resp.json()['detail']}")
print(resp.json())

POST /hooks/voice HTTP/1.1
Host: crm.example.com
Content-Type: application/json
X-VT-Event: call.ended
X-VT-Delivery: dl_51b7a9
X-VT-Timestamp: 1793832440
X-VT-Signature: sha256=9b1e44…

{
  "id": "evt_8a41f0c2",
  "type": "call.ended",
  "created_at": "2026-11-05T09:47:20Z",
  "data": {
    "room": "demo-8585522d",
    "org_id": "6f1c2a40-3b7e-4d0c-9a51-2f8e7c1d9b03",
    "org_name": "Example Clinic",
    "channel": "web",
    "profile": "Front desk",
    "engine": "live",
    "lang": "en",
    "voice": "marin",
    "started_at": 1793832409.1,
    "ended_at": 1793832434.2,
    "duration_s": 25.1,
    "total_usd": 0.021215,
    "ended_by": "caller",
    "outcome": "message_taken",
    "summary_text": "The caller asked for an appointment on Thursday afternoon; a message was taken for a callback.",
    "extracted": {
      "appointment_date": "2026-11-12",
      "callback": true
    },
    "first_audio_s": 2.43,
    "turns": 4,
    "source_gaps": {
      "count": 2,
      "total_ms": 230,
      "max_ms": 141,
      "agent_audio_s": 31.2,
      "events": [
        [
          16.4,
          141
        ],
        [
          40.1,
          89
        ]
      ]
    },
    "quality": {
      "verdict": "Clean: no loss, no gaps.",
      "protocol": "UDP",
      "loss_pct": 0,
      "conceal_pct": 0,
      "jitter_ms": 4,
      "rtt_ms": 38
    },
    "cost": {
      "live": {
        "billed_s": 25.1,
        "reported": true,
        "voice_usd": 0.020917,
        "backend": {
          "in": 1840,
          "cached": 1024,
          "out": 96
        },
        "backend_usd": 0.000298
      },
      "llm": {
        "input_tokens": 1840,
        "cached_tokens": 1024,
        "output_tokens": 96,
        "usd": 0.000298
      },
      "tts": {
        "input_tokens": 0,
        "audio_tokens": 0,
        "audio_s": 25.1,
        "usd": 0.020917
      },
      "stt": {
        "audio_s": 0,
        "usd": 0
      }
    },
    "tools": [
      {
        "t": 14.2,
        "name": "check_order",
        "kind": "read",
        "ok": true,
        "ms": 412,
        "status": 200
      }
    ],
    "outcomes": [],
    "summary": {
      "text": "The caller asked for an appointment on Thursday afternoon; a message was taken for a callback.",
      "language": "en",
      "outcome": "message_taken",
      "sentiment": "neutral",
      "topics": [
        "appointment"
      ],
      "action_items": [
        "Call the caller back on Thursday morning"
      ]
    },
    "recording": {
      "available": true,
      "duration_s": 25.1,
      "size_bytes": 201344
    },
    "supervisors": [
      {
        "user": "ayse@example.com",
        "joined_at": 1793832420.4,
        "left_at": 1793832431,
        "modes": [
          "listen",
          "whisper"
        ]
      }
    ],
    "greeting": {
      "connect_s": 0.15,
      "session_started_s": 0.05,
      "reply_requested_s": 0.05,
      "first_audio_s": 2.4,
      "reply_done_s": 7.1
    },
    "transcript": [
      {
        "role": "assistant",
        "text": "Hello, thanks for calling the clinic. How can I help you today?",
        "t": 2.4,
        "interrupted": false
      },
      {
        "role": "user",
        "text": "I would like an appointment on Thursday afternoon.",
        "t": 9.8
      }
    ]
  }
}

// Verifica prima la firma (stesso codice degli strumenti).
app.post("/hooks/voice", express.raw({ type: "*/*" }), async (req, res) => {
  if (!verify(req)) return res.sendStatus(401);

  // Consegna già elaborata? Conferma la ricezione e fermati.
  const delivery = req.get("X-VT-Delivery");
  if (await db.deliveries.exists(delivery)) return res.sendStatus(200);
  await db.deliveries.insert(delivery);

  // Rispondi subito; il lavoro lento fallo in background.
  res.sendStatus(200);
  const event = JSON.parse(req.body.toString("utf8"));
  queue.add("call-ended", event.data);
});

# Verifica prima la firma (stesso codice degli strumenti).
@app.post("/hooks/voice")
def voice_hook():
    if not verify(request):
        abort(401)

    # Consegna già elaborata? Conferma la ricezione e fermati.
    delivery = request.headers["X-VT-Delivery"]
    if db.deliveries.exists(delivery):
        return "", 200
    db.deliveries.insert(delivery)

    # Rispondi subito; il lavoro lento fallo in background.
    event = json.loads(request.get_data())
    queue.enqueue("call_ended", event["data"])
    return "", 200

{
  "detail": "Monthly spending limit reached"
}

async function vt(path, init = {}, attempt = 0) {
  const res = await fetch(`https://hubvocal.com/v1${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${process.env.VT_API_KEY}`,
      "Content-Type": "application/json",
      ...init.headers,
    },
  });
  if (res.status === 429 && attempt < 3) {
    const wait = Number(res.headers.get("Retry-After") ?? 60);
    await new Promise((r) => setTimeout(r, wait * 1000));
    return vt(path, init, attempt + 1);
  }
  const data = await res.json();
  if (!res.ok) throw new Error(`${res.status}: ${data.detail}`);
  return data;
}