API product website content checklist

An API product site has to show a working request and response, explain how to get a key and state limits, prices and uptime in plain terms. Most delays come from docs owned by engineering, SLA figures and unclear rate limits.

8 pages42 requests28 requiredAnswered by the API product manager or head of platform

Where to start

  1. Reference and docs. Docs belong to engineering and set how the site links out, so settle ownership before design.
  2. Getting started. The key setup and first call need testing on a clean machine, which takes engineering time.
  3. Pricing and limits. Units, limits and overage rules need product and finance agreement and shape the plan layout.
  4. Reliability and status. SLA wording requires legal review, so send it early.
  5. Use cases. Customer stories need permission, so ask while the rest is being built.

The checklist

Home

Developers and their managers land here to decide whether to try the API, and a real request and response convinces faster than a feature list.

  • API name and one-line pitch Short text, requiredThe product name and what a developer gets back, for example 'Address validation for checkout forms, one request per address.'
  • Base URL and current version Short text, requiredThe production base address and the current version label, such as v2. Copy it from the live docs so there is only one version of the truth.
  • Hero request and response example Long text, requiredOne curl call and the JSON that comes back, trimmed to fit a screen. Run it against the live API before sending it.
  • Primary action Single choice, requiredPick the first step most visitors should take. The page is built around it.Get an API keyRead the docsTry the sandboxTalk to sales
  • Signup address Link, requiredWhere a developer creates an account and sees a key. Test that a new signup reaches a key in under five minutes.

Use cases

Buyers need to see their own problem, so each use case should name the customer, the endpoint and the outcome.

  • Top use cases Long text, requiredThree to five, each with the customer type, the endpoints it uses and the result. Write from real customers, not from what the team hopes to sell.
  • Industries served Multiple choiceTick the sectors with live customers today. Each gets a short section only if you can name a use case.FintechEcommerceLogisticsHealthcareTravelMediaPublic sector
  • Customer stories File uploadCase studies as PDF or Word, each approved by the customer in writing. If none exist, name two customers who might agree.
  • Customer logos and permission Yes or no, requiredConfirm each logo shown has written permission from the customer. Send the logo files as SVG or PDF.
  • Architecture or flow diagram File uploadA diagram showing how a customer's system calls the API. SVG or an editable file is best.

Reference and docs

Reference docs are generated from the spec and owned by engineering, so the site has to link to them and match their look.

  • API reference address Link, requiredThe live reference. Say which tool builds it, such as Redoc, Swagger UI or Stoplight, and who can change its theme.
  • OpenAPI specification file File uploadThe current OpenAPI or similar spec as JSON or YAML. The designer uses it to pull endpoint names and check examples.
  • Client libraries Multiple choice, requiredTick each official SDK that is maintained today, and add links in the next field.JavaScript or TypeScriptPythonRubyGoJavaPHPC# or .NETNone, REST only
  • SDK repository links Long textThe address of each SDK repository or package page, with the latest version. Remove any that are no longer maintained.
  • Postman collection or sandbox LinkA shared collection or a browser sandbox a developer can use without code. Check it needs no login.
  • Docs ownership Short text, requiredWho approves changes to the docs and how long a request takes. The site depends on them for styling and links.

Getting started

A developer who cannot make a first call in minutes leaves, so authentication and key setup need clear, tested steps.

  • Authentication method Single choice, requiredPick how requests are authenticated today. The page explains it in one paragraph and links to the reference.API key in a headerOAuth 2.0JWT bearer tokenMutual TLSMore than one
  • How to get a key Long text, requiredThe steps from signup to a working key, in order, with any approval delay. Say whether a card is needed.
  • First call tutorial Long text, requiredFive steps or fewer from key to a first useful response, with the expected output at each step. Test it on a clean machine.
  • Sandbox or test mode Yes or no, requiredSay whether a developer can test without real data or charges. If yes, add the sandbox base address and how it differs from production.
  • Error format and common errors Long textShow one error response and list the five codes developers meet most. Link to the full list.

Pricing and limits

Pricing for APIs is confusing because there are several units, so the page must state what is counted and what happens at the limit.

  • Pricing unit Single choice, requiredPick what a customer is charged for. The page headline follows from it.Per requestPer credit or tokenPer seatPer record or objectFlat monthly planCustom contract
  • Plans and prices File upload, requiredA table with each plan, price, included volume, currency and billing period. Mark the plan to highlight.
  • Rate limits by plan Long text, requiredRequests per second or minute for each plan, burst rules and the headers returned when a limit is hit. Check them against the gateway settings.
  • Free tier or trial terms Long textThe free volume, how long it lasts and what happens when it runs out. State if a card is required.
  • Overage and cancellation rules Long text, requiredWhat a customer pays beyond the plan and how they cancel. Match the wording to your terms of service.
  • Do prices go on the website Yes or no, requiredIf no, say what the page shows instead and who answers the sales form.

Reliability and status

Production teams check uptime history before depending on an API, and this is where marketing figures get ahead of the real record.

  • Status page address Link, requiredThe public page for incidents and uptime. Link to it from the footer and the docs.
  • Uptime commitment Short textState a figure only if it appears in a signed SLA you offer. Include which plans receive it.
  • Service level agreement document File uploadThe standard SLA as a PDF, with remedies for missed targets. Have legal confirm it is the current version.
  • Regions and data hosting Multiple choiceTick where the API serves traffic from today. Buyers use this to answer data residency questions.North AmericaEuropeAsia PacificSingle region onlyCustomer-chosen region
  • Incident communication process Long textHow customers are told about an outage, who posts it and how fast. Describe what the team does today.

