docs(openapi): widen API title/description to full bundle + AI-agent/MCP framing (discoverability)#244
Merged
Merged
Conversation
…MCP framing The OpenAPI info block — the first thing an AI coding agent fetches to decide what the API does — only mentioned "databases, caches, and queues" and a generic "InstaNode API" title. It omitted pgvector/vector, object storage, webhooks, and the headline deployment wedge, plus any AI-agent / MCP / free-tier / single-HTTP-call framing. Framing-only change (no path/parameter/schema contract edits): - info.title → "instanode.dev — zero-friction dev infrastructure for AI agents" - info.description widened to lead with the keywords agents match: Postgres, pgvector/vector, Redis, MongoDB, NATS queues, S3 storage, webhooks, AND app deployment — each a single HTTP call, no account/Docker/setup; free anon tier; also MCP server + SDKs + CLI. Accurate to the live router surface. - Added a top-level tags[] block describing each service family (database/vector/cache/nosql/queue/storage/webhook/deploy/auth). - Regenerated openapi.snapshot.json (description is content, so the canonical snapshot changed; drift check passes). No paths, parameters, or schemas added/removed/renamed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
internal/handlers/openapi.gois the first thing an AI coding agent fetches (GET /openapi.json) to decide what the API does. The top-levelinfoblock undersold the product:"InstaNode API".This indexed instanode for a subset of the bundle. Discoverability audit flagged it.
Fix (framing-only — no endpoint/schema contract change)
Before:
InstaNode APIZero-friction developer infrastructure. Provision real databases, caches, and queues with a single HTTP call — no account, no Docker, no setup.After:
instanode.dev — zero-friction dev infrastructure for AI agents*/newpaths present) and CLAUDE.md "Live API surface".Also added a top-level
tags[]block (the spec previously had none) describing each service family: database / vector / cache / nosql / queue / storage / webhook / deploy / auth.No paths, parameters, or schemas were added, removed, or renamed. The
## Idempotency / Rate limit / Payload size / Security headersdescription sections are untouched.Tests / gates
make openapi-snapshotregeneratedopenapi.snapshot.json(the description is content, not whitespace, so the canonical snapshot changed). A snapshot update WAS required.make openapi-snapshot-check→ passes (snapshot matchesOpenAPISpecProduction()).go test ./internal/handlers/ -run OpenAPI -short→ green, incl.TestOpenAPISpecParses+TestServeOpenAPI_*(proves the edited spec still parses as valid JSON and serves at/openapi.json).go test ./cmd/openapi-snapshot/→ green.go vetclean;gofmt(real$(go env GOROOT)/bin/gofmt) on the changed file only.Rule 22 (contract↔docs sync) follow-up
The widened framing should be echoed by
content/llms.txt(source of truth, synced intoinstanode-web/public/llms.txtat build) and the marketing site's hook. Those live in separate repos (content+instanode-web) and are intentionally NOT touched here — file as a follow-up PR.🤖 Generated with Claude Code