API and MCP

The agent server is at https://api.vasal.site. This page lists every route it answers, the events it streams, and the MCP door for agents. Anything else answers 404 {"error":"NOT_FOUND"}, and an unexpected failure answers 500 {"error":"INTERNAL"}.

Rules for every routeCopy Anchor Link

• Refusals are JSON: a refusal is { "error": "<CODE>" }, changes nothing, and writes one log line holding only the route pattern and the code.
• Spending routes need a same-site POST: POST /runs, /runs/:id/confirm, /runs/:id/brief and /agent-keys need Content-Type: application/json and an Origin header equal to the site's origin. Otherwise they answer 403 FORBIDDEN_ORIGIN. This stops other websites from starting runs through their visitors' browsers. It does not stop a script that writes the header, which is what the human check and the caps are for. A body over 8 KiB (4 KiB for /agent-keys) answers 413 TOO_LARGE. A body that is not JSON, has an unknown key or breaks a limit answers 400 BAD_INPUT.
• A GET never spends: no GET, HEAD or prefetch starts a run or calls Qloo or the model.
• CORS: everything except /mcp allows the site's origin only, with the methods GET and POST and the headers Content-Type and Last-Event-ID. /mcp sends no CORS headers.
• Run paths: every /runs response carries X-Robots-Tag: noindex and Cache-Control: no-store. Every response carries X-Content-Type-Options: nosniff and Referrer-Policy: no-referrer.
• Run ids: a run id is a random UUID. No route lists visitors' runs.

RoutesCopy Anchor Link

GET /healthCopy Anchor Link

200 { "ok": true, "liveRuns": <true or false> } when the database answers within 2 seconds. Otherwise 503 { "ok": false }.

GET /showcaseCopy Anchor Link

200 { "runs": [...] }, cacheable for 60 seconds and open to indexing. It reads storage only. Each run holds runId, position, showName, finishedAt, guests (the first 3 on the board, each with id, name, fit, fitKnown, reach, rising, bringsNew and sharedTags), pastGuests and kolam.

POST /runsCopy Anchor Link

Body:

{ "show": "SmartLess", "exclude": ["<a name to leave out>"], "turnstileToken": "<the human check answer>" }

show is 1 to 300 characters. exclude is optional: up to 25 names of 1 to 100 characters, applied in code and never shown to the model. The site does not offer it. turnstileToken is required. Success is 202 { "runId": "<a uuid>" }, and the run continues in the background.

GET /runs/:idCopy Anchor Link

{
  "id": "<a uuid>",
  "status": "queued, awaiting_confirm, running, done or failed",
  "createdAt": "<a time>",
  "finishedAt": "<a time or null>",
  "errorCode": "<a code or null>",
  "candidates": [{ "id": "<a uuid>", "appleId": "<an id or null>", "name": "<name>", "publisher": "<publisher>", "qlooName": "<name>" }],
  "board": [{ "id": "<a uuid>", "name": "<name>", "fit": "<a number from 0 to 1>", "fitKnown": true, "fitRank": 1, "reach": "household name or null", "rising": "rising, steady, falling or unknown", "bringsNew": "<a group or null>", "sharedTags": ["<tag>"], "angle": "<text>" }],
  "kolam": "<a drawing as numbers, or null>",
  "withoutQloo": "<the flip, or null>",
  "pastGuests": { "checked": true, "episodes": 0, "since": "<YYYY-MM or null>", "source": "directory, linked or pasted", "feedName": "<name or null>", "feedPublisher": "<name or null>", "archiveTitles": 0 }
}

board, kolam, withoutQloo and pastGuests are filled only when status is done. A run that stopped early shows no board. withoutQloo is { "status": "done", "guesses": [...], "unresolved": <a whole number> } or { "status": "unavailable" }. Each guess holds name, fit, fitKnown, reach, pastGuest, host and onBoard. The feed's link and Qloo's ids are never in this answer, and the flip holds Qloo's names only, never the model's guesses as it wrote them. An unknown id answers 404 NOT_FOUND.

GET /runs/:id/eventsCopy Anchor Link

200 text/event-stream. A reconnecting client can send Last-Event-ID, and a value that is not plain digits replays from the start. A HEAD request answers 200 with no stream. The server holds at most 3 streams per run, 6 per visitor and 100 in all. A full server or visitor answers 503 STREAMS_FULL with Retry-After: 5. A full run answers 429 TOO_MANY_STREAMS. An unknown run answers 404 NOT_FOUND.

Each frame is exactly:

id: <a whole number>
event: <an event name>
data: <one line of JSON>

A line starting with a colon (: ping) is a keep-alive every 15 seconds. The server ends the stream at a done or failed event, once the candidates event is out for a run waiting to be confirmed, or after 10 minutes. A page opens a new stream after the host confirms.

POST /runs/:id/confirmCopy Anchor Link

