[lukekim]

Summary

Adds an HTTP SQL Response Formats section to the API overview (website/docs/api/overview.md). It flags the application/vnd.spiceai.sql.v1+json changes in spiceai/spiceai#15676:

• Key order: keys are now written as schema, data, row_count, sql. Before, row_count came first. It moved after data because the response now streams, and the count is only known after the last row.
• Streaming: v1+json now streams like application/json and text/csv. Before, it buffered the whole result.
• Decimals: DECIMAL values keep their exact digits and scale, the same as application/json. Before, they were converted to f64.

JSON object keys are unordered, so the SDKs and any client that parses the body as an object are unaffected. The note tells clients that read the body as text or rely on key positions to parse it as JSON instead.

Why here

The /v1/sql and /v1/nsql API pages (website/docs/api/HTTP/post-*.api.mdx) are generated from website/public/openapi.json, which updated_openapi.yml syncs from the runtime. A hand edit there would be overwritten on the next sync. The overview page is hand-written and already holds the cross-cutting HTTP notes, such as Request Correlation.

Merge order

⚠️ Merge only after spiceai/spiceai#15676 merges. The section describes v2.5 behavior.

Checks

• npx prettier --check website/docs/api/overview.md passes with the repo .prettierrc.
• The site build was not run locally (disk constraints on the build box). The change is plain Markdown with no new links or components.

[github-actions]

✅ Pull with Spice Passed

Passing checks:

• ✅ Title meets minimum length requirement (10 characters)
• ✅ Has at least one of the required labels: area/blog, area/docs, area/cookbook, dependencies
• ✅ No banned labels detected
• ✅ Has at least one assignee: lukekim, spiceemma

[github-actions]

🔍 Pull with Spice Failed

Passing checks:

• ✅ Title meets minimum length requirement (10 characters)
• ✅ Has at least one of the required labels: area/blog, area/docs, area/cookbook, dependencies
• ✅ No banned labels detected

Failed checks:

• ❌ At least one assignee is required for this pull request.

Please address these issues and update your pull request.

[github-actions]

🚀 deployed to https://ccea18f5.spiceai-org-website.pages.dev

[Copilot]

🔵 Needs a closer look

The documentation depends on the still-open spiceai/spiceai#15676, whose merge and inclusion in v2.5 must be confirmed before publishing the described behavior.

No open issues 🎉

What changed in this PR

Documents HTTP SQL response formats in the hand-written API overview, including the v2.5 behavior introduced by spiceai/spiceai#15676. This documentation should merge after that runtime change.

Changes:

• Lists supported response formats for /v1/sql and /v1/nsql.
• Explains v1+json streaming, key order, and decimal precision changes, with a JSON example and client compatibility guidance.

File	Description
website/​docs/​api/​overview.md	Adds HTTP SQL response format documentation and v2.5 compatibility notes.

_{Review effort: Balanced}

[github-actions]

🚀 deployed to https://de6d42e5.spiceai-org-website.pages.dev