The Problem We Kept Seeing

Before building Specway, I spent years working with API teams — as a developer consuming APIs and as a product engineer building them. One pattern repeated everywhere: developers struggle to find specific answers in documentation, even when the answer is clearly written somewhere in the docs.

The problem is not bad documentation. The problem is that documentation is organized by endpoint, but developers think in terms of tasks. A developer does not want to browse all 47 endpoints in your user management section. They want to know: "How do I invite a user to a workspace and assign them a role?"

Answering that question might require three different endpoints, specific header values, and a particular sequence of calls. No amount of better sidebar navigation solves this. Traditional search helps somewhat, but only if the developer uses the exact terms that appear in the docs.

This is why we built an AI chatbot into every Specway documentation site.

How It Works

The chatbot is not a generic language model pasted onto a docs page. It is specifically trained on the API it serves. Here is what makes it different:

Spec-Aware, Not Just Text-Aware

Most AI documentation assistants work by indexing the rendered text of your docs and performing retrieval-augmented generation (RAG) against that text. This works for content questions ("What is your rate limit policy?") but fails for structural questions.

Specway's chatbot ingests the full OpenAPI spec — every endpoint, parameter, schema, enum value, and relationship. It understands the API at a structural level, not just a textual one.

This means it can answer questions like:

• "Which endpoints accept the workspace_id parameter?" — It searches the spec structure, not keyword-matches against rendered text.
• "What is the difference between PATCH /users/{id} and PUT /users/{id}?" — It compares the two endpoint definitions and explains the semantic difference.
• "Show me how to paginate through all invoices created this month" — It identifies the correct endpoint, the pagination parameters, and the date filter format, then generates working code.

Code Sample Generation

When a developer asks a "how do I" question, the chatbot responds with a code sample in their preferred language. These samples are generated from the actual endpoint definition — correct URL, correct parameters, correct auth header — not approximated from a generic template.

Developer: "How do I upload a file to a project?"

Chatbot: "Use POST /v1/projects/{project_id}/files with a multipart/form-data body.
Here's an example in Python:"

---

import requests

response = requests.post(
    "https://api.example.com/v1/projects/proj_abc/files",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    files={"file": open("report.pdf", "rb")},
    data={"description": "Q1 report"}
)

print(response.json())

The code is accurate because it is generated from the spec, not from a model's general training data.

Error Diagnosis

When a developer pastes an error response into the chat, the bot can cross-reference it against the spec's error definitions and suggest fixes:

Developer: "I'm getting this error: { "code": "invalid_scope", "message": "The requested scope is not available for this client" }"

Chatbot: "The 'invalid_scope' error means your OAuth client doesn't have access to the scope you requested. Check your OAuth application settings and ensure the required scopes are enabled. The available scopes for this API are: read:users, write:users, read:projects, write:projects, admin."

What It Does Not Do

Transparency matters, so here is what the chatbot intentionally does not do:

• It does not make API calls. The chatbot generates code and explains endpoints, but it does not execute requests on behalf of the developer. The interactive playground handles that.
• It does not answer questions outside the API. If someone asks about your company's pricing or support hours, the chatbot will say it only knows about the API. This is deliberate — a focused tool is more trustworthy than one that tries to answer everything.
• It does not hallucinate endpoints. Because it works from the spec, not from general training data, it will tell a developer when an endpoint does not exist rather than inventing one.

Why Not Just Better Search?

We considered improving traditional search instead of building a chatbot. Here is why we went further:

Search requires the developer to know what to search for. If the endpoint for removing a team member is called DELETE /v1/memberships/{id}, a developer searching for "remove user from team" will not find it. The chatbot understands the intent and maps it to the correct endpoint.

Search returns documents, not answers. A search result takes you to a page where you still have to read and find the relevant section. The chatbot gives you the answer directly — endpoint, parameters, code sample — in one response.

Multi-step workflows are invisible to search. Many API tasks require calling multiple endpoints in sequence. Search cannot surface a workflow; the chatbot can.

Early Results

Since launching the AI chatbot across Specway documentation sites, we have observed:

• Developers who use the chatbot view 3x more endpoint pages per session than those who browse manually. The chatbot acts as a guide, pointing developers to endpoints they would not have found through navigation alone.
• Support ticket volume drops measurably for teams that enable the chatbot. The most common support question — "How do I do X?" — is exactly what the chatbot handles best.
• Code sample generation is the most-used feature. Developers use the chatbot as a code assistant more than as a documentation search tool.

These are early numbers from a limited sample. We will share more detailed data as the feature matures.

The Broader Trend

We are not the only ones adding AI to developer tools — GitHub Copilot, Cursor, and others have shown that developers readily adopt AI assistance when it is accurate and contextual. The key word is "contextual." A generic chatbot that has read the internet is less useful than one that deeply understands a specific API.

We believe every API documentation site will have an AI assistant within two years. The question is whether it will be a shallow text search wrapper or a spec-aware tool that genuinely understands the API. We are building the latter.

Try It

If you have a Specway doc site, the chatbot is available on every page — look for the chat icon in the bottom right corner. If you do not have a Specway site yet, import your OpenAPI spec (it takes under three minutes) and try asking the chatbot a question about your API. The answers might surprise you.