Quickstart

This walks the whole path once. It assumes you already have a tool that works, because an endpoint adds HTTP to a tool rather than replacing it: if the tool is wrong, the endpoint is wrong in the same way and with more moving parts in between.

1. Create the API

Go to API Endpoints and choose Create API.

Field	Notes
Name	For you. Shown in the list and as the OpenAPI document's title.
URL slug	The path segment callers use. Lowercase letters, numbers and hyphens.
Contract version	`v1`, or `latest` for a development endpoint. See Versions.

The slug and contract version together make the URL, and both are fixed once anything has been published under them. Choose them as though a caller will be depending on them, because that is exactly what will happen.

You now have a draft. Nothing is served yet.

2. Add an operation

Open the API and add an operation. The four decisions that matter:

Field	Example	Notes
Method	`GET`	`GET`, `POST`, `PUT`, `PATCH` or `DELETE`.
Path template	`/coverage/{employeeId}`	Appended to the API's base URL. `/` is the API root.
Safety	`safe`	What you promise about side effects. `GET` must be `safe`.
Target	A tool or an agent	What actually runs.

Then declare an input for each argument the target takes. For /coverage/{employeeId}, one path input:

Input field	Value	Notes
Argument name	`employeeId`	The name the tool expects.
In	`path`	Path inputs are always required and must be a primitive.
Public name	(blank)	Set it only when callers should use a different name.

Save the draft. The Docs tab now shows the generated OpenAPI document, which is worth a look: it is what a caller will see, and a missing description is obvious there in a way it is not in the editor.

Suggest an operation derives all of the above from the tool itself: the method, a resource path, and a placement for every argument. It is a proposal you can edit, and on a tool with more than two or three arguments it is considerably faster than declaring them by hand.

3. Try it before publishing

The draft is callable on its own channel, with no version segment:

curl https://service.ensembleapp.dev/external/draft/benefits/coverage/E-4417 \
  -H 'x-api-key: sk_...'

A key needs a grant on the API first, which step 4 covers; the draft shares its API with the published versions, so one grant covers both.

The draft channel is as private as the keys that can already call the API. It is for exercising a definition end to end, not for keeping work hidden.

4. Grant a key

Open the Access tab and add the key that should be allowed to call this API.

Choice	Effect
Whole API	Every operation, including ones added later.
Named operations	Only those. An operation added later is not included until you add it.
Read-only	Only operations declared `safe`, whatever else the grant names.

A grant is held on the API, not on a revision, so it survives publishing.

5. Publish

Publishing promotes the draft to the next revision and makes it the definition /external serves. Callers see no change in the URL: the revision number is not in it.

curl https://service.ensembleapp.dev/external/v1/benefits/coverage/E-4417 \
  -H 'x-api-key: sk_...'

HTTP/1.1 200 OK
X-Api-Version: v1
X-Request-Id: req-9f3c1d...
X-Target-Version: 4
Cache-Control: private, no-store

{ "plan": "PPO", "effectiveFrom": "2026-01-01" }

X-Target-Version is the tool revision that answered, which is the thing to quote when a response is not what you expected.

6. Hand over the document

A caller can read the contract for themselves, filtered to what their own key may call:

curl https://service.ensembleapp.dev/external/v1/benefits/_openapi.json \
  -H 'x-api-key: sk_...'

A narrowed grant gets a narrowed document, and a read-only grant does not see the unsafe operations. Advertising an operation the key would be refused is worse than not describing it, so the document is generated per key rather than published once.