@knowledge-stack/ksapi 1.88.1 → 1.89.0

package/docs/WorkflowDefinitionsApi.md

@@ -5,9 +5,9 @@ All URIs are relative to *http://localhost:8000*
 | Method | HTTP request | Description |
 |------------- | ------------- | -------------|
 | [**createWorkflowDefinition**](WorkflowDefinitionsApi.md#createworkflowdefinitionoperation) | **POST** /v1/workflow-definitions | Create Workflow Definition Handler |
+| [**createWorkflowRun**](WorkflowDefinitionsApi.md#createworkflowrun) | **POST** /v1/workflow-definitions/{definition_id}/runs | Create Workflow Run Handler |
 | [**deleteWorkflowDefinition**](WorkflowDefinitionsApi.md#deleteworkflowdefinition) | **DELETE** /v1/workflow-definitions/{definition_id} | Delete Workflow Definition Handler |
 | [**getWorkflowDefinition**](WorkflowDefinitionsApi.md#getworkflowdefinition) | **GET** /v1/workflow-definitions/{definition_id} | Get Workflow Definition Handler |
-| [**invokeWorkflow**](WorkflowDefinitionsApi.md#invokeworkflowoperation) | **POST** /v1/workflow-definitions/{definition_id}/invoke | Invoke Workflow Handler |
 | [**listWorkflowDefinitions**](WorkflowDefinitionsApi.md#listworkflowdefinitions) | **GET** /v1/workflow-definitions | List Workflow Definitions Handler |
 | [**listWorkflowRuns**](WorkflowDefinitionsApi.md#listworkflowruns) | **GET** /v1/workflow-definitions/{definition_id}/runs | List Workflow Runs Handler |
 | [**updateWorkflowDefinition**](WorkflowDefinitionsApi.md#updateworkflowdefinitionoperation) | **PUT** /v1/workflow-definitions/{definition_id} | Update Workflow Definition Handler |
@@ -86,11 +86,13 @@ No authorization required
 [[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
 
 
-## deleteWorkflowDefinition
+## createWorkflowRun
 
-> deleteWorkflowDefinition(definitionId, authorization, ksUat)
+> WorkflowRunResponse createWorkflowRun(definitionId, authorization, ksUat, files, inputScope, idempotencyKey)
 
-Delete Workflow Definition Handler
+Create Workflow Run Handler
+
+Trigger a workflow run from uploaded files and/or KB references.  The merged endpoint accepts both kinds of input in one multipart request. Each uploaded file is ingested under ``runs/<id>/inputs/`` (S3 + DB rows only; no Temporal pipeline). Each ``input_scope`` entry is resolved per its part_type: a DOCUMENT is pinned to its active ``DOCUMENT_VERSION``; a FOLDER is pinned by reference only and read live by the runner. A request that supplies neither is rejected.
 
 ### Example
 
@@ -99,7 +101,7 @@ import {
   Configuration,
   WorkflowDefinitionsApi,
 } from '@knowledge-stack/ksapi';
-import type { DeleteWorkflowDefinitionRequest } from '@knowledge-stack/ksapi';
+import type { CreateWorkflowRunRequest } from '@knowledge-stack/ksapi';
 
 async function example() {
   console.log("🚀 Testing @knowledge-stack/ksapi SDK...");
@@ -112,10 +114,16 @@ async function example() {
     authorization: authorization_example,
     // string (optional)
     ksUat: ksUat_example,
-  } satisfies DeleteWorkflowDefinitionRequest;
+    // Array<Blob> | Files to ingest under the run\\\'s ``inputs/`` folder. Each filename may include POSIX-style ``/`` separators to reconstruct a folder structure under ``inputs/``. (optional)
+    files: /path/to/file.txt,
+    // string | JSON array of ``DOCUMENT`` or ``FOLDER`` path_part UUIDs referenced from the existing knowledge base. Combined with ``files`` in a single request to form the run\\\'s input scope. (optional)
+    inputScope: inputScope_example,
+    // string | Optional key to prevent duplicate runs from retries. (optional)
+    idempotencyKey: idempotencyKey_example,
+  } satisfies CreateWorkflowRunRequest;
 
   try {
-    const data = await api.deleteWorkflowDefinition(body);
+    const data = await api.createWorkflowRun(body);
     console.log(data);
   } catch (error) {
     console.error(error);
@@ -134,10 +142,13 @@ example().catch(console.error);
 | **definitionId** | `string` |  | [Defaults to `undefined`] |
 | **authorization** | `string` |  | [Optional] [Defaults to `undefined`] |
 | **ksUat** | `string` |  | [Optional] [Defaults to `undefined`] |
+| **files** | `Array<Blob>` | Files to ingest under the run\\\&#39;s &#x60;&#x60;inputs/&#x60;&#x60; folder. Each filename may include POSIX-style &#x60;&#x60;/&#x60;&#x60; separators to reconstruct a folder structure under &#x60;&#x60;inputs/&#x60;&#x60;. | [Optional] |
+| **inputScope** | `string` | JSON array of &#x60;&#x60;DOCUMENT&#x60;&#x60; or &#x60;&#x60;FOLDER&#x60;&#x60; path_part UUIDs referenced from the existing knowledge base. Combined with &#x60;&#x60;files&#x60;&#x60; in a single request to form the run\\\&#39;s input scope. | [Optional] [Defaults to `undefined`] |
+| **idempotencyKey** | `string` | Optional key to prevent duplicate runs from retries. | [Optional] [Defaults to `undefined`] |
 
 ### Return type
 
-`void` (Empty response body)
+[**WorkflowRunResponse**](WorkflowRunResponse.md)
 
 ### Authorization
 
@@ -145,24 +156,24 @@ No authorization required
 
 ### HTTP request headers
 
-- **Content-Type**: Not defined
+- **Content-Type**: `multipart/form-data`
 - **Accept**: `application/json`
 
 
 ### HTTP response details
 | Status code | Description | Response headers |
 |-------------|-------------|------------------|
-| **204** | Successful Response |  -  |
+| **201** | Successful Response |  -  |
 | **422** | Validation Error |  -  |
 
 [[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
 
 
-## getWorkflowDefinition
+## deleteWorkflowDefinition
 
-> WorkflowDefinitionResponse getWorkflowDefinition(definitionId, authorization, ksUat)
+> deleteWorkflowDefinition(definitionId, authorization, ksUat)
 
-Get Workflow Definition Handler
+Delete Workflow Definition Handler
 
 ### Example
 
@@ -171,7 +182,7 @@ import {
   Configuration,
   WorkflowDefinitionsApi,
 } from '@knowledge-stack/ksapi';
-import type { GetWorkflowDefinitionRequest } from '@knowledge-stack/ksapi';
+import type { DeleteWorkflowDefinitionRequest } from '@knowledge-stack/ksapi';
 
 async function example() {
   console.log("🚀 Testing @knowledge-stack/ksapi SDK...");
@@ -184,10 +195,10 @@ async function example() {
     authorization: authorization_example,
     // string (optional)
     ksUat: ksUat_example,
-  } satisfies GetWorkflowDefinitionRequest;
+  } satisfies DeleteWorkflowDefinitionRequest;
 
   try {
-    const data = await api.getWorkflowDefinition(body);
+    const data = await api.deleteWorkflowDefinition(body);
     console.log(data);
   } catch (error) {
     console.error(error);
@@ -209,7 +220,7 @@ example().catch(console.error);
 
 ### Return type
 
-[**WorkflowDefinitionResponse**](WorkflowDefinitionResponse.md)
+`void` (Empty response body)
 
 ### Authorization
 
@@ -224,19 +235,17 @@ No authorization required
 ### HTTP response details
 | Status code | Description | Response headers |
 |-------------|-------------|------------------|
-| **200** | Successful Response |  -  |
+| **204** | Successful Response |  -  |
 | **422** | Validation Error |  -  |
 
 [[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
 
 
-## invokeWorkflow
-
-> WorkflowRunResponse invokeWorkflow(definitionId, invokeWorkflowRequest, authorization, ksUat)
+## getWorkflowDefinition
 
-Invoke Workflow Handler
+> WorkflowDefinitionResponse getWorkflowDefinition(definitionId, authorization, ksUat)
 
-Trigger a workflow run.  All business logic lives in &#x60;&#x60;WorkflowInvocationService&#x60;&#x60;. This handler only orchestrates the two phases:  1. **Phase 1 (in-session):** validate, build snapshot, persist run row,    mint JWT. Wrapped in a single DB session so the run insert and the    idempotency-race resolution share a transaction. 2. **Phase 2 (out-of-session):** dispatch HTTP call to the SELF_HOSTED    runner. Best-effort — the run is already persisted, so failures here    transition the run to &#x60;&#x60;FAILED&#x60;&#x60; rather than rejecting the request.
+Get Workflow Definition Handler
 
 ### Example
 
@@ -245,7 +254,7 @@ import {
   Configuration,
   WorkflowDefinitionsApi,
 } from '@knowledge-stack/ksapi';
-import type { InvokeWorkflowOperationRequest } from '@knowledge-stack/ksapi';
+import type { GetWorkflowDefinitionRequest } from '@knowledge-stack/ksapi';
 
 async function example() {
   console.log("🚀 Testing @knowledge-stack/ksapi SDK...");
@@ -254,16 +263,14 @@ async function example() {
   const body = {
     // string
     definitionId: 38400000-8cf0-11bd-b23e-10b96e4ef00d,
-    // InvokeWorkflowRequest
-    invokeWorkflowRequest: ...,
     // string (optional)
     authorization: authorization_example,
     // string (optional)
     ksUat: ksUat_example,
-  } satisfies InvokeWorkflowOperationRequest;
+  } satisfies GetWorkflowDefinitionRequest;
 
   try {
-    const data = await api.invokeWorkflow(body);
+    const data = await api.getWorkflowDefinition(body);
     console.log(data);
   } catch (error) {
     console.error(error);
@@ -280,13 +287,12 @@ example().catch(console.error);
 | Name | Type | Description  | Notes |
 |------------- | ------------- | ------------- | -------------|
 | **definitionId** | `string` |  | [Defaults to `undefined`] |
-| **invokeWorkflowRequest** | [InvokeWorkflowRequest](InvokeWorkflowRequest.md) |  | |
 | **authorization** | `string` |  | [Optional] [Defaults to `undefined`] |
 | **ksUat** | `string` |  | [Optional] [Defaults to `undefined`] |
 
 ### Return type
 
-[**WorkflowRunResponse**](WorkflowRunResponse.md)
+[**WorkflowDefinitionResponse**](WorkflowDefinitionResponse.md)
 
 ### Authorization
 
@@ -294,14 +300,14 @@ No authorization required
 
 ### HTTP request headers
 
-- **Content-Type**: `application/json`
+- **Content-Type**: Not defined
 - **Accept**: `application/json`
 
 
 ### HTTP response details
 | Status code | Description | Response headers |
 |-------------|-------------|------------------|
-| **202** | Successful Response |  -  |
+| **200** | Successful Response |  -  |
 | **422** | Validation Error |  -  |
 
 [[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)

package/docs/WorkflowExecutionState.md

@@ -0,0 +1,33 @@
+
+# WorkflowExecutionState
+
+Execution lifecycle of a workflow run.  Two-step flow lifecycle:  * ``PENDING`` — entry state when the create call carries uploads.   Inputs are being ingested by Temporal; the run cannot be started   yet. The ingestion-completion hook auto-flips the run to   ``NOT_STARTED`` once every input under ``inputs/`` reaches   ``pipeline_state.status == COMPLETED``. * ``NOT_STARTED`` — entry state when the create call has no   uploads (KB references only), OR the post-ingestion landing   pad. The user can Start the run from here. * ``IN_PROGRESS`` — set by ``POST /v1/workflow-runs/{id}/start``,   which builds the snapshot and dispatches the Temporal workflow. * ``COMPLETED`` / ``FAILED`` — terminal; ``completed_at`` is set.
+
+## Properties
+
+Name | Type
+------------ | -------------
+
+## Example
+
+```typescript
+import type { WorkflowExecutionState } from '@knowledge-stack/ksapi'
+
+// TODO: Update the object below with actual values
+const example = {
+} satisfies WorkflowExecutionState
+
+console.log(example)
+
+// Convert the instance to a JSON string
+const exampleJSON: string = JSON.stringify(example)
+console.log(exampleJSON)
+
+// Parse the JSON string back to an object
+const exampleParsed = JSON.parse(exampleJSON) as WorkflowExecutionState
+console.log(exampleParsed)
+```
+
+[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
+
+

package/docs/WorkflowMemoryApi.md

@@ -18,8 +18,6 @@ All URIs are relative to *http://localhost:8000*
 
 Append Workflow Memory Chunk Handler
 
-Append a new memory chunk.  Exposed for external agents (e.g. self-hosted runners) that need to capture learnings without touching the DB directly. The new chunk\'s ``chunk_id`` is server-assigned. Each call snapshots a new DocumentVersion, just like edit/forget.
-
 ### Example
 
 ```ts
@@ -319,7 +317,7 @@ No authorization required
 
 ## listWorkflowMemoryChunks
 
-> ListMemoryChunksResponse listWorkflowMemoryChunks(definitionId, authorization, ksUat)
+> PaginatedResponseMemoryChunkResponse listWorkflowMemoryChunks(definitionId, limit, offset, authorization, ksUat)
 
 List Workflow Memory Chunks Handler
 
@@ -339,6 +337,10 @@ async function example() {
   const body = {
     // string
     definitionId: 38400000-8cf0-11bd-b23e-10b96e4ef00d,
+    // number | Number of items per page (optional)
+    limit: 56,
+    // number | Number of items to skip (optional)
+    offset: 56,
     // string (optional)
     authorization: authorization_example,
     // string (optional)
@@ -363,12 +365,14 @@ example().catch(console.error);
 | Name | Type | Description  | Notes |
 |------------- | ------------- | ------------- | -------------|
 | **definitionId** | `string` |  | [Defaults to `undefined`] |
+| **limit** | `number` | Number of items per page | [Optional] [Defaults to `20`] |
+| **offset** | `number` | Number of items to skip | [Optional] [Defaults to `0`] |
 | **authorization** | `string` |  | [Optional] [Defaults to `undefined`] |
 | **ksUat** | `string` |  | [Optional] [Defaults to `undefined`] |
 
 ### Return type
 
-[**ListMemoryChunksResponse**](ListMemoryChunksResponse.md)
+[**PaginatedResponseMemoryChunkResponse**](PaginatedResponseMemoryChunkResponse.md)
 
 ### Authorization
 

package/docs/WorkflowRunResponse.md

@@ -1,23 +1,33 @@
 
 # WorkflowRunResponse
 
-Workflow run response.  Note: ``run_token_jti`` is intentionally NOT exposed. It\'s an internal token identifier persisted on the run row for callback auth — clients should treat run dispatch state as observable via ``status`` (RUNNING => dispatched), not via JTI presence.
+Workflow run response.  Doubles as a discriminated-union variant for folder-listing responses so the FE can mix WD/Run entries with regular folders + documents and route based on ``part_type``.  Two-step flow note: a NOT_STARTED run has ``started_at=None`` and ``run_snapshot=None``; both are populated when Start dispatches the run. The flat ``input_path_part_ids`` list carries the currently-pinned KB references so the FE can render them on a NOT_STARTED run (the snapshot\'s typed list is not available yet).
 
 ## Properties
 
 Name | Type
 ------------ | -------------
+`partType` | string
 `id` | string
+`pathPartId` | string
+`parentPathPartId` | string
+`materializedPath` | string
+`tenantId` | string
+`name` | string
 `workflowDefinitionId` | string
-`userId` | string
-`runnerType` | [WorkflowRunnerType](WorkflowRunnerType.md)
-`status` | [WorkflowRunStatus](WorkflowRunStatus.md)
+`triggeredBy` | [UserInfo](UserInfo.md)
+`executionState` | [WorkflowExecutionState](WorkflowExecutionState.md)
+`approvalState` | [PathPartApprovalState](PathPartApprovalState.md)
 `startedAt` | Date
 `completedAt` | Date
 `runSnapshot` | [WorkflowRunSnapshot](WorkflowRunSnapshot.md)
 `error` | string
+`inputsPathPartId` | string
+`outputsPathPartId` | string
+`discussionsPathPartId` | string
 `inputPathPartIds` | Array<string>
-`inputVersionIds` | Array<string>
+`outputsPathPartIds` | Array<string>
+`runThreadId` | string
 `createdAt` | Date
 `updatedAt` | Date
 
@@ -28,17 +38,27 @@ import type { WorkflowRunResponse } from '@knowledge-stack/ksapi'
 
 // TODO: Update the object below with actual values
 const example = {
+  "partType": null,
   "id": null,
+  "pathPartId": null,
+  "parentPathPartId": null,
+  "materializedPath": null,
+  "tenantId": null,
+  "name": null,
   "workflowDefinitionId": null,
-  "userId": null,
-  "runnerType": null,
-  "status": null,
+  "triggeredBy": null,
+  "executionState": null,
+  "approvalState": null,
   "startedAt": null,
   "completedAt": null,
   "runSnapshot": null,
   "error": null,
+  "inputsPathPartId": null,
+  "outputsPathPartId": null,
+  "discussionsPathPartId": null,
   "inputPathPartIds": null,
-  "inputVersionIds": null,
+  "outputsPathPartIds": null,
+  "runThreadId": null,
   "createdAt": null,
   "updatedAt": null,
 } satisfies WorkflowRunResponse

package/docs/WorkflowRunSnapshot.md

@@ -1,21 +1,16 @@
 
 # WorkflowRunSnapshot
 
-Frozen ABCD configuration captured at workflow trigger time.
+Frozen workflow configuration captured at trigger time.  ``workflow_definition_id`` and ``user_id`` are NOT stored here — they live directly on the ``WorkflowRun`` row and are surfaced via ``WorkflowRunResponse`` top-level fields.  Inputs are per-run; outputs land in the run\'s ``outputs/`` folder. The agent resolves the run\'s inputs/outputs/discussions folders by listing the run-folder children at activity startup.
 
 ## Properties
 
 Name | Type
 ------------ | -------------
-`workflowDefinitionId` | string
 `workflowName` | string
-`runnerType` | [WorkflowRunnerType](WorkflowRunnerType.md)
-`userId` | string
 `maxRunDurationSeconds` | number
-`sources` | [Array<ABCDPathSnapshot>](ABCDPathSnapshot.md)
-`instructions` | [Array<InstructionSnapshot>](InstructionSnapshot.md)
-`outputs` | [Array<ABCDPathSnapshot>](ABCDPathSnapshot.md)
-`template` | [ABCDPathSnapshot](ABCDPathSnapshot.md)
+`instruction` | [InstructionSnapshot](InstructionSnapshot.md)
+`inputs` | [Array<InputSnapshot>](InputSnapshot.md)
 
 ## Example
 
@@ -24,15 +19,10 @@ import type { WorkflowRunSnapshot } from '@knowledge-stack/ksapi'
 
 // TODO: Update the object below with actual values
 const example = {
-  "workflowDefinitionId": null,
   "workflowName": null,
-  "runnerType": null,
-  "userId": null,
   "maxRunDurationSeconds": null,
-  "sources": null,
-  "instructions": null,
-  "outputs": null,
-  "template": null,
+  "instruction": null,
+  "inputs": null,
 } satisfies WorkflowRunSnapshot
 
 console.log(example)