improvement(external-endpoints): v2 versions with clean signatures + updated docs based on openapi spec

[icecrasher321]

Summary

Introduces a new, parallel /api/v2 external API surface that standardizes the
response envelope, pagination, error handling, and auth across every resource —
fixing the inconsistencies that had accreted in /api/v1 without breaking existing
v1 consumers. v1 stays in place and untouched on the wire; v2 is where the breaking
improvements land. Also includes a set of safe, in-place v1 correctness fixes
surfaced during the audit, and a full API-reference docs rework.

Type of Change

• Documentation
• Other: Code cleanup

Testing

Tested manually

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Jun 29, 2026 10:23pm

[cursor]

PR Summary

Low Risk
Changes are limited to documentation content and OpenAPI spec loading for the docs site; no application API runtime code appears in this diff.

Overview
Reworks the docs OpenAPI setup from a single spec into multiple JSON files (openapi-core.json for execution, human-in-the-loop, and usage, plus domain v2 specs such as files/audit). openapi.ts now feeds all of them into Fumadocs, resolves operations across specs for generated pages, and hardens $ref expansion with cycle detection.

The API reference sidebar is reorganized: run/cancel/job-status endpoints move out of Workflows into a new (generated)/execution group under an Execution and Usage section; workflows pages are limited to lifecycle CRUD/deploy. Locales get aligned nav (including tables, files, knowledge bases where they were missing).

Getting started (all locales) now links async polling to /api-reference/execution/getJobStatus. Enterprise audit logs docs switch the example auth header to X-API-Key, extend the list response example with limits, and note actorName, metadata, and rate-limit headers.

^{Reviewed by Cursor Bugbot for commit 98c8567. Configure here.}

[greptile-apps]

Greptile Summary

This PR adds a parallel v2 external API and refreshes the API docs. The main changes are:

• New v2 routes for files, knowledge, logs, tables, workflows, and audit logs.
• Shared v2 response envelopes, cursor helpers, and error shapes.
• Split OpenAPI specs and updated docs navigation.
• Small v1 contract and route cleanup found during the API audit.

Confidence Score: 4/5

The v2 table mutation paths need fixes before merging.

• Unknown row data keys can be dropped before validation.
• Invalid bulk filters can return successful empty results.
• Column delete cleanup can race with immediate restore flows.

apps/sim/app/api/v2/tables/[tableId]/rows/route.ts; apps/sim/app/api/v2/tables/[tableId]/columns/route.ts

Important Files Changed

Filename	Overview
apps/sim/app/api/v2/lib/response.ts	Adds shared v2 response, error, rate-limit header, and cursor helpers.
apps/sim/app/api/v2/tables/[tableId]/rows/route.ts	Adds v2 row listing, insert, bulk update, and bulk delete, with validation gaps around public column-name translation.
apps/sim/app/api/v2/tables/[tableId]/columns/route.ts	Adds v2 column mutations and exposes the asynchronous delete cleanup behavior through the external API.
apps/sim/app/api/v2/knowledge/search/route.ts	Adds v2 knowledge search with workspace access checks and usage gating for vector queries.
apps/sim/app/api/v2/logs/route.ts	Adds v2 log listing with workspace-scoped filters and optional execution-data materialization.
apps/docs/lib/openapi.ts	Updates OpenAPI rendering to load multiple spec files and resolve references per owning spec.

_{Reviews (1): Last reviewed commit: "improvement(external-endpoints): v2 vers..." | Re-trigger Greptile}

[greptile-apps]

Unknown Columns Are Dropped

When a v2 caller sends row data with a misspelled or differently cased column name, rowDataNameToId removes that key before validateBatchRows runs. The request can then succeed while silently losing the caller's submitted value; the same translation pattern is used by the single-row insert, update, and upsert paths.

[greptile-apps]

Invalid Filters Succeed Empty

filterNamesToIds leaves unknown filter fields unchanged, so a bulk update or delete with a misspelled public column name is executed as a lookup on a non-existent JSON key. The API can return a successful response with zero affected rows instead of rejecting the invalid destructive filter.

[greptile-apps]

Column Undo Can Lose Data

This v2 delete path returns as soon as deleteColumn finishes, while the shared column service strips the deleted column's row data in a fire-and-forget cleanup. If an external caller immediately recreates or restores a column with the same id, that delayed cleanup can remove the restored column values after the API has already reported success.