fix(api): OpenAPI contract corrections — servers URL, resource_type/status/tier enums, provisioning envelope#103
Merged
Conversation
Wave FIX-E spec drift cleanup. Eight findings against the agent-facing OpenAPI doc, none of which broke runtime behavior but every one of which silently misled an agent trying to read the spec to discover what to do next: * servers[0].url was https://instant.dev (dead-brand 404). Now https://api.instanode.dev. #C1 * resource_type enum on ResourceItem AND the inline duplicate inside ClaimPreviewResponse listed "nats" (never written to the column — handlers emit "queue") and was missing "vector" entirely. Hoisted ClaimPreviewResponse.resources[] to $ref ResourceItem so the two enums can't drift again. #C9 * DeployResponse.item.status and DeployItem.status missed the intermediate "deploying" state the worker writes — strict-validating agents would reject poll responses. #C10 * TeamSummaryResponse.tier enum stopped at {anonymous,free,hobby,pro,team} but the live teams.plan_tier column carries hobby_plus, growth, and *_yearly variants — a dashboard that validated against this enum would reject every Plus / yearly customer. #C11 * ErrorResponse didn't document claim_url, which the free_tier_recycle_requires_claim envelope writes on the wire. #C12 * GET /start was documented as a 200 HTML page; the handler issues a 302 redirect to the dashboard's /claim page. Spec now declares 302 + the Location header. #C13 * upgrade_jwt was documented in llms.txt but missing from every provisioning response schema. Added to DB, Cache, NoSQL, Queue, Storage, Webhook, Vector responses so an agent reading the OpenAPI alone discovers the field instead of falling back to URL-stripping (which the policy memory explicitly says we do not want). #C17 openapi_test.go gains seven new gates so a future "let's tidy the schema" PR can't re-drop any of these without a CI fail. Stretching the contract surface, not the runtime — zero handler code changed. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
FIX-A added hobby_plus + growth to the tier enum. This branch's version also adds the *_yearly variants. Kept the superset (this branch's set) which includes everything from both PRs.
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.
Summary
Wave FIX-E OpenAPI spec drift cleanup. Eight findings against the agent-facing OpenAPI doc — none broke runtime behavior, but every one silently misled an agent reading the spec to discover what to do next.
servers[0].urlwashttps://instant.dev(dead-brand 404). Nowhttps://api.instanode.dev. (api: RETRO-2026-05-12 follow-ups — openapi for cached aggregates + agent_action on 401 #24 / #C1)resource_typeenum onResourceItemAND the inline duplicate insideClaimPreviewResponselisted"nats"(never written to the column — handlers emit"queue") and was missing"vector"entirely. HoistedClaimPreviewResponse.resources[]to$ref(ResourceItem)so the two enums can't drift again. (resources: pause/resume endpoints (Pro+ tier) — suspend without deletion #60 / #C9)DeployResponse.item.statusandDeployItem.statusmissed the intermediate"deploying"state. (handlers: use plans.Rank + consolidate agent_action constants #61 / #C10)TeamSummaryResponse.tierenum was stuck on{anonymous,free,hobby,pro,team}but the live column carrieshobby_plus,growth, and*_yearlyvariants. (env: default to 'development' (not 'production') + API explicitly echoes resolved env on every response #63 / #C11)ErrorResponsedidn't documentclaim_url, which thefree_tier_recycle_requires_claimenvelope writes on the wire. (deploy: optional notify_webhook URL fires HTTP POST on deploy terminal state #62 / #C12)GET /startwas documented as a 200 HTML page; the handler issues a 302 redirect to the dashboard's/claimpage. Spec now declares 302 + theLocationheader. (#C13)upgrade_jwtwas documented in llms.txt but missing from every provisioning response schema. Added to DB, Cache, NoSQL, Queue, Storage, Webhook, Vector responses. (#C17)openapi_test.gogains 7 new gates so a future "let's tidy the schema" PR can't re-drop any of these without CI failing.Coordination
/billing/checkoutplanenum missinghobby_plus. FIX-A owns theplans.yaml hobby_plusrow; this PR did not touch the enum to avoid clashing. FIX-A will roll uphobby_plusand the corresponding/billing/checkoutplanenum in the same change.Cross-references
fix(sdk-go): correct DefaultBaseURL + add Deploy() method— same wave.fix(mcp): correct /api/me/* paths, claim host, env var, surface agent_action— same wave.Test plan
go test ./internal/handlers/ -run TestOpenAPI -count=1→ PASS (all openapi tests, including the 7 new gates)go build ./...→ cleanTestTeamSelf_*failures are unrelated (column-count mismatch onmodels.GetTeamByID, reproduces onmaster)Stretches the contract surface, not the runtime — zero handler code changed.
Generated with Claude Code