Bind an OpenAPI source

This is the task page for working with a bound spec day to day. For what “live binding” means conceptually, see Spec source.

1. Add the provider

Add a source from the navigator’s API providers section. Give it either:

• a URL — http://localhost:8080/v3/api-docs, https://api.example.com/openapi.json, anything that serves the document; or
• a file path to a .json or .yaml spec.

If you do not know the path, give Tinspec the service’s base URL and let it discover the spec: it probes well-known documentation locations only, never resource paths.

Endpoints appear in the navigator grouped by OpenAPI tag.

2. Set the poll interval

Each provider has its own refresh interval. Choose it by how fast the spec actually moves:

• A spec generated by the service you are running locally changes on every rebuild — a short interval keeps up.
• A stable third-party spec does not need to be fetched every minute.

When the document is unreachable, the last successful fetch is served from the cache and your endpoints keep working.

3. Work with the endpoints

Open an endpoint and use whichever view fits:

• Docs for reading — typed parameters, body fields, documented response codes, a cURL snippet, and inline Try it.
• Form for building — Params / Headers / Body / Auth / Tests tabs.
• Editor for a runnable .http buffer with spec-aware completion.

Bodies are pre-filled from the request schema. Where you have sent that endpoint successfully before, Tinspec can also fill from a real send: 2xx request bodies from your own history, ranked by recency and whether their tests passed, with secrets scrubbed out and replaced by {{placeholders}}. It is offered in the Body autofill menu and as Send with last successful in Docs view.

4. Review what changed

Open Spec Changes after a deploy. It lists endpoints added, removed, and modified since you last acknowledged, and expands a modified one to show the change field by field. A removed endpoint keeps its last-known shape so you can still see what it was.

Mark things seen explicitly — per row, per provider, or all. Opening an endpoint does not acknowledge it.

Copy a subset of the spec

Tick endpoints (or a whole tag group) and copy a minimal, valid OpenAPI document containing just those operations, their path-level parameters, every transitively referenced schema, and the security schemes. Choose YAML or JSON.

This is the right thing to paste into a ticket, attach to a review, or hand to an agent — far better than a 40,000-line document or a screenshot.

5. Keep your edits

Edit a generated endpoint and Tinspec records an overlay: the field groups that differ from the generated request, stored as YAML in .tinspec/overlays/<provider-id>.yaml and re-applied on every refresh. The editor shows an Edited chip and a Reset to spec action.

Three things to know:

1. An overlaid group replaces the generated one wholesale — it is not a field-level merge.
2. URL and method cannot be overlaid; they are the endpoint’s identity.
3. If the spec changes underneath your edit, you get an amber banner: Keep edits or Reset to spec. Nothing merges silently.

Overlays are committable, so a teammate who pulls your project gets your endpoint tweaks. They need a project folder; a folderless project keeps them for the session only.

Turning an endpoint into a saved request

Save as request forks the endpoint into a collection. The copy is yours: it no longer tracks the spec, and no overlay applies to it. Do this for a reproduction case you want to keep stable; use an overlay when you want your change to follow the endpoint as it evolves.