API Endpoints

An API endpoint turns a tool or an agent into an HTTP operation with a URL, a request shape and a response shape. A caller sends an ordinary request with an API key; the platform picks the operation, binds the request to the target's arguments, runs it and returns the result.

It is the mirror image of a trigger. A trigger is how something outside calls in to start work, and answers as soon as the work is accepted. An endpoint is how something outside calls in to get an answer, and answers with it.

Use one when a system you do not control needs to reach something you built here: another team's service calling a pricing tool, a mobile app asking an agent a question, a partner integration you want to hand an OpenAPI document to.

The shape of a URL

https://service.ensembleapp.dev/external/v1/benefits/coverage/E-4417
                                └─ channel ─┘└─┬──┘ └──┬───┘ └───┬───┘
                                            version  slug   operation path

Everything externally callable lives under /external, which is deliberate: the trust boundary is visible in the path rather than by convention. Nothing under it is reachable without a key, and nothing under it is cacheable by a shared cache. The version segment answers only from a published definition; the one way to reach an unpublished one is the draft channel, which says so in the URL.

The three pieces

An API owns many operations. A key needs a grant on the API before it can call any of them, and the grant can be narrowed to particular operations.

What happens when a request arrives

Four properties of this order are worth knowing before you build on it.

Reaching the API is checked before the path is matched. A key with no grant gets 403 without learning which operations exist, so the surface cannot be used to enumerate them.

Binding failures are the caller's, and are specific. A declared number that arrives as "abc" is a 400 naming that field, not a 500 from inside your tool.

The target runs once, under a deadline. Thirty seconds by default, configurable per API. There is no asynchronous mode yet, so an operation that cannot answer in its budget is a 504 rather than a job to poll.

The call is recorded after the response is sent. Logging never delays a caller and never fails a call, which is also why a dropped log row is possible under load.

Where to go next