Specification, documentation, definition: which one are you writing?
People swap these three words all the time, and that confusion is a big reason the page stays blank. A practical split works like this. Documentation is the reference manual developers use to work with an API. A specification describes how the API behaves and what callers should expect. A definition is the machine-readable version that tools turn into docs, code samples and SDKs.
Many teams end up keeping two things. One is a definition file, commonly in the OpenAPI format. It's written as JSON or YAML and must include an openapi version field, an info object, and at least one of paths, components or webhooks. The other is a page that people actually review. Starting with the file makes sense if your team already reads YAML comfortably. The page below is for the earlier conversation, with the people who don't.
A worked example: booking meeting rooms at a fictional library
The sample spec describes a made-up API for the meeting rooms at Larkspur Branch Library, a fictional library. It covers four jobs: listing the rooms, checking a room's availability, creating a reservation and cancelling one. Every name, path and value is invented. No service runs behind it, and the page sends no requests.
Three habits in it are worth copying. First, every endpoint gets a method, a path, a one-line purpose and an operation ID. In the OpenAPI format, an operation ID must be unique across the whole API and is case-sensitive. Following that rule in a prose spec gives each endpoint a stable name that people can use in tickets and chat threads.
Second, paths use curly braces for the parts that change, as in /rooms/{roomId}/availability. Each of those placeholders has to match a documented path parameter. The parameter table also says where every other input goes. The format allows five locations (path, query, querystring, header and cookie), and a reviewer can't judge a design until they know which one you mean.
Third, responses are listed by status code, including the case nobody planned for. The format lets you describe a 200 for success and a default response for everything else. For reservations, the sample also spells out the double-booking conflict that a front-end developer will need to show on screen. It ends with a list of open questions, so reviewers can see what isn't settled yet.
Building your own page, with or without AI
The facts have to come from you: endpoints, fields, rules and the decisions still pending. AI helps with the other half, turning rough notes into a structured page with consistent tables. If you'd rather skip AI, the same headings work in any document editor.
The prompt below asks for a single HTML file. That's a web page whose text, layout and styling all live in one file, so you can open it in a browser and share it as a page. Replace each bracket with your own details. The examples inside the brackets come from the fictional library API.
Before anyone else sees the result, check it against your notes. Delete any field, status code or rule you didn't supply, because a reviewer will build against an invented field as readily as a real one.
After review: fixing the page everyone already has
Say you share the page with the developer building the booking screen. They reply that cancellation should return 204 with no body, and that the 409 conflict response should name the time block that's already taken. Neither change needs a fresh AI pass.
If the page lives in NOS, you edit the rendered text directly. You change the cancellation response, add the detail to the 409 entry and record both in the change log. The sharing link stays the same after edits, so the link already in the ticket now opens the corrected spec. Reviewers can open it without creating an account, and you can keep your review notes as notes or subpages in the same workspace as the spec.
Two limits keep this honest. Editing the page changes its words, not your API or your definition file, so you have to update those yourself to keep everything in sync. And if a partner or a process asks for an OpenAPI file or a PDF, send that. A link helps the discussion, but it doesn't replace a required file.
A prompt to adapt
Create a single self-contained HTML page that presents an API specification for human review. Use only the facts I list below. Do not add endpoints, fields, parameters, status codes, authentication methods or business rules I have not given you. If something is missing or unclear, list it under 'Open questions' instead of guessing.
API name: [API NAME, e.g. Larkspur Library Room Booking API]
One-sentence purpose: [WHAT CLIENTS CAN DO, e.g. lets the library website and staff app list rooms, check availability and manage reservations]
Spec version and date: [VERSION, DATE, e.g. v0.3 draft, 2026-10-12]
Base URL: [BASE URL or 'not decided']
Authentication: [METHOD or 'not decided']
Endpoints, one per line (method, path, one-line purpose, operation ID): [LIST, e.g. POST /reservations, create a reservation, createReservation]
Parameters per endpoint (name, location: path/query/header/cookie, type, required yes/no, notes): [LIST, e.g. roomId, path, string, yes, room slug such as studio-b]
Request body fields per endpoint (name, type, required, notes): [LIST]
Responses per endpoint (status code, meaning, short example body): [LIST, e.g. 409, time block already booked, returns nextAvailableStart]
Business rules: [LIST, e.g. reservations start on the half hour]
Open questions: [LIST]
Change log entries: [LIST]
Page structure: title and version line; short overview (purpose, base URL, authentication, date and time format); endpoint summary table; one section per endpoint with its parameters table, request body, responses and an example request and response in code blocks; error reference; open questions; change log.
Requirements:
- Mark the page clearly as a draft specification for review. It must not contain forms, buttons or scripts that send requests or pretend to call the API.
- Every path placeholder in curly braces must have a matching row in that endpoint's parameters table.
- Operation IDs must be unique. Flag any duplicates in my input under Open questions.
- Use semantic HTML: one h1, headings in order, real table elements with header cells, and code in pre/code elements.
- Use high contrast between text and background, don't rely on color alone to show meaning, and give visible focus styles to links.
- Make the page readable on a phone about 360px wide. Wide tables and code blocks scroll horizontally inside their own container, and the page itself never scrolls sideways.
- Load no external fonts, scripts or other network resources.