Docs / Endpoints: webhooks, APIs, MCP, apps

Describing your endpoint

Somebody has to be told what your endpoint takes. Until now that was a mail that was wrong the first time the script changed. Every activated endpoint now describes itself, and the description is generated — never written by hand — from what already exists: the path, the credential the caller presents, the networks it may come from, the scripts or operations that answer, their declared shapes, and the limits a caller is bounded by.

Three ways to read it, one document

• In the browser, on the endpoint’s form, under What this endpoint takes.
• From the command line: a9script describe <endpoint>.
• By the caller itself: a GET on the endpoint’s own URL, with the same credential a call needs. For a tools endpoint it is also the tool list an assistant reads — see An endpoint an assistant can call.

The three answer the same document, because one place assembles it — the running node, the only place that knows the body cap, the rate window and the reply budget a caller is actually bounded by. The browser and the command line read what it assembled, so the description exists for an activated endpoint, not for a draft.

What it says, by interpretation

• Webhook: the sender owns the body, so the document names the path, the credential’s location and spelling, the networks, and the scripts that listen — it declares no shape it cannot know.
• API: one entry per listening script with the shapes that script declares, and one per operation.
• MCP: the tool list, each tool with its generated input schema — the same list a client receives from tools/list.

What it never invents

An undeclared shape is stated as undeclared, never as an empty field list. A reference that resolves to nothing is left out rather than replaced by a placeholder. An endpoint nothing listens on says so, because an empty section would read as an endpoint that takes nothing. A credential’s VALUE has nowhere to go in the document: it names where the credential is presented and how it is spelled, and nothing more.

Who may read it

A GET on the endpoint is admitted exactly as a call is — networks, then the credential, then the switch, then the rate window — so a stranger learns nothing from the description it could not learn by calling. The browser’s read adds the one fact a copy fetched from the endpoint cannot carry: whether the endpoint is switched on.