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

.github/workflows/test-build.yml

@@ -123,6 +123,9 @@ jobs:
       - name: API contract boundary audit
         run: bun run check:api-validation:strict
 
+      - name: OpenAPI spec validation
+        run: bun run check:openapi
+
       - name: Desktop bridge contract audit
         run: bun run check:desktop-bridge
 

apps/docs/content/docs/de/api-reference/getting-started.mdx

@@ -121,7 +121,7 @@ This returns immediately with a `jobId` and `statusUrl`:
 }
 ```
 
-Poll the [Get Job Status](/api-reference/workflows/getJobStatus) endpoint until the status is `completed` or `failed`:
+Poll the [Get Job Status](/api-reference/execution/getJobStatus) endpoint until the status is `completed` or `failed`:
 
 ```bash
 curl https://www.sim.ai/api/jobs/{jobId} \

apps/docs/content/docs/de/api-reference/meta.json

@@ -2,6 +2,7 @@
   "title": "API Reference",
   "root": true,
   "pages": [
+    "---Getting Started---",
     "getting-started",
     "authentication",
     "---SDKs---",
@@ -10,9 +11,18 @@
     "---Endpoints---",
     "(generated)/workflows",
     "(generated)/logs",
-    "(generated)/usage",
     "(generated)/audit-logs",
     "(generated)/tables",
-    "(generated)/files"
+    "(generated)/files",
+    "(generated)/knowledge-bases",
+    "(generated)/mcp-servers",
+    "(generated)/skills",
+    "(generated)/custom-tools",
+    "(generated)/folders",
+    "(generated)/credentials",
+    "---Execution and Usage---",
+    "(generated)/execution",
+    "(generated)/human-in-the-loop",
+    "(generated)/usage"
   ]
 }

apps/docs/content/docs/en/api-reference/(generated)/execution/meta.json

@@ -0,0 +1,3 @@
+{
+  "pages": ["executeWorkflow", "getWorkflowExecution", "cancelExecution", "getJobStatus"]
+}

apps/docs/content/docs/en/api-reference/(generated)/workflows/meta.json

@@ -1,15 +1,14 @@
 {
   "pages": [
-    "executeWorkflow",
-    "getWorkflowExecution",
-    "cancelExecution",
     "listWorkflows",
     "getWorkflow",
     "exportWorkflow",
     "importWorkflow",
     "deployWorkflow",
     "undeployWorkflow",
     "rollbackWorkflow",
-    "getJobStatus"
+    "executeWorkflowV2",
+    "getWorkflowExecutionV2",
+    "cancelExecutionV2"
   ]
 }

apps/docs/content/docs/en/api-reference/getting-started.mdx

@@ -121,7 +121,7 @@ This returns immediately with a `jobId` and `statusUrl`:
 }
 ```
 
-Poll the [Get Job Status](/api-reference/workflows/getJobStatus) endpoint until the status is `completed` or `failed`:
+Poll the [Get Job Status](/api-reference/execution/getJobStatus) endpoint until the status is `completed` or `failed`:
 
 ```bash
 curl https://www.sim.ai/api/jobs/{jobId} \

apps/docs/content/docs/en/api-reference/meta.json

@@ -10,12 +10,19 @@
     "typescript",
     "---Endpoints---",
     "(generated)/workflows",
-    "(generated)/human-in-the-loop",
     "(generated)/logs",
-    "(generated)/usage",
     "(generated)/audit-logs",
     "(generated)/tables",
     "(generated)/files",
-    "(generated)/knowledge-bases"
+    "(generated)/knowledge-bases",
+    "(generated)/mcp-servers",
+    "(generated)/skills",
+    "(generated)/custom-tools",
+    "(generated)/folders",
+    "(generated)/credentials",
+    "---Execution and Usage---",
+    "(generated)/execution",
+    "(generated)/human-in-the-loop",
+    "(generated)/usage"
   ]
 }

apps/docs/content/docs/en/platform/enterprise/audit-logs.mdx

@@ -33,7 +33,7 @@ Audit logs are also accessible through the Sim API for integration with external
 
 ```http
 GET /api/v1/audit-logs
-Authorization: Bearer <api-key>
+X-API-Key: <api-key>
 ```
 
 **Query parameters:**
@@ -71,11 +71,18 @@ Authorization: Bearer <api-key>
       "createdAt": "2026-04-20T21:16:00.000Z"
     }
   ],
-  "nextCursor": "eyJpZCI6ImFiYzEyMyJ9"
+  "nextCursor": "eyJpZCI6ImFiYzEyMyJ9",
+  "limits": {
+    "workflowExecutionRateLimit": {
+      "sync": { "requestsPerMinute": 60, "maxBurst": 10, "remaining": 59, "resetAt": "2026-04-20T21:17:00.000Z" },
+      "async": { "requestsPerMinute": 30, "maxBurst": 5, "remaining": 30, "resetAt": "2026-04-20T21:17:00.000Z" }
+    },
+    "usage": { "currentPeriodCost": 1.25, "limit": 50, "plan": "enterprise", "isExceeded": false }
+  }
 }
 ```
 
-Paginate by passing the `nextCursor` value as the `cursor` parameter in the next request. When `nextCursor` is absent, you have reached the last page.
+Paginate by passing the `nextCursor` value as the `cursor` parameter in the next request. When `nextCursor` is absent, you have reached the last page. Each entry also includes `actorName`; `metadata` is an arbitrary per-action JSON object. The `limits` object reports your current rate-limit and usage status.
 
 The API accepts both personal and workspace-scoped API keys. Rate limits apply — the response includes `X-RateLimit-*` headers with your current limit and remaining quota.
 

apps/docs/content/docs/es/api-reference/getting-started.mdx

@@ -121,7 +121,7 @@ This returns immediately with a `jobId` and `statusUrl`:
 }
 ```
 
