api and mcp

yapyap keeps everything on your machine, and everything the app can show you it can also answer — to a script you write, or to an assistant like Claude Desktop. Two doors, one set of answers:

• MCP, for AI assistants that speak it.
• HTTP, for anything else — curl, a Shortcut, a cron job, a plugin.

Both are local only. Nothing here opens a port to your network, and nothing leaves this machine. Both doors are open only while yapyap is running.

what is reachable

The same seventeen reads, whichever door you knock on: the list of recordings, one recording's details, its transcript, its turns, its marks, its action items, its sentiment; archive-wide search and the filters search offers; speakers and unnamed voices; the lenses you have and the answers they already produced; and the state of the search index (plus a way to resume building it).

MCP

Point your assistant at yapyap's own binary with --mcp. In Claude Desktop's config:

{
  "mcpServers": {
    "yapyap": { "command": "/Applications/yapyap.app/Contents/MacOS/yapyap", "args": ["--mcp"] }
  }
}

--mcp does not start a second yapyap: it connects to the one already running and relays the conversation to it. yapyap has to be open — if it is not, the assistant is told the door is shut rather than being left waiting. Each read appears to the assistant as a tool named after what it does (sessions_list, sentences_list, sessions_transcript_get, …).

MCP is macOS and Linux. On Windows, use HTTP.

HTTP

While yapyap runs, it also answers HTTP on a loopback address — 127.0.0.1, reachable from this machine and nowhere else. The port changes every launch, and every request needs that launch's token, so yapyap writes both to a small file only your account can read:

• macOS / Linux — $TMPDIR/yapyap-api-$USER.json (usually /tmp/yapyap-api-you.json on Linux)
• Windows — yapyap-api-<you>.json in your %TEMP% folder

eval "$(jq -r '"URL=\(.url) TOKEN=\(.token)"' "${TMPDIR:-/tmp}/yapyap-api-$USER.json")"

# every recording, newest first
curl -s -H "authorization: Bearer $TOKEN" "$URL/sessions"

# one transcript, as text
curl -s -H "authorization: Bearer $TOKEN" \
  "$URL/sessions/<recording-id>/transcript?format=text"

# search the whole archive
curl -s -H "authorization: Bearer $TOKEN" "$URL/sentences?q=budget&limit=5"

GET / lists every path with a line on what it does, and GET /openapi.json is the full machine-readable description — enough for a client generator, or for pasting into a tool that reads OpenAPI.

when something is refused

Every refusal is a small JSON object that says what happened, with the same HTTP status you would expect:

{
  "type": "https://yap-yap.app/problems/not-found",
  "title": "No such recording.",
  "status": 404,
  "detail": "recording abc123 does not exist, or is no longer visible."
}

The common ones: 401 the token is missing or wrong (re-read the file — yapyap may have restarted), 404 no such path or no such row, 405 the right path with the wrong method, 422 a parameter yapyap does not recognise or cannot use, and 402 the licence has lapsed for something that needs one.