Body { "candidateId": "<a uuid>" }. Only an id the server issued for this run is accepted, and nothing else can be sent. Success is 202 { "ok": true }, and the agent continues in the background.

POST /runs/:id/briefCopy Anchor Link

Body { "guestId": "<a uuid>" }. A guest on the run's stored board only. If the brief exists, the answer is 200 { "brief": { "why", "angle", "questions", "pitchSubject", "pitchBody" } }. Otherwise the brief is claimed once, and the answer is 202 { "status": "pending" }. Poll GET /runs/:id/briefs/:guestId.

GET /runs/:id/briefs/:guestIdCopy Anchor Link

Reads storage only. The answer is one of { "status": "done", "brief": {...} }, { "status": "pending" }, { "status": "failed", "code": "<a code or null>" } and { "status": "none" }. none means no brief has been asked for, or a budget deferred it. An unknown run answers 404 NOT_FOUND and a guest not on the board 404 UNKNOWN_GUEST.

GET and POST /agent-keysCopy Anchor Link

GET answers 200 { "open": <true or false>, "limits": { "runsPerDay", "findsPerDay", "briefsPerDay", "inflightPerKey", "keyLifeDays", "keysPerVisitorPerDay" } }, cacheable for 30 seconds. open is false when the flag cannot be read.

POST takes { "turnstileToken": "<the human check answer>" } and answers 201 { "token": "vsl_...", "expiresAt": "<a time>" } with Cache-Control: no-store. The key appears in that one response and nowhere else.

The MCP doorCopy Anchor Link

The address is https://api.vasal.site/mcp. It speaks MCP over Streamable HTTP, stateless and JSON only. Each request carries Authorization: Bearer vsl_..., and every request is checked on its own. Connect your agent has the setup for each client.

Checks before a tool runsCopy Anchor Link

The checks run in this order, and each refusal is { "error": "<code>" } in lower case.

The key is read only from the header, never from a query string, a cookie or the body. A key is 32 random bytes behind the prefix vsl_, and only its SHA-256 is stored.

The four toolsCopy Anchor Link

Each tool validates its input strictly. An extra field or a wrong type is invalid_input. All four are marked open-world, because their results hold text from outside. get_board is marked read-only.

find_showCopy Anchor Link

Finds the podcast a name or link points to. Input { "query": "<a show name, an Apple Podcasts link or an RSS feed link>" }, 1 to 300 characters. It spends one of the key's 20 daily searches and holds the single agent run place while it works.

{
  "candidates": [{ "candidateId": "<a uuid>", "name": "<name>", "publisher": "<publisher>", "qlooName": "<name>", "appleUrl": "<a link or null>" }],
  "source": "<a fixed label>"
}

Up to 5 candidates. A candidateId is valid for one hour and only for the key that got it.

book_guestsCopy Anchor Link

Builds the board for one candidate. Input { "candidateId": "<a uuid>" }. It waits up to 45 seconds. Asking again for the same candidate returns the same run and spends nothing. It spends one of the key's 3 daily boards.

A guest holds guestId, name, fit, fitKnown, fitRank, reach ("household name" or null), rising, bringsNew (a group or null), sharedTags (up to 5), and angle. pastGuests says whether past guests were checked, against how many feed episodes, back to which month, and which kind of feed. runUrl is the website page for the run, built from the configured origin and the run id.

get_boardCopy Anchor Link

Reads a run this key started. Input { "runId": "<a uuid>" }. It spends nothing and works while live runs are off. Its answer has the shapes above, plus { "status": "failed", "runId", "reason": "<an error code>", "source" } for a run that stopped.

write_briefCopy Anchor Link

Writes, or returns, the AI-drafted brief and pitch for one guest on a finished board. Input { "runId": "<a uuid>", "guestId": "<a uuid>" }. It waits up to 30 seconds. It spends one of the key's 15 daily briefs, once per guest.

{
  "status": "done",
  "runId": "<a uuid>",
  "guestId": "<a uuid>",
  "brief": { "why": "<text>", "angle": "<text>", "questions": ["<text>"], "pitchSubject": "<text>", "pitchBody": "<text>" },
  "source": "<a fixed label>"
}

If the brief is not ready in time, the answer is { "status": "pending", "source": "<a fixed label>" }. Call again.

Tool errorsCopy Anchor Link

A tool error is a result with isError: true and exactly { "error": "<code>" }. The codes are a fixed set. "Does not exist" and "belongs to another key" both answer not_found, so a caller learns nothing about other keys' runs.

Limits per keyCopy Anchor Link

Days are UTC days. Agent runs spend from their own Qloo and model shares, and take one of the site's run places only together with the single agent place, so agents can never use all the places the website needs.

Every result's text is data, not instructions. Names, tags and episode information come from directories, feeds and Qloo, and angles and briefs are written by an AI model. Vasal strips links, emails and invisible characters, and a fixed source field labels the result, but that is a hint and not a defence.