-Poll the [Get Job Status](/api-reference/workflows/getJobStatus) endpoint until the status is `completed` or `failed`:
+Poll the [Get Job Status](/api-reference/execution/getJobStatus) endpoint until the status is `completed` or `failed`:
 
 ```bash
 curl https://www.sim.ai/api/jobs/{jobId} \

apps/docs/content/docs/es/api-reference/meta.json

@@ -2,6 +2,7 @@
   "title": "API Reference",
   "root": true,
   "pages": [
+    "---Getting Started---",
     "getting-started",
     "authentication",
     "---SDKs---",
@@ -10,7 +11,18 @@
     "---Endpoints---",
     "(generated)/workflows",
     "(generated)/logs",
-    "(generated)/usage",
-    "(generated)/audit-logs"
+    "(generated)/audit-logs",
+    "(generated)/tables",
+    "(generated)/files",
+    "(generated)/knowledge-bases",
+    "(generated)/mcp-servers",
+    "(generated)/skills",
+    "(generated)/custom-tools",
+    "(generated)/folders",
+    "(generated)/credentials",
+    "---Execution and Usage---",
+    "(generated)/execution",
+    "(generated)/human-in-the-loop",
+    "(generated)/usage"
   ]
 }

apps/docs/content/docs/fr/api-reference/getting-started.mdx

@@ -121,7 +121,7 @@ This returns immediately with a `jobId` and `statusUrl`:
 }
 ```
 
-Poll the [Get Job Status](/api-reference/workflows/getJobStatus) endpoint until the status is `completed` or `failed`:
+Poll the [Get Job Status](/api-reference/execution/getJobStatus) endpoint until the status is `completed` or `failed`:
 
 ```bash
 curl https://www.sim.ai/api/jobs/{jobId} \

apps/docs/content/docs/fr/api-reference/meta.json

@@ -2,6 +2,7 @@
   "title": "API Reference",
   "root": true,
   "pages": [
+    "---Getting Started---",
     "getting-started",
     "authentication",
     "---SDKs---",
@@ -10,7 +11,18 @@
     "---Endpoints---",
     "(generated)/workflows",
     "(generated)/logs",
-    "(generated)/usage",
-    "(generated)/audit-logs"
+    "(generated)/audit-logs",
+    "(generated)/tables",
+    "(generated)/files",
+    "(generated)/knowledge-bases",
+    "(generated)/mcp-servers",
+    "(generated)/skills",
+    "(generated)/custom-tools",
+    "(generated)/folders",
+    "(generated)/credentials",
+    "---Execution and Usage---",
+    "(generated)/execution",
+    "(generated)/human-in-the-loop",
+    "(generated)/usage"
   ]
 }

apps/docs/content/docs/ja/api-reference/getting-started.mdx

@@ -121,7 +121,7 @@ This returns immediately with a `jobId` and `statusUrl`:
 }
 ```
 
-Poll the [Get Job Status](/api-reference/workflows/getJobStatus) endpoint until the status is `completed` or `failed`:
+Poll the [Get Job Status](/api-reference/execution/getJobStatus) endpoint until the status is `completed` or `failed`:
 
 ```bash
 curl https://www.sim.ai/api/jobs/{jobId} \

apps/docs/content/docs/ja/api-reference/meta.json

@@ -2,6 +2,7 @@
   "title": "API Reference",
   "root": true,
   "pages": [
+    "---Getting Started---",
     "getting-started",
     "authentication",
     "---SDKs---",
@@ -10,7 +11,18 @@
     "---Endpoints---",
     "(generated)/workflows",
     "(generated)/logs",
-    "(generated)/usage",
-    "(generated)/audit-logs"
+    "(generated)/audit-logs",
+    "(generated)/tables",
+    "(generated)/files",
+    "(generated)/knowledge-bases",
+    "(generated)/mcp-servers",
+    "(generated)/skills",
+    "(generated)/custom-tools",
+    "(generated)/folders",
+    "(generated)/credentials",
+    "---Execution and Usage---",
+    "(generated)/execution",
+    "(generated)/human-in-the-loop",
+    "(generated)/usage"
   ]
 }

apps/docs/content/docs/zh/api-reference/getting-started.mdx

@@ -121,7 +121,7 @@ This returns immediately with a `jobId` and `statusUrl`:
 }
 ```
 
-Poll the [Get Job Status](/api-reference/workflows/getJobStatus) endpoint until the status is `completed` or `failed`:
+Poll the [Get Job Status](/api-reference/execution/getJobStatus) endpoint until the status is `completed` or `failed`:
 
 ```bash
 curl https://www.sim.ai/api/jobs/{jobId} \

apps/docs/content/docs/zh/api-reference/meta.json

@@ -2,6 +2,7 @@
   "title": "API Reference",
   "root": true,
   "pages": [
+    "---Getting Started---",
     "getting-started",
     "authentication",
     "---SDKs---",
@@ -10,7 +11,18 @@
     "---Endpoints---",
     "(generated)/workflows",
     "(generated)/logs",
-    "(generated)/usage",
-    "(generated)/audit-logs"
+    "(generated)/audit-logs",
+    "(generated)/tables",
+    "(generated)/files",
+    "(generated)/knowledge-bases",
+    "(generated)/mcp-servers",
+    "(generated)/skills",
+    "(generated)/custom-tools",
+    "(generated)/folders",
+    "(generated)/credentials",
+    "---Execution and Usage---",
+    "(generated)/execution",
+    "(generated)/human-in-the-loop",
+    "(generated)/usage"
   ]
 }