improvement(api): replace workflow jobs with execution resources

Author: TheodoreSpeaks

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

@@ -109,27 +109,27 @@ curl -X POST https://www.sim.ai/api/workflows/{workflowId}/execute \
   -d '{"inputs": {}, "async": true}'
 ```
 
-This returns immediately with a `jobId` and `statusUrl`:
+This returns immediately with an `executionId` and `statusUrl`:
 
 ```json
 {
   "success": true,
-  "jobId": "job_abc123",
-  "statusUrl": "https://www.sim.ai/api/jobs/job_abc123",
-  "message": "Workflow execution started",
+  "executionId": "c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74",
+  "statusUrl": "https://www.sim.ai/api/workflows/{workflowId}/executions/c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74",
+  "message": "Workflow execution queued",
   "async": true
 }
 ```
 
-Poll the [Get Job Status](/api-reference/execution/getJobStatus) endpoint until the status is `completed` or `failed`:
+Poll the [Get Execution Status](/api-reference/execution/getWorkflowExecution) endpoint until the status is terminal:
 
 ```bash
-curl https://www.sim.ai/api/jobs/{jobId} \
+curl https://www.sim.ai/api/workflows/{workflowId}/executions/{executionId}?includeOutput=true \
   -H "X-API-Key: YOUR_API_KEY"
 ```
 
 <Callout type="info">
-  Job status transitions follow: `queued` → `processing` → `completed` or `failed`. The `output` field is only present when status is `completed`.
+  Execution status transitions follow: `queued` → `running` → `completed`, `failed`, `cancelled`, or `paused`. The `finalOutput` field is populated for completed executions when `includeOutput=true`.
 </Callout>
 
 ## Response Format

apps/docs/content/docs/de/api-reference/python.mdx

@@ -112,30 +112,34 @@ if is_ready:
 
 **Rückgabe:** `bool`
 
-##### get_job_status()
+##### get_workflow_execution()
 
-Ruft den Status einer asynchronen Job-Ausführung ab.
+Get the status and optional outputs of a workflow execution.
 
 ```python
-status = client.get_job_status("task-id-from-async-execution")
-print("Status:", status["status"])  # 'queued', 'processing', 'completed', 'failed'
+status = client.get_workflow_execution("workflow-id", "execution-id", include_output=True)
+print("Status:", status["status"])  # 'queued', 'running', 'completed', 'failed'
 if status["status"] == "completed":
-    print("Output:", status["output"])
+    print("Output:", status["finalOutput"])
 ```
 
-**Parameter:**
-- `task_id` (str): Die Task-ID, die von der asynchronen Ausführung zurückgegeben wurde
+**Parameters:**
+- `workflow_id` (str): The workflow ID
+- `execution_id` (str): The execution ID returned from async execution
+- `include_output` (bool, optional): Include the final output for completed executions
+- `selected_outputs` (list[str], optional): Block output selectors to include
 
-**Rückgabe:** `Dict[str, Any]`
+**Returns:** `Dict[str, Any]`
 
-**Antwortfelder:**
-- `success` (bool): Ob die Anfrage erfolgreich war
-- `taskId` (str): Die Task-ID
-- `status` (str): Einer von `'queued'`, `'processing'`, `'completed'`, `'failed'`, `'cancelled'`
-- `metadata` (dict): Enthält `startedAt`, `completedAt` und `duration`
-- `output` (any, optional): Die Workflow-Ausgabe (wenn abgeschlossen)
-- `error` (any, optional): Fehlerdetails (wenn fehlgeschlagen)
-- `estimatedDuration` (int, optional): Geschätzte Dauer in Millisekunden (wenn in Bearbeitung/in Warteschlange)
+**Response fields:**
+- `executionId` (str): The execution ID
+- `workflowId` (str): The workflow ID
+- `status` (str): One of `'queued'`, `'pending'`, `'running'`, `'paused'`, `'completed'`, `'failed'`, `'cancelled'`
+- `startedAt` / `endedAt` (str): Execution timestamps
+- `totalDurationMs` (int, optional): Duration in milliseconds
+- `finalOutput` (any, optional): The workflow output when requested for a completed execution
+- `blockOutputs` (dict, optional): Requested block outputs
+- `error` (str, optional): Failure details
 
 ##### execute_with_retry()
 
@@ -271,10 +275,10 @@ class WorkflowExecutionResult:
 @dataclass
 class AsyncExecutionResult:
     success: bool
-    task_id: str
-    status: str  # 'queued'
-    created_at: str
-    links: Dict[str, str]  # e.g., {"status": "/api/jobs/{taskId}"}
+    execution_id: str
+    status_url: str
+    message: str = ""
+    async_execution: bool = True
 ```
 
 ### WorkflowStatus