Versioning and support

Teams building on an API worry about breaking changes, so the page should state how long a version lives and where news appears.

  • Versioning and deprecation policy Long text, requiredHow versions are numbered, how long an old version is supported and how much notice you give. Use the rule the team follows.
  • Changelog address Link, requiredThe page that lists releases and breaking changes. Say how it is formatted so the site can show the latest entry.
  • Support channels and hours Multiple choice, requiredTick each channel a customer can use, by plan if it differs.EmailChatPhoneCommunity forumShared Slack channelDedicated engineer
  • Developer community LinkThe Discord, forum or GitHub Discussions where developers get help from each other and from staff.

Security, legal and brand

Procurement and legal teams review these items before signing, and engineering teams care about the logos they can use in diagrams.

  • Security certifications held Multiple choice, requiredTick only what you hold today with a report you could share. Check the rules where you operate before using any badge.SOC 2 Type IIISO 27001PCI DSSHIPAA supportData processing agreement availableNone yet
  • Security disclosure contact Short text, requiredThe address for reporting a vulnerability and the policy that governs it.
  • Terms, acceptable use and privacy Link, requiredThe live addresses of the terms of service, the acceptable use policy and the privacy policy. If one is a draft, name who finishes it.
  • Data processing agreement File uploadThe template DPA a customer can sign. Ask legal whether it can be shown publicly.
  • Logo and brand files File upload, requiredSVG logos in colour and white, plus the symbol alone. Developers use these in their own diagrams.
  • Brand colours Colour, requiredHex codes for the main colour, accent and code highlights. State if the docs use a different palette.

What clients get stuck on

A request example that fails

Examples on slides use old fields or test keys. Ask an engineer to run every curl example against production, and paste the real output with a date.

SLA figures ahead of the contract

Marketing wants a number such as an uptime percentage, while the legal team has not signed one. Ask for the SLA document and quote only what it says.

Rate limits that vary in the gateway

The documented limit and the gateway setting often differ. Ask the platform team for the actual configuration per plan and compare it with the page.

Docs in a separate system

Reference docs are generated and sit on their own domain. Agree in week one whether the site links to them or restyles them, and who owns each choice.

Customer names that cannot be shown

Enterprise contracts often forbid naming customers. Ask account managers which logos have written permission and replace the rest with industry descriptions.

Copy the checklist

Plain Markdown you can paste into a doc or an email.

# API product website content checklist

## Home
- [ ] API name and one-line pitch (Short text, required)
- [ ] Base URL and current version (Short text, required)
- [ ] Hero request and response example (Long text, required)
- [ ] Primary action (Single choice, required)
- [ ] Signup address (Link, required)

## Use cases
- [ ] Top use cases (Long text, required)
- [ ] Industries served (Multiple choice)
- [ ] Customer stories (File upload)
- [ ] Customer logos and permission (Yes or no, required)
- [ ] Architecture or flow diagram (File upload)

## Reference and docs
- [ ] API reference address (Link, required)
- [ ] OpenAPI specification file (File upload)
- [ ] Client libraries (Multiple choice, required)
- [ ] SDK repository links (Long text)
- [ ] Postman collection or sandbox (Link)
- [ ] Docs ownership (Short text, required)

## Getting started
- [ ] Authentication method (Single choice, required)
- [ ] How to get a key (Long text, required)
- [ ] First call tutorial (Long text, required)
- [ ] Sandbox or test mode (Yes or no, required)
- [ ] Error format and common errors (Long text)

## Pricing and limits
- [ ] Pricing unit (Single choice, required)
- [ ] Plans and prices (File upload, required)
- [ ] Rate limits by plan (Long text, required)
- [ ] Free tier or trial terms (Long text)
- [ ] Overage and cancellation rules (Long text, required)
- [ ] Do prices go on the website (Yes or no, required)

## Reliability and status
- [ ] Status page address (Link, required)
- [ ] Uptime commitment (Short text)
- [ ] Service level agreement document (File upload)
- [ ] Regions and data hosting (Multiple choice)
- [ ] Incident communication process (Long text)

## Versioning and support
- [ ] Versioning and deprecation policy (Long text, required)
- [ ] Changelog address (Link, required)
- [ ] Support channels and hours (Multiple choice, required)
- [ ] Developer community (Link)

## Security, legal and brand
- [ ] Security certifications held (Multiple choice, required)
- [ ] Security disclosure contact (Short text, required)
- [ ] Terms, acceptable use and privacy (Link, required)
- [ ] Data processing agreement (File upload)
- [ ] Logo and brand files (File upload, required)
- [ ] Brand colours (Colour, required)

Questions about this checklist

Should API documentation sit inside the marketing site?

Keep it in its own tool, usually on a docs subdomain, and share the header and colours. The marketing site then links to a few featured pages and a search box.

Is it fine to show a sample response with made-up data?

Yes, if the shape matches what the live API returns. Run the real call and replace values with realistic placeholders, and never show a real customer's data.

What should an API pricing page show?

The unit you charge for, the included volume, the limits and what happens above them. A calculator helps, as long as it matches the invoice a customer would actually get.