API documentation written from your OpenAPI description, not from guesses

Developers judge an API by its documentation before they write a line of code. They want to authenticate, make a first call, understand every error and know what happens when the API changes. INKFLOW drafts API reference documentation and technical integration specifications for the people who will build against your product.

Order it as a technical specification and say 'API documentation' in the brief. The writer works from guidance for API references and asks for the material such a reference depends on: your OpenAPI or other machine-readable description, environments and base URLs, authentication and scopes, the error catalogue, rate limits, pagination, webhooks and the versioning policy.

Your description file is treated as the source of truth. Behaviour your material does not describe, such as a status code an endpoint might return or a webhook retry schedule, is left as a marked placeholder. Example requests use placeholder credentials and sandbox addresses, and your engineers review the draft before it is published.

Start API documentation

Preparing an API reference for the writer

1
Say what kind of document it is
Reference documentation for an API that already exists, or a requirements specification for a procurement or a contract. The two are written differently.
2
Paste in the description and the rules
Your OpenAPI description, the auth scheme with token lifetimes and scopes, rate limits and the headers that report them, pagination style and idempotency keys.
3
Describe the real behaviour
Side effects, every status code an operation can return, the error format with the client action for each, webhook events and how signatures are verified.
4
Review with the engineers who built it
There is a price on the order page before payment. Engineers then check each section against the running API, and you publish it in your own developer portal.

Sections of the API documentation

Getting started

How to obtain sandbox credentials, the base URL for each environment and a first call, so nobody tests against production by mistake.

Authentication explained once

The scheme, how tokens are obtained and refreshed, and what each scope allows, in one place every endpoint links back to.

Endpoint reference

Each operation with parameters, request and response bodies, side effects and status codes, consistent with the description file.

Errors a client can act on

The error format, each code, what it means and what the client should do next.

Webhooks and events

Event types, payload schemas, retry behaviour, ordering and signature checks.

Versioning and change

Your version scheme, compatibility promise, deprecation notice and sunset process, plus a changelog that flags breaking changes.

What the API documentation writer does not do

It does not call your API, generate SDKs, host a portal or produce an OpenAPI file from your source code. If your description file is out of date the documentation will be too, so reconcile them first.

Fields that carry personal data are marked as such when your data model says so. Whether your API meets data protection law is a question for your own advisers, not for the documentation.

Questions

Which kinds of API does it handle?

The guidance centres on HTTP APIs with a machine-readable description, OpenAPI being the usual one. If yours is described another way, include that description and say what it is.

Will the code examples run?

They are written from your description and use placeholders for keys and sandbox addresses. Nothing is executed on our side, so engineers should run each one against the sandbox before publishing.

Can it write a specification for an API we have not built yet?

Yes, as a requirements specification for procurement or a contract. Say so in the brief; decisions you have not made are left open as placeholders.

What about help for the people using our product?

That is a different document. The software user guide page covers help centre articles for end users rather than developers.

Do prices include VAT?

Prices include any VAT; nothing is added at checkout.

We are an organisation. How can we pay?

Single orders are paid by card at checkout. For subscriptions and repeat orders, care homes, councils and businesses can ask about paying by Direct Debit or standing order at app.inkflowstudio.org/organisations.

More from INKFLOW

An AI user manual generator for software and SaaS help centres An AI runbook generator for on-call engineers AI technical manual writer AI SOP generator for company manuals and standard operating procedures Complete books and series Everything INKFLOW writes