@@ -489,27 +493,31 @@ def execute_async():
         # Start async execution
         result = client.execute_workflow(
             "workflow-id",
-            input_data={"data": "large dataset"},
+            input={"data": "large dataset"},
             async_execution=True  # Execute asynchronously
         )
 
         # Check if result is an async execution
-        if hasattr(result, 'task_id'):
-            print(f"Task ID: {result.task_id}")
-            print(f"Status endpoint: {result.links['status']}")
+        if hasattr(result, 'async_execution') and result.async_execution:
+            print(f"Execution ID: {result.execution_id}")
+            print(f"Status endpoint: {result.status_url}")
 
             # Poll for completion
-            status = client.get_job_status(result.task_id)
+            status = client.get_workflow_execution(
+                "workflow-id", result.execution_id, include_output=True
+            )
 
-            while status["status"] in ["queued", "processing"]:
+            while status["status"] in ["queued", "pending", "running"]:
                 print(f"Current status: {status['status']}")
                 time.sleep(2)  # Wait 2 seconds
-                status = client.get_job_status(result.task_id)
+                status = client.get_workflow_execution(
+                    "workflow-id", result.execution_id, include_output=True
+                )
 
             if status["status"] == "completed":
                 print("Workflow completed!")
-                print(f"Output: {status['output']}")
-                print(f"Duration: {status['metadata']['duration']}")
+                print(f"Output: {status['finalOutput']}")
+                print(f"Duration: {status['totalDurationMs']}")
             else:
                 print(f"Workflow failed: {status['error']}")
 

apps/docs/content/docs/de/api-reference/typescript.mdx

