Skip to content

docs: front-load API contract on landing and api reference#31

Open
brunobuddy wants to merge 1 commit into
mainfrom
docs/api-contract-clarity
Open

docs: front-load API contract on landing and api reference#31
brunobuddy wants to merge 1 commit into
mainfrom
docs/api-contract-clarity

Conversation

@brunobuddy
Copy link
Copy Markdown
Member

Summary

The cloud base URL, auth header, key prefix, and manifest/auto model identifier are spread across multiple pages. An LLM helping a user integrate has to chain through several files just to assemble a working request — and the most common hallucination ("can I pass gpt-4o-mini directly?") is never explicitly refuted.

This is a surgical contract-clarity pass on two files. No marketing/positioning changes, no restructure.

  • introduction.mdx — add a Quick reference table at the top: cloud base URL, self-hosted base URL, auth header, key acquisition link, the only accepted request model, both endpoint paths, and a note that no client SDK is needed (use openai / @anthropic-ai/sdk with baseURL set).
  • reference/api.mdx
    • Make the cloud curl the primary sample; self-hosted follows. The previous sample only showed http://localhost:2099, which silently breaks anyone integrating with the cloud.
    • Add a Model identifier callout next to chat completions: manifest/auto is the only accepted value; provider-specific names like gpt-4o-mini or claude-sonnet-4 are rejected. This closes the highest-frequency hallucination.
    • Expand the Authentication section into the three explicit steps (sign up → create agent → pass mnfst_<key>), with the M003 link surfaced.

Test plan

  • Mintlify preview renders the Quick reference table on /introduction above the feature cards
  • The new cloud curl block on /reference/api is the first sample under "Chat completions"
  • The M003 link resolves to /errors/M003
  • /llms-full.txt now contains the Quick reference (it's pulled from introduction.mdx)

The cloud base URL, auth header, key prefix, and `manifest/auto` model
identifier were spread across multiple pages — an LLM helping a user
integrate had to chain through several files. Pull the contract up to
the landing page and make the API reference cloud-first.

- introduction.mdx: add a Quick reference table at the top with base
  URLs, auth, model identifier, and endpoints
- reference/api.mdx: cloud curl first then self-hosted; add a Model
  identifier callout stating manifest/auto is the only accepted value;
  expand the Authentication section into explicit signup → create
  agent → pass mnfst_ steps with an M003 link
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant