PinkDocs has five blocks for API documentation. Together they turn a normal article into an API reference page like the ones from Stripe or Mintlify: the endpoint at the top, the parameters in the middle, and request and response examples in a column on the right that stays in view while readers scroll.
Want to see the result first? Open one of the sample pages: Create a ticket (POST), List tickets (GET) or Delete a ticket (DELETE).
The API blocks
| Block | What it shows |
|---|---|
| API Endpoint | The HTTP method as a coloured badge, the path and an optional base URL, with a button that copies the full URL. {placeholders} in the path are highlighted. |
| API Parameters | A titled list of parameters (for example Authentication, Path parameters, Query parameters or Body). Each one has a name, type, where it's sent, required, deprecated, a default and a description. |
| API Request Example | The same call in several languages (cURL, JavaScript, Python, PHP, Go, Ruby and more) as tabs, with syntax highlighting and a copy button. |
| API Response Examples | Example responses, one tab per status code. Each tab has a coloured dot: green for success, orange for client errors, red for server errors. |
| API Examples Column | Holds the request and response examples. On wide screens it becomes the sticky right-hand column. |
All five are in the block inserter under PinkDocs. Search for "API" to find them quickly.
Build an endpoint page
Create an article for the endpoint
Go to PinkDocs → Documents → Add New. Use one article per endpoint and name it after what it does, for example Create a ticket. Start with a sentence or two about what the endpoint is for.
Tip: put your endpoints in their own category, such as API reference, so they're grouped in the sidebar.
Add the API Endpoint block
Add API Endpoint under the intro. Pick the method from the badge (GET, POST, PUT, PATCH, DELETE…) and type the path, for example /v1/tickets/{ticket_id}.
In the block settings on the right you can add a Base URL such as https://api.example.com. It's shown in grey before the path and included when readers copy the URL. Turn on Deprecated for endpoints you plan to remove.
Add the examples column
Add API Examples Column. It starts with an empty API Request Example and API Response Examples inside it. Fill those in now or after the parameters (see the next two sections).
Add one API Parameters block per group
Add an API Parameters block for each group of parameters and set its title: Authentication for headers, Path parameters, Query parameters and Body.
For each parameter, fill in:
- Name and Type (
string,integer,boolean,string[],object…). - Sent in: header, path, query, cookie or body. Everything except Body is shown as a small chip in front of the name.
- Default, if the parameter has one.
- Description. Links and inline code (between backticks) are allowed.
- Required and Deprecated switches.
Use the arrows to reorder parameters and the bin icon to remove one.
Publish
Publish the article. In the docs sidebar the article now has its method in front of its title, so readers can scan your endpoints at a glance.
Request examples
Each tab of an API Request Example is one language. Choose the language and paste the code. cURL is the one most readers look for first, so keep it as the first tab.
When readers switch to another language, every request example on the page switches with them, and their choice is remembered on your other API pages.
For a POST endpoint with name and count body parameters, the generated examples look like this:
Response examples
Add one response per status code you want to show: usually the success response plus the errors readers are most likely to hit (400, 401, 404, 422, 429).
For each response, set the Status, an optional short Description (shown above the code, for example Missing or invalid API key), the Format (JSON, XML, HTML, YAML or text) and the Body. The editor warns you if the JSON isn't valid, and Format JSON indents it for you.
For responses with no body, such as 204 No Content, choose Text and write something like (empty body).
How the page is laid out
On screens 1280 pixels wide and more, the API Examples Column moves to the right of the article and stays in view while readers scroll through the parameters. It takes the place of the On this page list on that article. If the examples are taller than the screen, the column scrolls on its own.
On smaller screens there's no room for a second column, so the examples show where you placed the block in the article. That's why the best place for the examples column is right after the API Endpoint block: phone readers see the example call before the long parameter list.
Everything follows your knowledge base's brand colour, corner roundness and light/dark mode. Code examples use light colours in light mode and dark colours in dark mode.
Write API docs with AI
If you've connected PinkDocs to Claude, ChatGPT or another AI tool, your AI tool can write these pages for you. It knows every API block, so you can ask things like "Write an API reference article for POST /v1/tickets from this OpenAPI snippet" or "Turn this README section into endpoint pages".
Behind the scenes the AI writes Markdown with PinkDocs directives, and PinkDocs turns them into blocks. You can use the same syntax yourself when you import Markdown:
Each parameter is one list line: the name in backticks, then the type and optional flags in brackets, then a colon and the description. The flags can be combined:
| Flag | Meaning |
|---|---|
required | Shows the required label. |
deprecated | Shows the deprecated label. |
in=header, in=path, in=query, in=cookie | Where the parameter is sent (shown as a chip). Leave it out for body fields. |
default=value | Shows the default value. |
Tips for good API pages
- One endpoint per article. It keeps the examples column next to the parameters it belongs to, and each endpoint gets its own badge in the sidebar.
- Put the examples column right after the endpoint, so phone readers see an example call before the parameter list.
- Start with cURL. It's the language every developer can read, and it's the one most people copy.
- Use realistic values in examples (
jane@example.com,tkt_8f2a91) rather thanstringorfoo. Never paste a real API key: use a placeholder likeYOUR_API_KEY. - Show the errors readers will hit, with a one-line description each. Add a short Errors section with a table if you have more to say.
- Write nested fields with a dot, for example
requester.email.
Frequently asked questions
Not yet. The examples are for reading and copying. A "Try it" button is planned for a later version.
No. Without it, the article keeps its normal On this page list. You can also use API Request Example and API Response Examples on their own anywhere in an article.
Yes. They all share the reader's language choice, so switching to Python in one switches all of them.
Not yet; it's planned. Until then, connect an AI tool over MCP and ask it to write the pages from your OpenAPI file: it uses the API blocks automatically.
The badge comes from the article's API Endpoint block. Check that the article has one and that you saved it after adding the block.