API

Two APIs

Two different things are called an API here, and they are not the same surface.

The local API belongs to the desktop companion, tcc. The daemon runs on your own machine and serves an HTTP interface on the loopback address. Anything you can do in the companion — verify three words, stamp a file, list connections, manage an organisation — has a route. It has a committed OpenAPI document, which is what these pages are written from, and the daemon serves that same document to callers.

The platform API is the server side: the hosted service the apps talk to. It is not published, and it carries no user-specific routes at all — see below, because the reason is a deliberate one rather than a gap.

What This Section Covers

These pages cover the local API only. They describe where the daemon listens, how a caller authenticates, what the responses look like, and every one of the 79 documented paths.

They do not teach the companion itself. Installing it, signing it in and running it as a daemon are covered in the companion and CLI pages.

Why the Platform API Is Absent

The short reason is that it has no published document, no published version and no stability promise, so pages about it would describe a surface nobody has committed to keeping.

The longer reason is the one that will not change: there are no user-specific routes on the platform to publish.

Answering “what is Mary’s code?” on a server means the server holds the secret that produces the code. The moment it does, the end-to-end promise is over — not because anyone would misuse it, but because it stops being true. A server that CAN read your codes is a server whose compromise reads everybody’s codes, and no amount of care on our side changes what an attacker would walk away with.

So we keep no user secrets on any server we run, and a user-facing platform API is a thing we cannot build without giving that up. What the platform does expose is system-level, machine-to-machine work that touches no personal secret, and an account holder has no access to that in the first place.

This is not a gap waiting to be filled. If the platform API is published one day, it will cover the same system-level ground and still hold nothing of yours.

The consequence for an integration: the only thing that can answer questions about an account’s connections is something holding that account’s keys — the local companion. It keeps the session and the keys on your own machine, does the work there, and talks to the platform for the parts that need no secret. That is why these pages document the local API, and why it is not a second-best.