How to design request and response schemas in APIKumo for cleaner, self-documenting APIs

Raw JSON responses in API documentation tell readers what an endpoint returns, but they rarely explain why. A field called status could be a string, an enum, a boolean disguised as a number — the consumer has no way to know without reading source code or asking you directly. Structured schemas fix this. In APIKumo, the schema editor lets you annotate every request and response shape with field names, types, enums, and worked examples, and those annotations flow straight into your published docs site without any extra writing. This post walks through the full workflow, from opening the editor to shipping documentation your consumers will actually trust.

When a docs page shows only a captured response body, readers are forced to reverse-engineer your API from a single snapshot. A few problems with that approach:

• One example, infinite edge cases. The sample you captured probably doesn't show nullable fields, optional keys, or the full range of an enum.
• Types are ambiguous. JSON doesn't distinguish between an integer ID and a string ID that happens to contain digits. A schema makes the contract explicit.
• Enums go undocumented. If order.state can be pending, fulfilled, or cancelled, a reader has no way to discover that from a single example.
• Docs drift. A pasted blob goes stale the moment the shape changes. A schema you maintain alongside the request stays in sync because it lives in the same workspace.

APIKumo's structured schema editor is designed to solve all of these — with as little friction as possible.

Every saved request in a collection has two schema slots: one for the request body and one for the response. To reach them, open any saved request and switch to the Schema tab alongside Headers, Body, and Pre/Post processors.

You'll see two expandable panels — Request Schema and Response Schema — each starting empty. You can build a schema from scratch using the field editor, or paste in an existing JSON example and let the editor infer a baseline structure that you then refine.

If you're migrating from an OpenAPI spec or a Postman collection, the imported data already populates these panels wherever schema definitions were present in the source file, so you don't start from zero.

Each field in the editor has four core properties:

For string fields you can additionally specify an enum — a comma-separated list of the only values the API will accept or return. For example, an order.state field might have:

enum: pending, processing, fulfilled, cancelled

The published docs page renders this as a labelled list, so consumers know immediately that shipped is not a valid value and won't build a branch around it.

For array and object types you can nest child fields. An object type reveals an Add child field button; an array type lets you define the shape of each item. This nesting can go as deep as your payload warrants — a common pattern is a top-level data object containing a results array of order objects, each with its own nested address object.

Every field accepts one or more example values. These are distinct from the live response captured when you last sent the request — they're curated illustrations of what a realistic value looks like.

Good examples make a material difference to developer experience:

• An email field with the example ada@example.com is clearer than one with string.
• A created_at field with 2024-11-03T09:15:00Z tells a reader the format is ISO 8601 UTC without needing a description sentence.
• An amount field with 1999 alongside the description "Amount in the smallest currency unit (e.g. cents)" prevents the classic off-by-100 integration bug.

Examples you add in the schema editor are composited into a synthetic example payload on the docs page. This is separate from the raw captured response and stays current even if you haven't sent the request recently — making it far more reliable as reference material.

Once a collection is published to your your-name.apikumo.com site, every saved request becomes a docs page automatically. The schema you defined appears in two places on that page:

1. Parameters and body section — request schema fields are listed with their types, required badges, enum values, and descriptions. Readers can scan the table without needing to construct a trial request.
2. Response section — the response schema appears alongside the latest captured response body. Readers see both the raw snapshot and the annotated contract, so they understand which fields are always present and which are optional.

No extra writing, no separate docs tool, no copy-pasting field tables into a Notion page. The schema editor is the documentation authoring step.

The Try-it panel on published docs pages also benefits: because the request schema is defined, the panel can show placeholder hints per field rather than an empty body editor, which lowers the barrier for readers to make their first successful call.

APIKumo's {{variable}} substitution works in schema example values the same way it works in request URLs and headers. If your base_url environment variable differs between staging and production, any example that references it resolves correctly for the active environment.

A common pattern is to store a representative resource ID in an environment variable and reference it in schema examples:

# Environment: Staging
SAMPLE_ORDER_ID = ord_staging_8f2a

# Field: id
Example value: {{SAMPLE_ORDER_ID}}

When a reader uses the Try-it panel against the staging environment, they see ord_staging_8f2a pre-filled rather than a generic placeholder. When you flip to production, the resolved value updates automatically — secrets never leak into the published docs because variable values are resolved at send-time, not stored in the collection.

Schemas change. Fields get added, types get tightened, enums grow. APIKumo's versions and changelog feature lets you snapshot a collection at any point, continue editing the next version safely, and surface a diff to readers when you ship.

A practical workflow:

1. Snapshot v1 of your collection once the initial schema is stable.
2. Add the new refund_reason field to the response schema, mark it optional for now.
3. Snapshot v2 and write a one-line changelog entry: "Added optional refund_reason field to order response."
4. Publish. Readers see the version selector and the changelog entry — no guessing what changed between integrations.

This is especially valuable if consumers have built client code against your docs. A visible changelog entry about a new required request field is the difference between a smooth upgrade and a silent 400 error in production.

The structured schema you build in APIKumo isn't locked in. From your published subdomain you can export:

• OpenAPI 3 export — a fully formed spec with components/schemas entries populated from your field definitions, ready to feed into code generators, gateway validators, or linting pipelines.
• Markdown docs export — a flat Markdown file with all schema tables included, suitable for a GitHub wiki or a monorepo docs/ folder.
• llms.txt export — a machine-readable representation of your API surface that AI agents and LLM-powered tools can fetch directly from your-name.apikumo.com/llms.txt.

All three exports are reachable on the same subdomain without auth headers, so CI pipelines and AI agents can fetch them on demand.

A well-defined schema is the foundation of every other piece of APIKumo's docs pipeline. It feeds the published docs page, powers the Try-it panel, informs the AI chat assistant on your docs site, and produces valid OpenAPI output — all from the same editor you use to design and test the request itself.

The workflow is straightforward: open a saved request, fill in the schema fields with accurate types, a meaningful description, and at least one realistic example value, then publish. Your consumers get field-level documentation, enum constraints, and a synthetic example payload without you writing a single docs paragraph outside the tool. Start with your most-used endpoint, get the schema right, and the rest of the collection follows the same pattern.