@@ -133,31 +133,37 @@ if (isReady) {
 
 **Rückgabewert:** `Promise<boolean>`
 
-##### getJobStatus()
+##### getWorkflowExecution()
 
-Den Status einer asynchronen Job-Ausführung abrufen.
+Get the status and optional outputs of a workflow execution.
 
 ```typescript
-const status = await client.getJobStatus('task-id-from-async-execution');
-console.log('Status:', status.status); // 'queued', 'processing', 'completed', 'failed'
+const status = await client.getWorkflowExecution('workflow-id', 'execution-id', {
+  includeOutput: true
+});
+console.log('Status:', status.status); // 'queued', 'running', 'completed', 'failed'
 if (status.status === 'completed') {
-  console.log('Output:', status.output);
+  console.log('Output:', status.finalOutput);
 }
 ```
 
-**Parameter:**
-- `taskId` (string): Die Task-ID, die von der asynchronen Ausführung zurückgegeben wurde
+**Parameters:**
+- `workflowId` (string): The workflow ID
+- `executionId` (string): The execution ID returned from async execution
+- `options.includeOutput` (boolean, optional): Include the final output for completed executions
+- `options.selectedOutputs` (string[], optional): Block output selectors to include
 
-**Rückgabewert:** `Promise<JobStatus>`
+**Returns:** `Promise<WorkflowExecutionStatus>`
 
-**Antwortfelder:**
-- `success` (boolean): Ob die Anfrage erfolgreich war
-- `taskId` (string): Die Task-ID
-- `status` (string): Einer der Werte `'queued'`, `'processing'`, `'completed'`, `'failed'`, `'cancelled'`
-- `metadata` (object): Enthält `startedAt`, `completedAt` und `duration`
-- `output` (any, optional): Die Workflow-Ausgabe (wenn abgeschlossen)
-- `error` (any, optional): Fehlerdetails (wenn fehlgeschlagen)
-- `estimatedDuration` (number, optional): Geschätzte Dauer in Millisekunden (wenn in Bearbeitung/in der Warteschlange)
+**Response fields:**
+- `executionId` (string): The execution ID
+- `workflowId` (string): The workflow ID
+- `status` (string): One of `'queued'`, `'pending'`, `'running'`, `'paused'`, `'completed'`, `'failed'`, `'cancelled'`
+- `startedAt` / `endedAt` (string): Execution timestamps
+- `totalDurationMs` (number, nullable): Duration in milliseconds
+- `finalOutput` (any, nullable): The workflow output when requested for a completed execution
+- `blockOutputs` (object, nullable): Requested block outputs
+- `error` (string, nullable): Failure details
 
 ##### executeWithRetry()
 
@@ -286,12 +292,10 @@ interface WorkflowExecutionResult {
 ```typescript
 interface AsyncExecutionResult {
   success: boolean;
-  taskId: string;
-  status: 'queued';
-  createdAt: string;
-  links: {
-    status: string;  // e.g., "/api/jobs/{taskId}"
-  };
+  executionId: string;
+  statusUrl: string;
+  message: string;
+  async: true;
 }
 ```
 
@@ -791,29 +795,32 @@ const client = new SimStudioClient({
 async function executeAsync() {
   try {
     // Start async execution
-    const result = await client.executeWorkflow('workflow-id', {
-      input: { data: 'large dataset' },
+    const result = await client.executeWorkflow('workflow-id', { data: 'large dataset' }, {
       async: true  // Execute asynchronously
     });
 
     // Check if result is an async execution
-    if ('taskId' in result) {
-      console.log('Task ID:', result.taskId);
-      console.log('Status endpoint:', result.links.status);
+    if ('async' in result && result.async) {
+      console.log('Execution ID:', result.executionId);
+      console.log('Status endpoint:', result.statusUrl);
 
       // Poll for completion
-      let status = await client.getJobStatus(result.taskId);
+      let status = await client.getWorkflowExecution('workflow-id', result.executionId, {
+        includeOutput: true
+      });
 
-      while (status.status === 'queued' || status.status === 'processing') {
+      while (status.status === 'queued' || status.status === 'pending' || status.status === 'running') {
         console.log('Current status:', status.status);
         await new Promise(resolve => setTimeout(resolve, 2000)); // Wait 2 seconds
-        status = await client.getJobStatus(result.taskId);
+        status = await client.getWorkflowExecution('workflow-id', result.executionId, {
+          includeOutput: true
+        });
       }
 
       if (status.status === 'completed') {
         console.log('Workflow completed!');
-        console.log('Output:', status.output);
-        console.log('Duration:', status.metadata.duration);
+        console.log('Output:', status.finalOutput);
+        console.log('Duration:', status.totalDurationMs);
       } else {
         console.error('Workflow failed:', status.error);
       }

apps/docs/content/docs/de/sdks/python.mdx

@@ -112,30 +112,34 @@ if is_ready:
 
 **Rückgabe:** `bool`
 
-##### get_job_status()
+##### get_workflow_execution()
 
-Ruft den Status einer asynchronen Job-Ausführung ab.
+Get the status and optional outputs of a workflow execution.
 
 ```python
-status = client.get_job_status("task-id-from-async-execution")
-print("Status:", status["status"])  # 'queued', 'processing', 'completed', 'failed'
+status = client.get_workflow_execution("workflow-id", "execution-id", include_output=True)
+print("Status:", status["status"])  # 'queued', 'running', 'completed', 'failed'
 if status["status"] == "completed":
-    print("Output:", status["output"])
+    print("Output:", status["finalOutput"])
 ```
 
-**Parameter:**
-- `task_id` (str): Die Task-ID, die von der asynchronen Ausführung zurückgegeben wurde
+**Parameters:**
+- `workflow_id` (str): The workflow ID
+- `execution_id` (str): The execution ID returned from async execution
+- `include_output` (bool, optional): Include the final output for completed executions
+- `selected_outputs` (list[str], optional): Block output selectors to include
 
-**Rückgabe:** `Dict[str, Any]`
+**Returns:** `Dict[str, Any]`
 
-**Antwortfelder:**
-- `success` (bool): Ob die Anfrage erfolgreich war
-- `taskId` (str): Die Task-ID
-- `status` (str): Einer von `'queued'`, `'processing'`, `'completed'`, `'failed'`, `'cancelled'`
-- `metadata` (dict): Enthält `startedAt`, `completedAt` und `duration`
-- `output` (any, optional): Die Workflow-Ausgabe (wenn abgeschlossen)
-- `error` (any, optional): Fehlerdetails (wenn fehlgeschlagen)
-- `estimatedDuration` (int, optional): Geschätzte Dauer in Millisekunden (wenn in Bearbeitung/in Warteschlange)
+**Response fields:**
+- `executionId` (str): The execution ID
+- `workflowId` (str): The workflow ID
+- `status` (str): One of `'queued'`, `'pending'`, `'running'`, `'paused'`, `'completed'`, `'failed'`, `'cancelled'`
+- `startedAt` / `endedAt` (str): Execution timestamps
+- `totalDurationMs` (int, optional): Duration in milliseconds
+- `finalOutput` (any, optional): The workflow output when requested for a completed execution
+- `blockOutputs` (dict, optional): Requested block outputs
+- `error` (str, optional): Failure details
 
 ##### execute_with_retry()
 
@@ -271,10 +275,10 @@ class WorkflowExecutionResult:
 @dataclass
 class AsyncExecutionResult:
     success: bool
-    task_id: str
-    status: str  # 'queued'
-    created_at: str
-    links: Dict[str, str]  # e.g., {"status": "/api/jobs/{taskId}"}
+    execution_id: str
+    status_url: str
+    message: str = ""
+    async_execution: bool = True
 ```
 
 ### WorkflowStatus
@@ -489,27 +493,31 @@ def execute_async():
         # Start async execution
         result = client.execute_workflow(
             "workflow-id",
-            input_data={"data": "large dataset"},
+            input={"data": "large dataset"},
             async_execution=True  # Execute asynchronously
         )
 
         # Check if result is an async execution
-        if hasattr(result, 'task_id'):
-            print(f"Task ID: {result.task_id}")
-            print(f"Status endpoint: {result.links['status']}")
+        if hasattr(result, 'async_execution') and result.async_execution:
+            print(f"Execution ID: {result.execution_id}")
+            print(f"Status endpoint: {result.status_url}")
 
             # Poll for completion
-            status = client.get_job_status(result.task_id)
+            status = client.get_workflow_execution(
+                "workflow-id", result.execution_id, include_output=True
+            )
 
-            while status["status"] in ["queued", "processing"]:
+            while status["status"] in ["queued", "pending", "running"]:
                 print(f"Current status: {status['status']}")
                 time.sleep(2)  # Wait 2 seconds
-                status = client.get_job_status(result.task_id)
+                status = client.get_workflow_execution(
+                    "workflow-id", result.execution_id, include_output=True
+                )
 
             if status["status"] == "completed":
                 print("Workflow completed!")
-                print(f"Output: {status['output']}")
-                print(f"Duration: {status['metadata']['duration']}")
+                print(f"Output: {status['finalOutput']}")
+                print(f"Duration: {status['totalDurationMs']}")
             else:
                 print(f"Workflow failed: {status['error']}")