mirror of
https://github.com/simstudioai/sim.git
synced 2026-04-28 03:00:29 -04:00
c393791f04
* docs(openapi): add Human in the Loop API endpoints Add HITL pause/resume endpoints to the OpenAPI spec covering the full workflow pause lifecycle: listing paused executions, inspecting pause details, and resuming with input. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs(openapi): add 403 and 500 responses to HITL endpoints Address PR review feedback: add missing 403 Forbidden response to all HITL endpoints (from validateWorkflowAccess), and 500 responses to resume endpoints that have explicit error paths. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * lint --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
6819 lines
234 KiB
JSON
6819 lines
234 KiB
JSON
{
|
|
"openapi": "3.1.0",
|
|
"info": {
|
|
"title": "Sim API",
|
|
"description": "API for executing workflows, querying logs, and managing resources in Sim.",
|
|
"version": "1.0.0",
|
|
"contact": {
|
|
"name": "Sim Support",
|
|
"email": "help@sim.ai",
|
|
"url": "https://www.sim.ai"
|
|
},
|
|
"license": {
|
|
"name": "Apache 2.0",
|
|
"url": "https://www.apache.org/licenses/LICENSE-2.0.html"
|
|
}
|
|
},
|
|
"servers": [
|
|
{
|
|
"url": "https://www.sim.ai",
|
|
"description": "Production"
|
|
}
|
|
],
|
|
"tags": [
|
|
{
|
|
"name": "Workflows",
|
|
"description": "Execute workflows and manage workflow resources"
|
|
},
|
|
{
|
|
"name": "Human in the Loop",
|
|
"description": "Manage paused workflow executions and resume them with input"
|
|
},
|
|
{
|
|
"name": "Logs",
|
|
"description": "Query execution logs and retrieve details"
|
|
},
|
|
{
|
|
"name": "Usage",
|
|
"description": "Check rate limits and billing usage"
|
|
},
|
|
{
|
|
"name": "Audit Logs",
|
|
"description": "View audit trail of workspace activity"
|
|
},
|
|
{
|
|
"name": "Tables",
|
|
"description": "Manage tables and rows for structured data storage"
|
|
},
|
|
{
|
|
"name": "Files",
|
|
"description": "Upload, download, and manage workspace files"
|
|
},
|
|
{
|
|
"name": "Knowledge Bases",
|
|
"description": "Manage knowledge bases, documents, and vector search"
|
|
}
|
|
],
|
|
"security": [
|
|
{
|
|
"apiKey": []
|
|
}
|
|
],
|
|
"paths": {
|
|
"/api/workflows/{id}/execute": {
|
|
"post": {
|
|
"operationId": "executeWorkflow",
|
|
"summary": "Execute Workflow",
|
|
"description": "Execute a deployed workflow. Supports synchronous, asynchronous, and streaming modes. For async execution, the response includes a statusUrl you can poll for results.",
|
|
"tags": ["Workflows"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X POST \\\n \"https://www.sim.ai/api/workflows/{id}/execute\" \\\n -H \"X-API-Key: YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"key\": \"value\"\n }\n }'"
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The unique identifier of the deployed workflow to execute.",
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "wf_1a2b3c4d5e"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"description": "Execution configuration including input values and execution mode options.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"input": {
|
|
"type": "object",
|
|
"description": "Key-value pairs matching the workflow's defined input fields. Use the Get Workflow endpoint to discover available input fields.",
|
|
"additionalProperties": true
|
|
},
|
|
"triggerType": {
|
|
"type": "string",
|
|
"description": "How this execution was triggered. Defaults to api when called via the REST API. Recorded in execution logs for filtering."
|
|
},
|
|
"stream": {
|
|
"type": "boolean",
|
|
"description": "When true, returns results as Server-Sent Events (SSE) for real-time block-by-block output streaming."
|
|
},
|
|
"selectedOutputs": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "List of specific block IDs whose outputs to include in the response. When omitted, all block outputs are returned."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"input": {
|
|
"query": "What is the weather in Tokyo?"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Synchronous execution completed successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ExecutionResult"
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"executionId": "exec_abc123",
|
|
"output": {
|
|
"content": "The weather in Tokyo is sunny, 22\u00b0C."
|
|
},
|
|
"error": null,
|
|
"metadata": {
|
|
"startTime": "2026-01-15T10:30:00Z",
|
|
"endTime": "2026-01-15T10:30:01Z",
|
|
"duration": 1250
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"202": {
|
|
"description": "Asynchronous execution has been queued. Poll the statusUrl for results.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AsyncExecutionResult"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/workflows/{id}/executions/{executionId}/cancel": {
|
|
"post": {
|
|
"operationId": "cancelExecution",
|
|
"summary": "Cancel Execution",
|
|
"description": "Cancel a running workflow execution. Only effective for executions that are still in progress.",
|
|
"tags": ["Workflows"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X POST \\\n \"https://www.sim.ai/api/workflows/{id}/executions/{executionId}/cancel\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The unique identifier of the workflow.",
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "wf_1a2b3c4d5e"
|
|
}
|
|
},
|
|
{
|
|
"name": "executionId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The unique identifier of the execution to cancel.",
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "exec_9f8e7d6c5b"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Execution was successfully cancelled.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"description": "Whether the cancellation was successful."
|
|
},
|
|
"executionId": {
|
|
"type": "string",
|
|
"description": "The ID of the cancelled execution."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"executionId": "exec_abc123"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/workflows/{id}/paused": {
|
|
"get": {
|
|
"operationId": "listPausedExecutions",
|
|
"summary": "List Paused Executions",
|
|
"description": "List all paused executions for a workflow. Workflows pause at Human in the Loop blocks and wait for input before continuing. Use this endpoint to discover which executions need attention.",
|
|
"tags": ["Human in the Loop"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X GET \\\n \"https://www.sim.ai/api/workflows/{id}/paused?status=paused\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The unique identifier of the workflow.",
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "wf_1a2b3c4d5e"
|
|
}
|
|
},
|
|
{
|
|
"name": "status",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "Filter paused executions by status.",
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "paused"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "List of paused executions.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"pausedExecutions": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/PausedExecutionSummary"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"pausedExecutions": [
|
|
{
|
|
"id": "pe_abc123",
|
|
"workflowId": "wf_1a2b3c4d5e",
|
|
"executionId": "exec_9f8e7d6c5b",
|
|
"status": "paused",
|
|
"totalPauseCount": 1,
|
|
"resumedCount": 0,
|
|
"pausedAt": "2026-01-15T10:30:00Z",
|
|
"updatedAt": "2026-01-15T10:30:00Z",
|
|
"expiresAt": null,
|
|
"metadata": null,
|
|
"triggerIds": [],
|
|
"pausePoints": [
|
|
{
|
|
"contextId": "ctx_xyz789",
|
|
"blockId": "block_hitl_1",
|
|
"registeredAt": "2026-01-15T10:30:00Z",
|
|
"resumeStatus": "paused",
|
|
"snapshotReady": true,
|
|
"resumeLinks": {
|
|
"apiUrl": "https://www.sim.ai/api/resume/wf_1a2b3c4d5e/exec_9f8e7d6c5b/ctx_xyz789",
|
|
"uiUrl": "https://www.sim.ai/resume/wf_1a2b3c4d5e/exec_9f8e7d6c5b",
|
|
"contextId": "ctx_xyz789",
|
|
"executionId": "exec_9f8e7d6c5b",
|
|
"workflowId": "wf_1a2b3c4d5e"
|
|
},
|
|
"response": {
|
|
"displayData": {
|
|
"title": "Approval Required",
|
|
"message": "Please review this request"
|
|
},
|
|
"formFields": []
|
|
}
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/workflows/{id}/paused/{executionId}": {
|
|
"get": {
|
|
"operationId": "getPausedExecution",
|
|
"summary": "Get Paused Execution",
|
|
"description": "Get detailed information about a specific paused execution, including its pause points, execution snapshot, and resume queue. Use this to inspect the state before resuming.",
|
|
"tags": ["Human in the Loop"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X GET \\\n \"https://www.sim.ai/api/workflows/{id}/paused/{executionId}\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The unique identifier of the workflow.",
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "wf_1a2b3c4d5e"
|
|
}
|
|
},
|
|
{
|
|
"name": "executionId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The execution ID of the paused execution.",
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "exec_9f8e7d6c5b"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Paused execution details.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/PausedExecutionDetail"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/resume/{workflowId}/{executionId}": {
|
|
"get": {
|
|
"operationId": "getPausedExecutionByResumePath",
|
|
"summary": "Get Paused Execution (Resume Path)",
|
|
"description": "Get detailed information about a specific paused execution using the resume URL path. Returns the same data as the workflow paused execution detail endpoint.",
|
|
"tags": ["Human in the Loop"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X GET \\\n \"https://www.sim.ai/api/resume/{workflowId}/{executionId}\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "workflowId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The unique identifier of the workflow.",
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "wf_1a2b3c4d5e"
|
|
}
|
|
},
|
|
{
|
|
"name": "executionId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The execution ID of the paused execution.",
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "exec_9f8e7d6c5b"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Paused execution details.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/PausedExecutionDetail"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
},
|
|
"500": {
|
|
"description": "Internal server error.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"error": {
|
|
"type": "string",
|
|
"description": "Human-readable error message."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/resume/{workflowId}/{executionId}/{contextId}": {
|
|
"get": {
|
|
"operationId": "getPauseContext",
|
|
"summary": "Get Pause Context",
|
|
"description": "Get detailed information about a specific pause context within a paused execution. Returns the pause point details, resume queue state, and any active resume entry.",
|
|
"tags": ["Human in the Loop"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X GET \\\n \"https://www.sim.ai/api/resume/{workflowId}/{executionId}/{contextId}\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "workflowId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The unique identifier of the workflow.",
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "wf_1a2b3c4d5e"
|
|
}
|
|
},
|
|
{
|
|
"name": "executionId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The execution ID of the paused execution.",
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "exec_9f8e7d6c5b"
|
|
}
|
|
},
|
|
{
|
|
"name": "contextId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The pause context ID to retrieve details for.",
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "ctx_xyz789"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Pause context details.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/PauseContextDetail"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
}
|
|
}
|
|
},
|
|
"post": {
|
|
"operationId": "resumeExecution",
|
|
"summary": "Resume Execution",
|
|
"description": "Resume a paused workflow execution by providing input for a specific pause context. The execution continues from where it paused, using the provided input. Supports synchronous, asynchronous, and streaming modes (determined by the original execution's configuration).",
|
|
"tags": ["Human in the Loop"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X POST \\\n \"https://www.sim.ai/api/resume/{workflowId}/{executionId}/{contextId}\" \\\n -H \"X-API-Key: YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"input\": {\n \"approved\": true,\n \"comment\": \"Looks good to me\"\n }\n }'"
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "workflowId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The unique identifier of the workflow.",
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "wf_1a2b3c4d5e"
|
|
}
|
|
},
|
|
{
|
|
"name": "executionId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The execution ID of the paused execution.",
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "exec_9f8e7d6c5b"
|
|
}
|
|
},
|
|
{
|
|
"name": "contextId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The pause context ID to resume. Found in the pause point's contextId field or resumeLinks.",
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "ctx_xyz789"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"description": "Input data for the resumed execution. The structure depends on the workflow's Human in the Loop block configuration.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"input": {
|
|
"type": "object",
|
|
"description": "Key-value pairs to pass as input to the resumed execution. If omitted, the entire request body is used as input.",
|
|
"additionalProperties": true
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"input": {
|
|
"approved": true,
|
|
"comment": "Looks good to me"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Resume execution completed synchronously, or resume was queued behind another in-progress resume.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"oneOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ResumeResult"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "Resume has been queued behind another in-progress resume.",
|
|
"properties": {
|
|
"status": {
|
|
"type": "string",
|
|
"enum": ["queued"],
|
|
"description": "Indicates the resume is queued."
|
|
},
|
|
"executionId": {
|
|
"type": "string",
|
|
"description": "The execution ID assigned to this resume."
|
|
},
|
|
"queuePosition": {
|
|
"type": "integer",
|
|
"description": "Position in the resume queue."
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"description": "Human-readable status message."
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"type": "object",
|
|
"description": "Resume execution started (non-API-key callers). The execution runs asynchronously.",
|
|
"properties": {
|
|
"status": {
|
|
"type": "string",
|
|
"enum": ["started"],
|
|
"description": "Indicates the resume execution has started."
|
|
},
|
|
"executionId": {
|
|
"type": "string",
|
|
"description": "The execution ID for the resumed workflow."
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"description": "Human-readable status message."
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"examples": {
|
|
"sync": {
|
|
"summary": "Synchronous completion",
|
|
"value": {
|
|
"success": true,
|
|
"status": "completed",
|
|
"executionId": "exec_new123",
|
|
"output": {
|
|
"result": "Approved and processed"
|
|
},
|
|
"error": null,
|
|
"metadata": {
|
|
"duration": 850,
|
|
"startTime": "2026-01-15T10:35:00Z",
|
|
"endTime": "2026-01-15T10:35:01Z"
|
|
}
|
|
}
|
|
},
|
|
"queued": {
|
|
"summary": "Queued behind another resume",
|
|
"value": {
|
|
"status": "queued",
|
|
"executionId": "exec_new123",
|
|
"queuePosition": 2,
|
|
"message": "Resume queued. It will run after current resumes finish."
|
|
}
|
|
},
|
|
"started": {
|
|
"summary": "Execution started (fire and forget)",
|
|
"value": {
|
|
"status": "started",
|
|
"executionId": "exec_new123",
|
|
"message": "Resume execution started."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"202": {
|
|
"description": "Resume execution has been queued for asynchronous processing. Poll the statusUrl for results.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AsyncExecutionResult"
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"async": true,
|
|
"jobId": "job_4a3b2c1d0e",
|
|
"executionId": "exec_new123",
|
|
"message": "Resume execution queued",
|
|
"statusUrl": "https://www.sim.ai/api/jobs/job_4a3b2c1d0e"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
},
|
|
"503": {
|
|
"description": "Failed to queue the resume execution. Retry the request.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"error": {
|
|
"type": "string",
|
|
"description": "Error message."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Internal server error.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"error": {
|
|
"type": "string",
|
|
"description": "Human-readable error message."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/v1/workflows": {
|
|
"get": {
|
|
"operationId": "listWorkflows",
|
|
"summary": "List Workflows",
|
|
"description": "Retrieve all workflows in a workspace with cursor-based pagination.",
|
|
"tags": ["Workflows"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X GET \\\n \"https://www.sim.ai/api/v1/workflows?workspaceId=YOUR_WORKSPACE_ID\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/WorkspaceId"
|
|
},
|
|
{
|
|
"name": "folderId",
|
|
"in": "query",
|
|
"description": "Filter results to only include workflows within this folder.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "deployedOnly",
|
|
"in": "query",
|
|
"description": "When true, only return workflows that have been deployed. Useful for listing workflows available for API execution.",
|
|
"schema": {
|
|
"type": "boolean"
|
|
}
|
|
},
|
|
{
|
|
"name": "limit",
|
|
"in": "query",
|
|
"description": "Maximum number of workflows to return per page. Must be between 1 and 100.",
|
|
"schema": {
|
|
"type": "integer",
|
|
"minimum": 1,
|
|
"maximum": 100
|
|
}
|
|
},
|
|
{
|
|
"name": "cursor",
|
|
"in": "query",
|
|
"description": "Pagination cursor returned from a previous request's nextCursor field. Omit for the first page.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "A paginated list of workflows.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "array",
|
|
"description": "Array of workflow summary objects for the current page.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/WorkflowSummary"
|
|
}
|
|
},
|
|
"nextCursor": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Cursor for fetching the next page of results. null when there are no more results."
|
|
},
|
|
"limits": {
|
|
"$ref": "#/components/schemas/Limits",
|
|
"description": "Rate limit and usage information for the current API key."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"data": [
|
|
{
|
|
"id": "wf_abc123",
|
|
"name": "Weather Bot",
|
|
"isDeployed": true,
|
|
"createdAt": "2026-01-15T10:30:00Z",
|
|
"updatedAt": "2026-01-15T10:30:00Z"
|
|
}
|
|
],
|
|
"nextCursor": null
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/v1/workflows/{id}": {
|
|
"get": {
|
|
"operationId": "getWorkflow",
|
|
"summary": "Get Workflow",
|
|
"description": "Retrieve details for a single workflow, including its input fields and deployment status.",
|
|
"tags": ["Workflows"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X GET \\\n \"https://www.sim.ai/api/v1/workflows/{id}\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The unique workflow identifier.",
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "wf_1a2b3c4d5e"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Workflow details including input field definitions.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"description": "The full workflow detail object.",
|
|
"$ref": "#/components/schemas/WorkflowDetail"
|
|
},
|
|
"limits": {
|
|
"$ref": "#/components/schemas/Limits",
|
|
"description": "Rate limit and usage information for the current API key."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"data": {
|
|
"id": "wf_abc123",
|
|
"name": "Weather Bot",
|
|
"description": "A workflow that fetches weather data",
|
|
"isDeployed": true,
|
|
"createdAt": "2026-01-15T10:30:00Z",
|
|
"updatedAt": "2026-01-15T10:30:00Z"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/jobs/{jobId}": {
|
|
"get": {
|
|
"operationId": "getJobStatus",
|
|
"summary": "Get Job Status",
|
|
"description": "Poll the status of an asynchronous workflow execution. Use the jobId returned from the Execute Workflow endpoint when the execution is queued asynchronously.",
|
|
"tags": ["Workflows"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X GET \\\n \"https://www.sim.ai/api/jobs/{jobId}\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "jobId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The job identifier returned in the async execution response.",
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "job_4a3b2c1d0e"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Current status of the job. When completed, includes the execution output.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/JobStatus"
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"taskId": "job_abc123",
|
|
"status": "completed",
|
|
"output": {
|
|
"content": "Done"
|
|
},
|
|
"metadata": {
|
|
"startTime": "2026-01-15T10:30:00Z"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/v1/logs": {
|
|
"get": {
|
|
"operationId": "queryLogs",
|
|
"summary": "Query Logs",
|
|
"description": "List workflow execution logs with advanced filtering and cursor-based pagination. Supports filtering by workflow, trigger type, date range, duration, cost, and more.",
|
|
"tags": ["Logs"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X GET \\\n \"https://www.sim.ai/api/v1/logs?workspaceId=YOUR_WORKSPACE_ID\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/WorkspaceId"
|
|
},
|
|
{
|
|
"name": "workflowIds",
|
|
"in": "query",
|
|
"description": "Comma-separated list of workflow IDs to filter by. Only logs from these workflows will be returned.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "folderIds",
|
|
"in": "query",
|
|
"description": "Comma-separated list of folder IDs. Returns logs for all workflows within these folders.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "triggers",
|
|
"in": "query",
|
|
"description": "Comma-separated trigger types to filter by: api, webhook, schedule, manual, chat.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "level",
|
|
"in": "query",
|
|
"description": "Filter logs by severity level. info for successful executions, error for failed ones.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "startDate",
|
|
"in": "query",
|
|
"description": "Only return logs after this ISO 8601 timestamp (inclusive).",
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "date-time"
|
|
}
|
|
},
|
|
{
|
|
"name": "endDate",
|
|
"in": "query",
|
|
"description": "Only return logs before this ISO 8601 timestamp (inclusive).",
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "date-time"
|
|
}
|
|
},
|
|
{
|
|
"name": "executionId",
|
|
"in": "query",
|
|
"description": "Filter by an exact execution ID. Useful for looking up a specific run.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "minDurationMs",
|
|
"in": "query",
|
|
"description": "Only return logs where execution took at least this many milliseconds.",
|
|
"schema": {
|
|
"type": "integer"
|
|
}
|
|
},
|
|
{
|
|
"name": "maxDurationMs",
|
|
"in": "query",
|
|
"description": "Only return logs where execution took at most this many milliseconds.",
|
|
"schema": {
|
|
"type": "integer"
|
|
}
|
|
},
|
|
{
|
|
"name": "minCost",
|
|
"in": "query",
|
|
"description": "Only return logs where execution cost at least this amount in USD.",
|
|
"schema": {
|
|
"type": "number"
|
|
}
|
|
},
|
|
{
|
|
"name": "maxCost",
|
|
"in": "query",
|
|
"description": "Only return logs where execution cost at most this amount in USD.",
|
|
"schema": {
|
|
"type": "number"
|
|
}
|
|
},
|
|
{
|
|
"name": "model",
|
|
"in": "query",
|
|
"description": "Filter by the AI model used during execution (e.g., gpt-4o, claude-sonnet-4-20250514).",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "details",
|
|
"in": "query",
|
|
"description": "Response detail level. basic returns summary fields only. full includes execution data, trace spans, and outputs.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "includeTraceSpans",
|
|
"in": "query",
|
|
"description": "When true, includes block-level execution trace spans with timing and input/output data.",
|
|
"schema": {
|
|
"type": "boolean"
|
|
}
|
|
},
|
|
{
|
|
"name": "includeFinalOutput",
|
|
"in": "query",
|
|
"description": "When true, includes the workflow's final output in each log entry.",
|
|
"schema": {
|
|
"type": "boolean"
|
|
}
|
|
},
|
|
{
|
|
"name": "limit",
|
|
"in": "query",
|
|
"description": "Maximum number of log entries to return per page.",
|
|
"schema": {
|
|
"type": "integer"
|
|
}
|
|
},
|
|
{
|
|
"name": "cursor",
|
|
"in": "query",
|
|
"description": "Pagination cursor returned from a previous request's nextCursor field.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "order",
|
|
"in": "query",
|
|
"description": "Sort order by execution start time. desc returns newest first.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "A paginated list of execution logs matching the filter criteria.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "array",
|
|
"description": "Array of log entries for the current page.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/LogEntry"
|
|
}
|
|
},
|
|
"nextCursor": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Cursor for fetching the next page. null when there are no more results."
|
|
},
|
|
"limits": {
|
|
"$ref": "#/components/schemas/Limits"
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"data": [
|
|
{
|
|
"id": "log_abc123",
|
|
"workflowId": "wf_abc123",
|
|
"level": "info",
|
|
"trigger": "api",
|
|
"createdAt": "2026-01-15T10:30:00Z"
|
|
}
|
|
],
|
|
"nextCursor": null
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/v1/logs/{id}": {
|
|
"get": {
|
|
"operationId": "getLogDetails",
|
|
"summary": "Get Log Details",
|
|
"description": "Retrieve detailed information about a specific log entry, including workflow metadata, execution data, and cost breakdown.",
|
|
"tags": ["Logs"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X GET \\\n \"https://www.sim.ai/api/v1/logs/{id}\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The unique identifier of the log entry.",
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "log_7x8y9z0a1b"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Detailed log entry with full execution data and cost breakdown.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"description": "The full log detail object.",
|
|
"$ref": "#/components/schemas/LogDetail"
|
|
},
|
|
"limits": {
|
|
"$ref": "#/components/schemas/Limits"
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"data": {
|
|
"id": "log_abc123",
|
|
"workflowId": "wf_abc123",
|
|
"executionId": "exec_abc123",
|
|
"level": "info",
|
|
"trigger": "api",
|
|
"totalDurationMs": 1250,
|
|
"startedAt": "2026-01-15T10:30:00Z",
|
|
"endedAt": "2026-01-15T10:30:01Z",
|
|
"createdAt": "2026-01-15T10:30:00Z"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/v1/logs/executions/{executionId}": {
|
|
"get": {
|
|
"operationId": "getExecutionDetails",
|
|
"summary": "Get Execution Details",
|
|
"description": "Retrieve the full execution state snapshot, including the workflow state at time of execution and detailed metadata.",
|
|
"tags": ["Logs"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X GET \\\n \"https://www.sim.ai/api/v1/logs/executions/{executionId}\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "executionId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The unique execution identifier.",
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "exec_9f8e7d6c5b"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Full execution state snapshot with workflow state and metadata.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"executionId": {
|
|
"type": "string",
|
|
"description": "The unique identifier for this execution."
|
|
},
|
|
"workflowId": {
|
|
"type": "string",
|
|
"description": "The workflow that was executed."
|
|
},
|
|
"workflowState": {
|
|
"type": "object",
|
|
"description": "Snapshot of the workflow configuration at the time of execution.",
|
|
"properties": {
|
|
"blocks": {
|
|
"type": "object",
|
|
"description": "Map of block IDs to their configuration and state during execution."
|
|
},
|
|
"edges": {
|
|
"type": "array",
|
|
"description": "List of connections between blocks defining the execution flow.",
|
|
"items": {
|
|
"type": "object"
|
|
}
|
|
},
|
|
"loops": {
|
|
"type": "object",
|
|
"description": "Loop configurations defining iterative execution patterns."
|
|
},
|
|
"parallels": {
|
|
"type": "object",
|
|
"description": "Parallel execution group configurations."
|
|
}
|
|
}
|
|
},
|
|
"executionMetadata": {
|
|
"type": "object",
|
|
"description": "Metadata about the execution including timing and cost information.",
|
|
"properties": {
|
|
"trigger": {
|
|
"type": "string",
|
|
"description": "How the execution was triggered (e.g., api, manual, schedule)."
|
|
},
|
|
"startedAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "ISO 8601 timestamp when execution started."
|
|
},
|
|
"endedAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "ISO 8601 timestamp when execution completed."
|
|
},
|
|
"totalDurationMs": {
|
|
"type": "integer",
|
|
"description": "Total execution duration in milliseconds."
|
|
},
|
|
"cost": {
|
|
"type": "object",
|
|
"description": "Cost breakdown for this execution including per-model details."
|
|
}
|
|
}
|
|
},
|
|
"limits": {
|
|
"$ref": "#/components/schemas/Limits"
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"executionId": "exec_abc123",
|
|
"workflowId": "wf_abc123",
|
|
"workflowState": {},
|
|
"executionMetadata": {}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/v1/audit-logs": {
|
|
"get": {
|
|
"operationId": "listAuditLogs",
|
|
"summary": "List Audit Logs",
|
|
"description": "Retrieve audit logs for your organization with cursor-based pagination. Requires an Enterprise subscription and organization admin or owner role.",
|
|
"tags": ["Audit Logs"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X GET \\\n \"https://www.sim.ai/api/v1/audit-logs?workspaceId=YOUR_WORKSPACE_ID\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "action",
|
|
"in": "query",
|
|
"description": "Filter by action type (e.g., workflow.created, workflow.deployed, member.invited).",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "resourceType",
|
|
"in": "query",
|
|
"description": "Filter by resource type (e.g., workflow, workspace, member).",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "resourceId",
|
|
"in": "query",
|
|
"description": "Filter by a specific resource ID.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"$ref": "#/components/parameters/WorkspaceId"
|
|
},
|
|
{
|
|
"name": "actorId",
|
|
"in": "query",
|
|
"description": "Filter by the user who performed the action. Must be a member of your organization.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "startDate",
|
|
"in": "query",
|
|
"description": "Only return logs after this ISO 8601 timestamp (inclusive).",
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "date-time"
|
|
}
|
|
},
|
|
{
|
|
"name": "endDate",
|
|
"in": "query",
|
|
"description": "Only return logs before this ISO 8601 timestamp (inclusive).",
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "date-time"
|
|
}
|
|
},
|
|
{
|
|
"name": "includeDeparted",
|
|
"in": "query",
|
|
"description": "When true, includes audit logs from users who have left the organization.",
|
|
"schema": {
|
|
"type": "boolean"
|
|
}
|
|
},
|
|
{
|
|
"name": "limit",
|
|
"in": "query",
|
|
"description": "Maximum number of audit log entries to return per page. Must be between 1 and 100.",
|
|
"schema": {
|
|
"type": "integer",
|
|
"minimum": 1,
|
|
"maximum": 100
|
|
}
|
|
},
|
|
{
|
|
"name": "cursor",
|
|
"in": "query",
|
|
"description": "Pagination cursor returned from a previous request's nextCursor field.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "A paginated list of audit log entries.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"type": "array",
|
|
"description": "Array of audit log entries for the current page.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/AuditLogEntry"
|
|
}
|
|
},
|
|
"nextCursor": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Cursor for fetching the next page. null when there are no more results."
|
|
},
|
|
"limits": {
|
|
"$ref": "#/components/schemas/Limits"
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"data": [
|
|
{
|
|
"id": "audit_abc123",
|
|
"action": "workflow.execute",
|
|
"actorId": "user_abc123",
|
|
"actorName": "Jane Doe",
|
|
"actorEmail": "jane@example.com",
|
|
"resourceType": "workflow",
|
|
"createdAt": "2026-01-15T10:30:00Z"
|
|
}
|
|
],
|
|
"nextCursor": null
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/v1/audit-logs/{id}": {
|
|
"get": {
|
|
"operationId": "getAuditLogDetails",
|
|
"summary": "Get Audit Log Details",
|
|
"description": "Retrieve a single audit log entry by ID. Requires an Enterprise subscription and organization admin or owner role.",
|
|
"tags": ["Audit Logs"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X GET \\\n \"https://www.sim.ai/api/v1/audit-logs/{id}\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The unique audit log entry identifier.",
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "audit_2c3d4e5f6g"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "The audit log entry.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"data": {
|
|
"description": "The audit log entry.",
|
|
"$ref": "#/components/schemas/AuditLogEntry"
|
|
},
|
|
"limits": {
|
|
"$ref": "#/components/schemas/Limits"
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"data": {
|
|
"id": "audit_abc123",
|
|
"action": "workflow.execute",
|
|
"actorId": "user_abc123",
|
|
"actorName": "Jane Doe",
|
|
"actorEmail": "jane@example.com",
|
|
"resourceType": "workflow",
|
|
"resourceId": "wf_abc123",
|
|
"metadata": {},
|
|
"createdAt": "2026-01-15T10:30:00Z"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/users/me/usage-limits": {
|
|
"get": {
|
|
"operationId": "getUsageLimits",
|
|
"summary": "Get Usage Limits",
|
|
"description": "Retrieve your current rate limits, usage spending, and storage consumption for the billing period.",
|
|
"tags": ["Usage"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X GET \\\n \"https://www.sim.ai/api/users/me/usage-limits\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Current rate limits, usage, and storage information.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/UsageLimits"
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"rateLimit": {
|
|
"sync": {
|
|
"limit": 100,
|
|
"remaining": 95,
|
|
"reset": "2026-01-15T11:00:00Z"
|
|
},
|
|
"async": {
|
|
"limit": 50,
|
|
"remaining": 48,
|
|
"reset": "2026-01-15T11:00:00Z"
|
|
}
|
|
},
|
|
"usage": {
|
|
"currentPeriodCost": 12.5,
|
|
"limit": 100.0,
|
|
"plan": "pro"
|
|
},
|
|
"storage": {
|
|
"usedBytes": 5242880,
|
|
"limitBytes": 1073741824,
|
|
"percentUsed": 0.49
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
}
|
|
},
|
|
"parameters": []
|
|
}
|
|
},
|
|
"/api/v1/tables": {
|
|
"get": {
|
|
"operationId": "listTables",
|
|
"summary": "List Tables",
|
|
"description": "List all tables in a workspace. Returns table metadata including name, schema, and row counts.",
|
|
"tags": ["Tables"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X GET \\\n \"https://www.sim.ai/api/v1/tables?workspaceId=YOUR_WORKSPACE_ID\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/WorkspaceId"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "List of tables in the workspace.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"description": "Indicates whether the request was successful."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"tables": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/Table"
|
|
},
|
|
"description": "Array of tables in the workspace."
|
|
},
|
|
"totalCount": {
|
|
"type": "integer",
|
|
"description": "Total number of tables."
|
|
}
|
|
},
|
|
"description": "Response payload."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"data": {
|
|
"tables": [
|
|
{
|
|
"id": "tbl_abc123",
|
|
"name": "contacts",
|
|
"description": "Customer contacts",
|
|
"schema": {
|
|
"columns": [
|
|
{
|
|
"name": "email",
|
|
"type": "string",
|
|
"required": true,
|
|
"unique": true
|
|
}
|
|
]
|
|
},
|
|
"rowCount": 150,
|
|
"maxRows": 10000,
|
|
"createdAt": "2026-01-15T10:30:00Z",
|
|
"updatedAt": "2026-01-15T10:30:00Z"
|
|
}
|
|
],
|
|
"totalCount": 1
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
},
|
|
"post": {
|
|
"operationId": "createTable",
|
|
"summary": "Create Table",
|
|
"description": "Create a new table in a workspace. Define the table schema with typed columns, optional constraints (required, unique), and a name.",
|
|
"tags": ["Tables"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X POST \\\n \"https://www.sim.ai/api/v1/tables\" \\\n -H \"X-API-Key: YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"workspaceId\": \"YOUR_WORKSPACE_ID\",\n \"name\": \"contacts\",\n \"description\": \"Customer contacts\",\n \"schema\": {\n \"columns\": [\n { \"name\": \"email\", \"type\": \"string\", \"required\": true, \"unique\": true },\n { \"name\": \"name\", \"type\": \"string\", \"required\": true },\n { \"name\": \"age\", \"type\": \"number\" }\n ]\n }\n }'"
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["workspaceId", "name", "schema"],
|
|
"properties": {
|
|
"workspaceId": {
|
|
"type": "string",
|
|
"description": "The workspace to create the table in."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Table name. Must start with a letter or underscore, alphanumeric and underscores only.",
|
|
"pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$"
|
|
},
|
|
"description": {
|
|
"type": "string",
|
|
"description": "Optional description of the table."
|
|
},
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["columns"],
|
|
"properties": {
|
|
"columns": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/ColumnDefinition"
|
|
},
|
|
"minItems": 1,
|
|
"description": "Column definitions for the table."
|
|
}
|
|
},
|
|
"description": "Table schema definition containing column definitions."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"workspaceId": "wsp_abc123",
|
|
"name": "contacts",
|
|
"description": "Customer contacts",
|
|
"schema": {
|
|
"columns": [
|
|
{
|
|
"name": "email",
|
|
"type": "string",
|
|
"required": true,
|
|
"unique": true
|
|
},
|
|
{
|
|
"name": "name",
|
|
"type": "string",
|
|
"required": true
|
|
},
|
|
{
|
|
"name": "age",
|
|
"type": "number"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Table created successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"description": "Indicates whether the request was successful."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"table": {
|
|
"$ref": "#/components/schemas/Table",
|
|
"description": "The newly created table."
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"description": "Confirmation message."
|
|
}
|
|
},
|
|
"description": "Response payload."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"data": {
|
|
"table": {
|
|
"id": "tbl_abc123",
|
|
"name": "contacts",
|
|
"description": "Customer contacts",
|
|
"schema": {
|
|
"columns": [
|
|
{
|
|
"name": "email",
|
|
"type": "string",
|
|
"required": true,
|
|
"unique": true
|
|
}
|
|
]
|
|
},
|
|
"rowCount": 0,
|
|
"maxRows": 10000,
|
|
"createdAt": "2026-01-15T10:30:00Z",
|
|
"updatedAt": "2026-01-15T10:30:00Z"
|
|
},
|
|
"message": "Table created successfully"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
},
|
|
"parameters": []
|
|
}
|
|
},
|
|
"/api/v1/tables/{tableId}": {
|
|
"get": {
|
|
"operationId": "getTable",
|
|
"summary": "Get Table",
|
|
"description": "Retrieve a table's metadata, schema, and row count.",
|
|
"tags": ["Tables"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X GET \\\n \"https://www.sim.ai/api/v1/tables/{tableId}?workspaceId=YOUR_WORKSPACE_ID\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/TableId"
|
|
},
|
|
{
|
|
"$ref": "#/components/parameters/WorkspaceId"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Table details.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"description": "Indicates whether the request was successful."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"table": {
|
|
"$ref": "#/components/schemas/Table",
|
|
"description": "The requested table with its metadata and schema."
|
|
}
|
|
},
|
|
"description": "Response payload."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"data": {
|
|
"table": {
|
|
"id": "tbl_abc123",
|
|
"name": "contacts",
|
|
"description": "Customer contacts",
|
|
"schema": {
|
|
"columns": [
|
|
{
|
|
"name": "email",
|
|
"type": "string",
|
|
"required": true,
|
|
"unique": true
|
|
}
|
|
]
|
|
},
|
|
"rowCount": 150,
|
|
"maxRows": 10000,
|
|
"createdAt": "2026-01-15T10:30:00Z",
|
|
"updatedAt": "2026-01-15T10:30:00Z"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
},
|
|
"delete": {
|
|
"operationId": "deleteTable",
|
|
"summary": "Delete Table",
|
|
"description": "Delete a table and all its rows. This action is irreversible.",
|
|
"tags": ["Tables"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X DELETE \\\n \"https://www.sim.ai/api/v1/tables/{tableId}?workspaceId=YOUR_WORKSPACE_ID\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/TableId"
|
|
},
|
|
{
|
|
"$ref": "#/components/parameters/WorkspaceId"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Table deleted successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"description": "Indicates whether the request was successful."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"message": {
|
|
"type": "string",
|
|
"description": "Confirmation message."
|
|
}
|
|
},
|
|
"description": "Response payload."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"data": {
|
|
"message": "Table deleted successfully"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/v1/tables/{tableId}/columns": {
|
|
"post": {
|
|
"operationId": "addColumn",
|
|
"summary": "Add Column",
|
|
"description": "Add a new column to the table schema. Optionally specify a position to insert the column at a specific index.",
|
|
"tags": ["Tables"],
|
|
"x-codeSamples": [
|
|
{
|
|
"lang": "curl",
|
|
"source": "curl -X POST \\\n \"https://www.sim.ai/api/v1/tables/{tableId}/columns\" \\\n -H \"X-API-Key: YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"workspaceId\": \"YOUR_WORKSPACE_ID\",\n \"column\": {\n \"name\": \"email\",\n \"type\": \"string\",\n \"required\": true,\n \"unique\": true\n }\n }'"
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/TableId"
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["workspaceId", "column"],
|
|
"properties": {
|
|
"workspaceId": {
|
|
"type": "string",
|
|
"description": "The workspace ID"
|
|
},
|
|
"column": {
|
|
"type": "object",
|
|
"required": ["name", "type"],
|
|
"properties": {
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Column name (alphanumeric and underscores, must start with letter or underscore)"
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"enum": ["string", "number", "boolean", "date", "json"],
|
|
"description": "Column data type"
|
|
},
|
|
"required": {
|
|
"type": "boolean",
|
|
"description": "Whether the column requires a value"
|
|
},
|
|
"unique": {
|
|
"type": "boolean",
|
|
"description": "Whether column values must be unique"
|
|
},
|
|
"position": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"description": "Position index to insert the column at (0-based). Appends if omitted."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"workspaceId": "wsp_abc123",
|
|
"column": {
|
|
"name": "phone",
|
|
"type": "string",
|
|
"required": false,
|
|
"unique": false
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Column added successfully",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean"
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"columns": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/ColumnDefinition"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"data": {
|
|
"columns": [
|
|
{
|
|
"name": "email",
|
|
"type": "string",
|
|
"required": true,
|
|
"unique": true
|
|
},
|
|
{
|
|
"name": "phone",
|
|
"type": "string",
|
|
"required": false,
|
|
"unique": false
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
},
|
|
"patch": {
|
|
"operationId": "updateColumn",
|
|
"summary": "Update Column",
|
|
"description": "Update a column's name, type, or constraints. Multiple updates can be applied in a single request. When renaming, subsequent updates (type, constraints) use the new name.",
|
|
"tags": ["Tables"],
|
|
"x-codeSamples": [
|
|
{
|
|
"lang": "curl",
|
|
"source": "curl -X PATCH \\\n \"https://www.sim.ai/api/v1/tables/{tableId}/columns\" \\\n -H \"X-API-Key: YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"workspaceId\": \"YOUR_WORKSPACE_ID\",\n \"columnName\": \"old_name\",\n \"updates\": {\n \"name\": \"new_name\",\n \"type\": \"number\"\n }\n }'"
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/TableId"
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["workspaceId", "columnName", "updates"],
|
|
"properties": {
|
|
"workspaceId": {
|
|
"type": "string",
|
|
"description": "The workspace ID"
|
|
},
|
|
"columnName": {
|
|
"type": "string",
|
|
"description": "Current name of the column to update"
|
|
},
|
|
"updates": {
|
|
"type": "object",
|
|
"properties": {
|
|
"name": {
|
|
"type": "string",
|
|
"description": "New column name"
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"enum": ["string", "number", "boolean", "date", "json"],
|
|
"description": "New column data type"
|
|
},
|
|
"required": {
|
|
"type": "boolean",
|
|
"description": "Whether the column requires a value"
|
|
},
|
|
"unique": {
|
|
"type": "boolean",
|
|
"description": "Whether column values must be unique"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"workspaceId": "wsp_abc123",
|
|
"columnName": "phone",
|
|
"updates": {
|
|
"name": "phone_number",
|
|
"type": "string",
|
|
"required": true
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Column updated successfully",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean"
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"columns": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/ColumnDefinition"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"data": {
|
|
"columns": [
|
|
{
|
|
"name": "email",
|
|
"type": "string",
|
|
"required": true,
|
|
"unique": true
|
|
},
|
|
{
|
|
"name": "phone_number",
|
|
"type": "string",
|
|
"required": true,
|
|
"unique": false
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
},
|
|
"delete": {
|
|
"operationId": "deleteColumn",
|
|
"summary": "Delete Column",
|
|
"description": "Delete a column from the table schema. This removes the column definition and strips the corresponding key from all existing row data. Cannot delete the last remaining column.",
|
|
"tags": ["Tables"],
|
|
"x-codeSamples": [
|
|
{
|
|
"lang": "curl",
|
|
"source": "curl -X DELETE \\\n \"https://www.sim.ai/api/v1/tables/{tableId}/columns\" \\\n -H \"X-API-Key: YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"workspaceId\": \"YOUR_WORKSPACE_ID\",\n \"columnName\": \"old_column\"\n }'"
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/TableId"
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["workspaceId", "columnName"],
|
|
"properties": {
|
|
"workspaceId": {
|
|
"type": "string",
|
|
"description": "The workspace ID"
|
|
},
|
|
"columnName": {
|
|
"type": "string",
|
|
"description": "Name of the column to delete"
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"workspaceId": "wsp_abc123",
|
|
"columnName": "phone_number"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Column deleted successfully",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean"
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"columns": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/ColumnDefinition"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"data": {
|
|
"columns": [
|
|
{
|
|
"name": "email",
|
|
"type": "string",
|
|
"required": true,
|
|
"unique": true
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/v1/tables/{tableId}/rows": {
|
|
"get": {
|
|
"operationId": "listRows",
|
|
"summary": "List Rows",
|
|
"description": "Query rows from a table with optional filtering, sorting, and pagination. Filters and sorts are passed as JSON-encoded query parameters.",
|
|
"tags": ["Tables"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X GET \\\n \"https://www.sim.ai/api/v1/tables/{tableId}/rows?workspaceId=YOUR_WORKSPACE_ID&limit=50&offset=0\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/TableId"
|
|
},
|
|
{
|
|
"$ref": "#/components/parameters/WorkspaceId"
|
|
},
|
|
{
|
|
"name": "filter",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "JSON-encoded filter object. Example: {\"status\": \"active\"} or {\"age\": {\"$gt\": 18}}.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "sort",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "JSON-encoded sort object. Example: {\"created_at\": \"desc\"}.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "limit",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "Maximum rows to return (1-1000, default 100).",
|
|
"schema": {
|
|
"type": "integer",
|
|
"default": 100,
|
|
"minimum": 1,
|
|
"maximum": 1000
|
|
}
|
|
},
|
|
{
|
|
"name": "offset",
|
|
"in": "query",
|
|
"required": false,
|
|
"description": "Number of rows to skip for pagination (default 0).",
|
|
"schema": {
|
|
"type": "integer",
|
|
"default": 0,
|
|
"minimum": 0
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Rows matching the query.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"description": "Indicates whether the request was successful."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"rows": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/TableRow"
|
|
},
|
|
"description": "Array of rows matching the query."
|
|
},
|
|
"rowCount": {
|
|
"type": "integer",
|
|
"description": "Number of rows returned in this response."
|
|
},
|
|
"totalCount": {
|
|
"type": "integer",
|
|
"description": "Total rows matching the filter."
|
|
},
|
|
"limit": {
|
|
"type": "integer",
|
|
"description": "The limit that was applied to the query."
|
|
},
|
|
"offset": {
|
|
"type": "integer",
|
|
"description": "The offset that was applied to the query."
|
|
}
|
|
},
|
|
"description": "Response payload."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"data": {
|
|
"rows": [
|
|
{
|
|
"id": "row_abc123",
|
|
"data": {
|
|
"email": "jane@example.com",
|
|
"name": "Jane Doe"
|
|
},
|
|
"position": 0,
|
|
"createdAt": "2026-01-15T10:30:00Z",
|
|
"updatedAt": "2026-01-15T10:30:00Z"
|
|
}
|
|
],
|
|
"rowCount": 1,
|
|
"totalCount": 1,
|
|
"limit": 100,
|
|
"offset": 0
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
},
|
|
"post": {
|
|
"operationId": "insertRows",
|
|
"summary": "Insert Rows",
|
|
"description": "Insert one or more rows into a table. For a single row, pass a `data` object. For batch insert, pass a `rows` array (up to 1000 rows).",
|
|
"tags": ["Tables"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X POST \\\n \"https://www.sim.ai/api/v1/tables/{tableId}/rows\" \\\n -H \"X-API-Key: YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"workspaceId\": \"YOUR_WORKSPACE_ID\",\n \"data\": {\n \"email\": \"user@example.com\",\n \"name\": \"Jane Doe\"\n }\n }'"
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/TableId"
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"oneOf": [
|
|
{
|
|
"type": "object",
|
|
"required": ["workspaceId", "data"],
|
|
"description": "Single row insert.",
|
|
"properties": {
|
|
"workspaceId": {
|
|
"type": "string",
|
|
"description": "The workspace that owns the table."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Key-value pairs matching the table schema."
|
|
},
|
|
"position": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"description": "Position index for the row. If omitted, the row is appended at the end of the table."
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"type": "object",
|
|
"required": ["workspaceId", "rows"],
|
|
"description": "Batch insert (up to 1000 rows).",
|
|
"properties": {
|
|
"workspaceId": {
|
|
"type": "string",
|
|
"description": "The workspace that owns the table."
|
|
},
|
|
"rows": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"additionalProperties": true
|
|
},
|
|
"minItems": 1,
|
|
"maxItems": 1000,
|
|
"description": "Array of row objects to insert. Each object contains key-value pairs matching the table schema."
|
|
},
|
|
"positions": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "integer",
|
|
"minimum": 0
|
|
},
|
|
"uniqueItems": true,
|
|
"maxItems": 1000,
|
|
"description": "Array of position indices for each row. Must be the same length as the rows array and must not contain duplicates. If omitted, rows are appended in order."
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"example": {
|
|
"workspaceId": "wsp_abc123",
|
|
"data": {
|
|
"email": "jane@example.com",
|
|
"name": "Jane Doe",
|
|
"age": 30
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Row(s) inserted successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"description": "Indicates whether the request was successful."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"row": {
|
|
"$ref": "#/components/schemas/TableRow",
|
|
"description": "The inserted row (present for single-row inserts)."
|
|
},
|
|
"rows": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/TableRow"
|
|
},
|
|
"description": "Array of inserted rows (present for batch inserts)."
|
|
},
|
|
"insertedCount": {
|
|
"type": "integer",
|
|
"description": "Number of rows successfully inserted."
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"description": "Confirmation message."
|
|
}
|
|
},
|
|
"description": "Response payload."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"data": {
|
|
"row": {
|
|
"id": "row_abc123",
|
|
"data": {
|
|
"email": "jane@example.com",
|
|
"name": "Jane Doe",
|
|
"age": 30
|
|
},
|
|
"position": 0,
|
|
"createdAt": "2026-01-15T10:30:00Z",
|
|
"updatedAt": "2026-01-15T10:30:00Z"
|
|
},
|
|
"message": "Row inserted successfully"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
},
|
|
"put": {
|
|
"operationId": "updateRows",
|
|
"summary": "Update Rows",
|
|
"description": "Bulk update rows matching a filter. All matching rows will have the specified fields updated. Validates against schema and unique constraints.",
|
|
"tags": ["Tables"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X PUT \\\n \"https://www.sim.ai/api/v1/tables/{tableId}/rows\" \\\n -H \"X-API-Key: YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"workspaceId\": \"YOUR_WORKSPACE_ID\",\n \"filter\": { \"status\": \"pending\" },\n \"data\": { \"status\": \"active\" }\n }'"
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/TableId"
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["workspaceId", "filter", "data"],
|
|
"properties": {
|
|
"workspaceId": {
|
|
"type": "string",
|
|
"description": "The workspace that owns the table."
|
|
},
|
|
"filter": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Filter criteria to match rows."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Fields to update on matching rows."
|
|
},
|
|
"limit": {
|
|
"type": "integer",
|
|
"minimum": 1,
|
|
"maximum": 1000,
|
|
"description": "Maximum number of rows to update."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"workspaceId": "wsp_abc123",
|
|
"filter": {
|
|
"status": "pending"
|
|
},
|
|
"data": {
|
|
"status": "active"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"$ref": "#/components/responses/RowsUpdated"
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
},
|
|
"delete": {
|
|
"operationId": "deleteRows",
|
|
"summary": "Delete Rows",
|
|
"description": "Delete rows by filter criteria or by an explicit list of row IDs. Pass either a `filter` object or a `rowIds` array.",
|
|
"tags": ["Tables"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X DELETE \\\n \"https://www.sim.ai/api/v1/tables/{tableId}/rows\" \\\n -H \"X-API-Key: YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"workspaceId\": \"YOUR_WORKSPACE_ID\",\n \"rowIds\": [\"row_abc123\", \"row_def456\"]\n }'"
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/TableId"
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"oneOf": [
|
|
{
|
|
"type": "object",
|
|
"required": ["workspaceId", "filter"],
|
|
"description": "Delete by filter.",
|
|
"properties": {
|
|
"workspaceId": {
|
|
"type": "string",
|
|
"description": "The workspace that owns the table."
|
|
},
|
|
"filter": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Filter criteria to match rows for deletion."
|
|
},
|
|
"limit": {
|
|
"type": "integer",
|
|
"minimum": 1,
|
|
"maximum": 1000,
|
|
"description": "Maximum number of rows to delete. Defaults to all matching rows, capped at 1000."
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"type": "object",
|
|
"required": ["workspaceId", "rowIds"],
|
|
"description": "Delete by IDs.",
|
|
"properties": {
|
|
"workspaceId": {
|
|
"type": "string",
|
|
"description": "The workspace that owns the table."
|
|
},
|
|
"rowIds": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"maxItems": 1000,
|
|
"description": "Explicit list of row IDs to delete (max 1000)."
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"example": {
|
|
"workspaceId": "wsp_abc123",
|
|
"rowIds": ["row_abc123", "row_def456"]
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Rows deleted.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"description": "Indicates whether the request was successful."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"message": {
|
|
"type": "string",
|
|
"description": "Confirmation message describing how many rows were deleted."
|
|
},
|
|
"deletedCount": {
|
|
"type": "integer",
|
|
"description": "Number of rows that were deleted."
|
|
},
|
|
"deletedRowIds": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "Array of IDs for each row that was deleted."
|
|
},
|
|
"requestedCount": {
|
|
"type": "integer",
|
|
"description": "Number of row IDs requested for deletion (only present when deleting by IDs)."
|
|
},
|
|
"missingRowIds": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "Row IDs that were requested but not found (only present when deleting by IDs)."
|
|
}
|
|
},
|
|
"description": "Response payload."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"data": {
|
|
"message": "Rows deleted successfully",
|
|
"deletedCount": 2,
|
|
"deletedRowIds": ["row_abc123", "row_def456"]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
},
|
|
"patch": {
|
|
"operationId": "batchUpdateRows",
|
|
"summary": "Batch Update Rows",
|
|
"description": "Update multiple specific rows by their IDs in a single request. Each entry in the `updates` array specifies a row ID and the fields to update. Validates against the table schema and unique constraints. Up to 1000 rows can be updated per request.",
|
|
"tags": ["Tables"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X PATCH \\\n \"https://www.sim.ai/api/v1/tables/{tableId}/rows\" \\\n -H \"X-API-Key: YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"workspaceId\": \"YOUR_WORKSPACE_ID\",\n \"updates\": [\n { \"rowId\": \"row_abc123\", \"data\": { \"status\": \"active\" } },\n { \"rowId\": \"row_def456\", \"data\": { \"status\": \"archived\" } }\n ]\n }'"
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/TableId"
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["workspaceId", "updates"],
|
|
"properties": {
|
|
"workspaceId": {
|
|
"type": "string",
|
|
"description": "The workspace that owns the table."
|
|
},
|
|
"updates": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"required": ["rowId", "data"],
|
|
"properties": {
|
|
"rowId": {
|
|
"type": "string",
|
|
"description": "The ID of the row to update."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Key-value pairs of fields to update on this row."
|
|
}
|
|
}
|
|
},
|
|
"minItems": 1,
|
|
"maxItems": 1000,
|
|
"description": "Array of update objects. Each object specifies a row ID and the fields to update. Duplicate row IDs are not allowed."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"workspaceId": "wsp_abc123",
|
|
"updates": [
|
|
{
|
|
"rowId": "row_abc123",
|
|
"data": {
|
|
"status": "active"
|
|
}
|
|
},
|
|
{
|
|
"rowId": "row_def456",
|
|
"data": {
|
|
"status": "archived"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"$ref": "#/components/responses/RowsUpdated"
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/v1/tables/{tableId}/rows/{rowId}": {
|
|
"get": {
|
|
"operationId": "getRow",
|
|
"summary": "Get Row",
|
|
"description": "Retrieve a single row by its ID.",
|
|
"tags": ["Tables"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X GET \\\n \"https://www.sim.ai/api/v1/tables/{tableId}/rows/{rowId}?workspaceId=YOUR_WORKSPACE_ID\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/TableId"
|
|
},
|
|
{
|
|
"$ref": "#/components/parameters/RowId"
|
|
},
|
|
{
|
|
"$ref": "#/components/parameters/WorkspaceId"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Row data.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"description": "Indicates whether the request was successful."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"row": {
|
|
"$ref": "#/components/schemas/TableRow",
|
|
"description": "The requested row."
|
|
}
|
|
},
|
|
"description": "Response payload."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"data": {
|
|
"row": {
|
|
"id": "row_abc123",
|
|
"data": {
|
|
"email": "jane@example.com",
|
|
"name": "Jane Doe"
|
|
},
|
|
"position": 0,
|
|
"createdAt": "2026-01-15T10:30:00Z",
|
|
"updatedAt": "2026-01-15T10:30:00Z"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
},
|
|
"patch": {
|
|
"operationId": "updateRow",
|
|
"summary": "Update Row",
|
|
"description": "Partially update a single row. Only the provided fields are updated; existing fields are preserved. Data is validated against the table schema.",
|
|
"tags": ["Tables"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X PATCH \\\n \"https://www.sim.ai/api/v1/tables/{tableId}/rows/{rowId}\" \\\n -H \"X-API-Key: YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"workspaceId\": \"YOUR_WORKSPACE_ID\",\n \"data\": { \"name\": \"Updated Name\" }\n }'"
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/TableId"
|
|
},
|
|
{
|
|
"$ref": "#/components/parameters/RowId"
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["workspaceId", "data"],
|
|
"properties": {
|
|
"workspaceId": {
|
|
"type": "string",
|
|
"description": "The workspace that owns the table."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Fields to update. Only specified fields are changed."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"workspaceId": "wsp_abc123",
|
|
"data": {
|
|
"name": "Updated Name"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Row updated.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"description": "Indicates whether the request was successful."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"row": {
|
|
"$ref": "#/components/schemas/TableRow",
|
|
"description": "The updated row with all current field values."
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"description": "Confirmation message."
|
|
}
|
|
},
|
|
"description": "Response payload."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"data": {
|
|
"row": {
|
|
"id": "row_abc123",
|
|
"data": {
|
|
"email": "jane@example.com",
|
|
"name": "Updated Name"
|
|
},
|
|
"position": 0,
|
|
"createdAt": "2026-01-15T10:30:00Z",
|
|
"updatedAt": "2026-01-16T08:00:00Z"
|
|
},
|
|
"message": "Row updated successfully"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
},
|
|
"delete": {
|
|
"operationId": "deleteRow",
|
|
"summary": "Delete Row",
|
|
"description": "Delete a single row by its ID.",
|
|
"tags": ["Tables"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X DELETE \\\n \"https://www.sim.ai/api/v1/tables/{tableId}/rows/{rowId}\" \\\n -H \"X-API-Key: YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"workspaceId\": \"YOUR_WORKSPACE_ID\"\n }'"
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/TableId"
|
|
},
|
|
{
|
|
"$ref": "#/components/parameters/RowId"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Row deleted.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"description": "Indicates whether the request was successful."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"message": {
|
|
"type": "string",
|
|
"description": "Confirmation message."
|
|
},
|
|
"deletedCount": {
|
|
"type": "integer",
|
|
"description": "Number of rows deleted (always 1 for single-row deletion)."
|
|
}
|
|
},
|
|
"description": "Response payload."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"data": {
|
|
"message": "Row deleted successfully",
|
|
"deletedCount": 1
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
},
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["workspaceId"],
|
|
"properties": {
|
|
"workspaceId": {
|
|
"type": "string",
|
|
"description": "The workspace that owns the table."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"workspaceId": "wsp_abc123"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/v1/tables/{tableId}/rows/upsert": {
|
|
"post": {
|
|
"operationId": "upsertRow",
|
|
"summary": "Upsert Row",
|
|
"description": "Insert a new row or update an existing one based on a unique column value. The table must have at least one column with a unique constraint. If a row with a matching unique value exists, it is updated; otherwise, a new row is inserted. When multiple unique columns exist, specify `conflictTarget` to indicate which column to match on.",
|
|
"tags": ["Tables"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X POST \\\n \"https://www.sim.ai/api/v1/tables/{tableId}/rows/upsert\" \\\n -H \"X-API-Key: YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"workspaceId\": \"YOUR_WORKSPACE_ID\",\n \"data\": { \"email\": \"user@example.com\", \"name\": \"John\" }\n }'"
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/TableId"
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["workspaceId", "data"],
|
|
"properties": {
|
|
"workspaceId": {
|
|
"type": "string",
|
|
"description": "The workspace ID."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Row data. Must include a value for the conflict target column."
|
|
},
|
|
"conflictTarget": {
|
|
"type": "string",
|
|
"description": "Name of the unique column to match on. Required when the table has multiple unique columns. If the table has exactly one unique column, this can be omitted."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"workspaceId": "wsp_abc123",
|
|
"data": {
|
|
"email": "user@example.com",
|
|
"name": "John Doe"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Row upserted successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"description": "Indicates whether the request was successful."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"row": {
|
|
"$ref": "#/components/schemas/TableRow",
|
|
"description": "The inserted or updated row."
|
|
},
|
|
"operation": {
|
|
"type": "string",
|
|
"enum": ["insert", "update"],
|
|
"description": "Whether the row was inserted or updated."
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"description": "Confirmation message."
|
|
}
|
|
},
|
|
"description": "Response payload."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"data": {
|
|
"row": {
|
|
"id": "row_abc123",
|
|
"data": {
|
|
"email": "user@example.com",
|
|
"name": "John Doe"
|
|
},
|
|
"createdAt": "2026-01-15T10:30:00Z",
|
|
"updatedAt": "2026-01-15T10:30:00Z"
|
|
},
|
|
"operation": "insert",
|
|
"message": "Row inserted successfully"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/v1/files": {
|
|
"get": {
|
|
"operationId": "listFiles",
|
|
"summary": "List Files",
|
|
"description": "List all files in a workspace.",
|
|
"tags": ["Files"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X GET \\\n \"https://www.sim.ai/api/v1/files?workspaceId=YOUR_WORKSPACE_ID\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/WorkspaceId"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "List of workspace files.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"description": "Whether the request completed successfully."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"files": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/FileMetadata"
|
|
},
|
|
"description": "Array of file metadata objects in the workspace."
|
|
},
|
|
"totalCount": {
|
|
"type": "integer",
|
|
"description": "Total number of files."
|
|
}
|
|
},
|
|
"description": "Response payload containing the files list and count."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"data": {
|
|
"files": [
|
|
{
|
|
"id": "file_abc123",
|
|
"name": "data.csv",
|
|
"size": 1024,
|
|
"type": "text/csv",
|
|
"key": "files/wsp_abc123/data.csv",
|
|
"uploadedBy": "user_abc123",
|
|
"uploadedAt": "2026-01-15T10:30:00Z"
|
|
}
|
|
],
|
|
"totalCount": 1
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
},
|
|
"post": {
|
|
"operationId": "uploadFile",
|
|
"summary": "Upload File",
|
|
"description": "Upload a file to a workspace. Send the file as multipart/form-data with a `file` field and a `workspaceId` field. Maximum file size is 100MB. Duplicate filenames within a workspace are not allowed.",
|
|
"tags": ["Files"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X POST \\\n \"https://www.sim.ai/api/v1/files\" \\\n -H \"X-API-Key: YOUR_API_KEY\" \\\n -F \"workspaceId=YOUR_WORKSPACE_ID\" \\\n -F \"file=@/path/to/file.csv\""
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"multipart/form-data": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["file", "workspaceId"],
|
|
"properties": {
|
|
"file": {
|
|
"type": "string",
|
|
"format": "binary",
|
|
"description": "The file to upload (max 100MB)."
|
|
},
|
|
"workspaceId": {
|
|
"type": "string",
|
|
"description": "The workspace to upload the file to."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "File uploaded successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"description": "Whether the upload completed successfully."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"file": {
|
|
"$ref": "#/components/schemas/FileMetadata",
|
|
"description": "Metadata of the newly uploaded file."
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"description": "Human-readable confirmation message."
|
|
}
|
|
},
|
|
"description": "Response payload containing the uploaded file metadata."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"data": {
|
|
"file": {
|
|
"id": "file_abc123",
|
|
"name": "data.csv",
|
|
"size": 1024,
|
|
"type": "text/csv",
|
|
"key": "files/wsp_abc123/data.csv",
|
|
"uploadedBy": "user_abc123",
|
|
"uploadedAt": "2026-01-15T10:30:00Z"
|
|
},
|
|
"message": "File uploaded successfully"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"409": {
|
|
"description": "A file with the same name already exists in this workspace.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"error": {
|
|
"type": "string",
|
|
"description": "Error message indicating a file with the same name already exists in this workspace."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
},
|
|
"parameters": []
|
|
}
|
|
},
|
|
"/api/v1/files/{fileId}": {
|
|
"get": {
|
|
"operationId": "downloadFile",
|
|
"summary": "Download File",
|
|
"description": "Download a file's content. Returns the raw file bytes with appropriate Content-Type, Content-Disposition, and Content-Length headers. File metadata is included in custom response headers: X-File-Id, X-File-Name, X-Uploaded-At.",
|
|
"tags": ["Files"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X GET \\\n \"https://www.sim.ai/api/v1/files/{fileId}?workspaceId=YOUR_WORKSPACE_ID\" \\\n -H \"X-API-Key: YOUR_API_KEY\" \\\n -o downloaded-file.csv"
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "fileId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The unique identifier of the file.",
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "wf_1709571234_abc1234"
|
|
}
|
|
},
|
|
{
|
|
"$ref": "#/components/parameters/WorkspaceId"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "File content as binary data.",
|
|
"headers": {
|
|
"Content-Type": {
|
|
"description": "MIME type of the file.",
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "text/csv"
|
|
}
|
|
},
|
|
"Content-Disposition": {
|
|
"description": "Attachment with filename.",
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "attachment; filename=\"data.csv\""
|
|
}
|
|
},
|
|
"Content-Length": {
|
|
"description": "File size in bytes.",
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "1024"
|
|
}
|
|
},
|
|
"X-File-Id": {
|
|
"description": "Unique file identifier.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"X-File-Name": {
|
|
"description": "Original filename.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"X-Uploaded-At": {
|
|
"description": "ISO 8601 upload timestamp.",
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "date-time"
|
|
}
|
|
}
|
|
},
|
|
"content": {
|
|
"application/octet-stream": {
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "binary"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
},
|
|
"delete": {
|
|
"operationId": "deleteFile",
|
|
"summary": "Delete File",
|
|
"description": "Delete a file from a workspace. This removes both the file content and its metadata. This action is irreversible.",
|
|
"tags": ["Files"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X DELETE \\\n \"https://www.sim.ai/api/v1/files/{fileId}?workspaceId=YOUR_WORKSPACE_ID\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "fileId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The unique identifier of the file to delete.",
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "wf_1709571234_abc1234"
|
|
}
|
|
},
|
|
{
|
|
"$ref": "#/components/parameters/WorkspaceId"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "File deleted successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"description": "Whether the deletion completed successfully."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"message": {
|
|
"type": "string",
|
|
"description": "Human-readable confirmation message."
|
|
}
|
|
},
|
|
"description": "Response payload containing the deletion confirmation."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"data": {
|
|
"message": "File deleted successfully"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/v1/knowledge": {
|
|
"get": {
|
|
"operationId": "listKnowledgeBases",
|
|
"summary": "List Knowledge Bases",
|
|
"description": "List all knowledge bases in a workspace.",
|
|
"tags": ["Knowledge Bases"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X GET \\\n \"https://www.sim.ai/api/v1/knowledge?workspaceId=YOUR_WORKSPACE_ID\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/WorkspaceId"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "List of knowledge bases in the workspace.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"description": "Whether the request was successful."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"knowledgeBases": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/KnowledgeBase"
|
|
},
|
|
"description": "Array of knowledge base objects in the workspace."
|
|
},
|
|
"totalCount": {
|
|
"type": "integer",
|
|
"description": "Total number of knowledge bases."
|
|
}
|
|
},
|
|
"description": "Response payload containing the list of knowledge bases."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"data": {
|
|
"knowledgeBases": [
|
|
{
|
|
"id": "kb_abc123",
|
|
"name": "Product Docs",
|
|
"description": "Product documentation and FAQs",
|
|
"docCount": 5,
|
|
"tokenCount": 25000,
|
|
"embeddingModel": "text-embedding-3-small",
|
|
"createdAt": "2026-01-15T10:30:00Z",
|
|
"updatedAt": "2026-01-15T10:30:00Z"
|
|
}
|
|
],
|
|
"totalCount": 1
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
},
|
|
"post": {
|
|
"operationId": "createKnowledgeBase",
|
|
"summary": "Create Knowledge Base",
|
|
"description": "Create a new knowledge base in a workspace. Optionally configure chunking parameters for document processing.",
|
|
"tags": ["Knowledge Bases"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X POST \\\n \"https://www.sim.ai/api/v1/knowledge\" \\\n -H \"X-API-Key: YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"workspaceId\": \"YOUR_WORKSPACE_ID\",\n \"name\": \"Product Documentation\",\n \"description\": \"Internal product docs for search\",\n \"chunkingConfig\": {\n \"maxSize\": 1024,\n \"minSize\": 100,\n \"overlap\": 200\n }\n }'"
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["workspaceId", "name"],
|
|
"properties": {
|
|
"workspaceId": {
|
|
"type": "string",
|
|
"description": "The workspace to create the knowledge base in."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Knowledge base name (1-255 characters).",
|
|
"maxLength": 255
|
|
},
|
|
"description": {
|
|
"type": "string",
|
|
"description": "Optional description (max 1000 characters).",
|
|
"maxLength": 1000
|
|
},
|
|
"chunkingConfig": {
|
|
"$ref": "#/components/schemas/ChunkingConfig",
|
|
"description": "Optional chunking configuration for document processing. Defaults to maxSize=1024, minSize=100, overlap=200 if omitted."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"workspaceId": "wsp_abc123",
|
|
"name": "Product Docs",
|
|
"description": "Product documentation and FAQs"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Knowledge base created successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"description": "Whether the request was successful."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"knowledgeBase": {
|
|
"$ref": "#/components/schemas/KnowledgeBase",
|
|
"description": "The newly created knowledge base object."
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"description": "Human-readable confirmation message."
|
|
}
|
|
},
|
|
"description": "Response payload containing the created knowledge base."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"data": {
|
|
"knowledgeBase": {
|
|
"id": "kb_abc123",
|
|
"name": "Product Docs",
|
|
"description": "Product documentation and FAQs",
|
|
"docCount": 0,
|
|
"tokenCount": 0,
|
|
"embeddingModel": "text-embedding-3-small",
|
|
"createdAt": "2026-01-15T10:30:00Z",
|
|
"updatedAt": "2026-01-15T10:30:00Z"
|
|
},
|
|
"message": "Knowledge base created successfully"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
},
|
|
"parameters": []
|
|
}
|
|
},
|
|
"/api/v1/knowledge/{id}": {
|
|
"get": {
|
|
"operationId": "getKnowledgeBase",
|
|
"summary": "Get Knowledge Base",
|
|
"description": "Get details of a specific knowledge base.",
|
|
"tags": ["Knowledge Bases"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X GET \\\n \"https://www.sim.ai/api/v1/knowledge/KB_ID?workspaceId=YOUR_WORKSPACE_ID\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "Knowledge base ID.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"$ref": "#/components/parameters/WorkspaceId"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Knowledge base details.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"description": "Whether the request was successful."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"knowledgeBase": {
|
|
"$ref": "#/components/schemas/KnowledgeBase",
|
|
"description": "The knowledge base object."
|
|
}
|
|
},
|
|
"description": "Response payload containing the knowledge base details."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"data": {
|
|
"knowledgeBase": {
|
|
"id": "kb_abc123",
|
|
"name": "Product Docs",
|
|
"description": "Product documentation and FAQs",
|
|
"docCount": 5,
|
|
"tokenCount": 25000,
|
|
"embeddingModel": "text-embedding-3-small",
|
|
"createdAt": "2026-01-15T10:30:00Z",
|
|
"updatedAt": "2026-01-15T10:30:00Z"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
},
|
|
"put": {
|
|
"operationId": "updateKnowledgeBase",
|
|
"summary": "Update Knowledge Base",
|
|
"description": "Update a knowledge base's name, description, or chunking configuration. At least one field must be provided.",
|
|
"tags": ["Knowledge Bases"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X PUT \\\n \"https://www.sim.ai/api/v1/knowledge/KB_ID\" \\\n -H \"X-API-Key: YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"workspaceId\": \"YOUR_WORKSPACE_ID\",\n \"name\": \"Updated Name\"\n }'"
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "Knowledge base ID.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["workspaceId"],
|
|
"properties": {
|
|
"workspaceId": {
|
|
"type": "string",
|
|
"description": "The workspace the knowledge base belongs to."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "New name (1-255 characters).",
|
|
"maxLength": 255
|
|
},
|
|
"description": {
|
|
"type": "string",
|
|
"description": "New description (max 1000 characters).",
|
|
"maxLength": 1000
|
|
},
|
|
"chunkingConfig": {
|
|
"$ref": "#/components/schemas/ChunkingConfig",
|
|
"description": "Updated chunking configuration. All three fields (maxSize, minSize, overlap) must be provided if included."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"workspaceId": "wsp_abc123",
|
|
"name": "Updated Product Docs",
|
|
"description": "Updated product documentation"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Knowledge base updated successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"description": "Whether the request was successful."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"knowledgeBase": {
|
|
"$ref": "#/components/schemas/KnowledgeBase",
|
|
"description": "The updated knowledge base object."
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"description": "Human-readable confirmation message."
|
|
}
|
|
},
|
|
"description": "Response payload containing the updated knowledge base."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"data": {
|
|
"knowledgeBase": {
|
|
"id": "kb_abc123",
|
|
"name": "Updated Product Docs",
|
|
"description": "Updated product documentation",
|
|
"docCount": 5,
|
|
"tokenCount": 25000,
|
|
"embeddingModel": "text-embedding-3-small",
|
|
"createdAt": "2026-01-15T10:30:00Z",
|
|
"updatedAt": "2026-01-16T08:00:00Z"
|
|
},
|
|
"message": "Knowledge base updated successfully"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
},
|
|
"delete": {
|
|
"operationId": "deleteKnowledgeBase",
|
|
"summary": "Delete Knowledge Base",
|
|
"description": "Soft-delete a knowledge base and all its documents.",
|
|
"tags": ["Knowledge Bases"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X DELETE \\\n \"https://www.sim.ai/api/v1/knowledge/KB_ID?workspaceId=YOUR_WORKSPACE_ID\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "Knowledge base ID.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"$ref": "#/components/parameters/WorkspaceId"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Knowledge base deleted successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"description": "Whether the request was successful."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"message": {
|
|
"type": "string",
|
|
"description": "Human-readable confirmation message."
|
|
}
|
|
},
|
|
"description": "Response payload."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"data": {
|
|
"message": "Knowledge base deleted successfully"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/v1/knowledge/{id}/documents": {
|
|
"get": {
|
|
"operationId": "listDocuments",
|
|
"summary": "List Documents",
|
|
"description": "List documents in a knowledge base with pagination, filtering, and sorting.",
|
|
"tags": ["Knowledge Bases"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X GET \\\n \"https://www.sim.ai/api/v1/knowledge/KB_ID/documents?workspaceId=YOUR_WORKSPACE_ID&limit=50&offset=0\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "Knowledge base ID.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"$ref": "#/components/parameters/WorkspaceId"
|
|
},
|
|
{
|
|
"name": "limit",
|
|
"in": "query",
|
|
"description": "Maximum number of documents to return (1-100, default 50).",
|
|
"schema": {
|
|
"type": "integer",
|
|
"minimum": 1,
|
|
"maximum": 100,
|
|
"default": 50
|
|
}
|
|
},
|
|
{
|
|
"name": "offset",
|
|
"in": "query",
|
|
"description": "Number of documents to skip (default 0).",
|
|
"schema": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"default": 0
|
|
}
|
|
},
|
|
{
|
|
"name": "search",
|
|
"in": "query",
|
|
"description": "Search documents by filename.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "enabledFilter",
|
|
"in": "query",
|
|
"description": "Filter by enabled status.",
|
|
"schema": {
|
|
"type": "string",
|
|
"enum": ["all", "enabled", "disabled"],
|
|
"default": "all"
|
|
}
|
|
},
|
|
{
|
|
"name": "sortBy",
|
|
"in": "query",
|
|
"description": "Field to sort by.",
|
|
"schema": {
|
|
"type": "string",
|
|
"enum": [
|
|
"filename",
|
|
"fileSize",
|
|
"tokenCount",
|
|
"chunkCount",
|
|
"uploadedAt",
|
|
"processingStatus",
|
|
"enabled"
|
|
],
|
|
"default": "uploadedAt"
|
|
}
|
|
},
|
|
{
|
|
"name": "sortOrder",
|
|
"in": "query",
|
|
"description": "Sort direction.",
|
|
"schema": {
|
|
"type": "string",
|
|
"enum": ["asc", "desc"],
|
|
"default": "desc"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "List of documents.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"description": "Whether the request was successful."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"documents": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/KnowledgeDocument"
|
|
},
|
|
"description": "Array of document objects in the knowledge base."
|
|
},
|
|
"pagination": {
|
|
"type": "object",
|
|
"properties": {
|
|
"total": {
|
|
"type": "integer",
|
|
"description": "Total number of documents matching the query."
|
|
},
|
|
"limit": {
|
|
"type": "integer",
|
|
"description": "Maximum number of documents returned per page."
|
|
},
|
|
"offset": {
|
|
"type": "integer",
|
|
"description": "Number of documents skipped from the beginning."
|
|
},
|
|
"hasMore": {
|
|
"type": "boolean",
|
|
"description": "Whether there are more documents beyond the current page."
|
|
}
|
|
},
|
|
"description": "Pagination metadata for the document list."
|
|
}
|
|
},
|
|
"description": "Response payload containing the documents and pagination info."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"data": {
|
|
"documents": [
|
|
{
|
|
"id": "doc_abc123",
|
|
"knowledgeBaseId": "kb_abc123",
|
|
"filename": "Getting Started.pdf",
|
|
"fileSize": 204800,
|
|
"mimeType": "application/pdf",
|
|
"processingStatus": "completed",
|
|
"chunkCount": 12,
|
|
"tokenCount": 3500,
|
|
"enabled": true,
|
|
"createdAt": "2026-01-15T10:30:00Z"
|
|
}
|
|
],
|
|
"pagination": {
|
|
"total": 1,
|
|
"limit": 50,
|
|
"offset": 0,
|
|
"hasMore": false
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
},
|
|
"post": {
|
|
"operationId": "uploadDocument",
|
|
"summary": "Upload Document",
|
|
"description": "Upload a document to a knowledge base. The document will be processed asynchronously (chunked and embedded). Maximum file size is 100MB.",
|
|
"tags": ["Knowledge Bases"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X POST \\\n \"https://www.sim.ai/api/v1/knowledge/KB_ID/documents\" \\\n -H \"X-API-Key: YOUR_API_KEY\" \\\n -F \"workspaceId=YOUR_WORKSPACE_ID\" \\\n -F \"file=@/path/to/document.pdf\""
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "Knowledge base ID.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"multipart/form-data": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["file", "workspaceId"],
|
|
"properties": {
|
|
"file": {
|
|
"type": "string",
|
|
"format": "binary",
|
|
"description": "The document file to upload (max 100MB)."
|
|
},
|
|
"workspaceId": {
|
|
"type": "string",
|
|
"description": "The workspace the knowledge base belongs to."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Document uploaded successfully. Processing will begin shortly.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"description": "Whether the request was successful."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"document": {
|
|
"$ref": "#/components/schemas/KnowledgeDocument",
|
|
"description": "The newly created document object with initial processing status of 'pending'."
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"description": "Human-readable confirmation message."
|
|
}
|
|
},
|
|
"description": "Response payload containing the uploaded document."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"data": {
|
|
"document": {
|
|
"id": "doc_abc123",
|
|
"knowledgeBaseId": "kb_abc123",
|
|
"filename": "Getting Started.pdf",
|
|
"fileSize": 204800,
|
|
"mimeType": "application/pdf",
|
|
"processingStatus": "pending",
|
|
"chunkCount": 0,
|
|
"tokenCount": 0,
|
|
"enabled": true,
|
|
"createdAt": "2026-01-15T10:30:00Z"
|
|
},
|
|
"message": "Document uploaded successfully. Processing will begin shortly."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
},
|
|
"409": {
|
|
"description": "A file with the same name already exists.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"error": {
|
|
"type": "string",
|
|
"description": "Error message indicating a file with the same name already exists."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"413": {
|
|
"description": "Storage limit exceeded for the workspace.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"error": {
|
|
"type": "string",
|
|
"description": "Error message indicating the workspace storage limit has been exceeded."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"415": {
|
|
"description": "Unsupported file type. See error message for supported types.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"error": {
|
|
"type": "string",
|
|
"description": "Error message indicating the file type is not supported."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/v1/knowledge/{id}/documents/{documentId}": {
|
|
"get": {
|
|
"operationId": "getDocument",
|
|
"summary": "Get Document",
|
|
"description": "Get details of a specific document in a knowledge base.",
|
|
"tags": ["Knowledge Bases"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X GET \\\n \"https://www.sim.ai/api/v1/knowledge/KB_ID/documents/DOC_ID?workspaceId=YOUR_WORKSPACE_ID\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "Knowledge base ID.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "documentId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "Document ID.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"$ref": "#/components/parameters/WorkspaceId"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Document details.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"description": "Whether the request was successful."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"document": {
|
|
"$ref": "#/components/schemas/KnowledgeDocumentDetail",
|
|
"description": "Detailed document object including processing and connector information."
|
|
}
|
|
},
|
|
"description": "Response payload containing the document details."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"data": {
|
|
"document": {
|
|
"id": "doc_abc123",
|
|
"knowledgeBaseId": "kb_abc123",
|
|
"filename": "Getting Started.pdf",
|
|
"fileSize": 204800,
|
|
"mimeType": "application/pdf",
|
|
"processingStatus": "completed",
|
|
"chunkCount": 12,
|
|
"tokenCount": 3500,
|
|
"characterCount": 18000,
|
|
"enabled": true,
|
|
"createdAt": "2026-01-15T10:30:00Z"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
},
|
|
"delete": {
|
|
"operationId": "deleteDocument",
|
|
"summary": "Delete Document",
|
|
"description": "Soft-delete a document from a knowledge base. For connector-sourced documents, this also prevents re-import on future syncs.",
|
|
"tags": ["Knowledge Bases"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X DELETE \\\n \"https://www.sim.ai/api/v1/knowledge/KB_ID/documents/DOC_ID?workspaceId=YOUR_WORKSPACE_ID\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "Knowledge base ID.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"name": "documentId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "Document ID.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"$ref": "#/components/parameters/WorkspaceId"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Document deleted successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"description": "Whether the request was successful."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"message": {
|
|
"type": "string",
|
|
"description": "Human-readable confirmation message."
|
|
}
|
|
},
|
|
"description": "Response payload."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"data": {
|
|
"message": "Document deleted successfully"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/v1/knowledge/search": {
|
|
"post": {
|
|
"operationId": "searchKnowledgeBase",
|
|
"summary": "Search Knowledge Base",
|
|
"description": "Perform vector similarity search across one or more knowledge bases. Supports semantic search via query text, tag-based filtering, or a combination of both.",
|
|
"tags": ["Knowledge Bases"],
|
|
"x-codeSamples": [
|
|
{
|
|
"id": "curl",
|
|
"label": "cURL",
|
|
"lang": "bash",
|
|
"source": "curl -X POST \\\n \"https://www.sim.ai/api/v1/knowledge/search\" \\\n -H \"X-API-Key: YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"workspaceId\": \"YOUR_WORKSPACE_ID\",\n \"knowledgeBaseIds\": [\"KB_ID\"],\n \"query\": \"How do I reset my password?\",\n \"topK\": 5\n }'"
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": ["workspaceId", "knowledgeBaseIds"],
|
|
"properties": {
|
|
"workspaceId": {
|
|
"type": "string",
|
|
"description": "The workspace containing the knowledge bases."
|
|
},
|
|
"knowledgeBaseIds": {
|
|
"oneOf": [
|
|
{
|
|
"type": "string",
|
|
"description": "A single knowledge base ID."
|
|
},
|
|
{
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "An array of knowledge base IDs to search across."
|
|
}
|
|
],
|
|
"description": "Array of knowledge base IDs to search across."
|
|
},
|
|
"query": {
|
|
"type": "string",
|
|
"description": "Search query text for semantic similarity search. Either query or tagFilters must be provided."
|
|
},
|
|
"topK": {
|
|
"type": "integer",
|
|
"minimum": 1,
|
|
"maximum": 100,
|
|
"default": 10,
|
|
"description": "Maximum number of results to return."
|
|
},
|
|
"tagFilters": {
|
|
"type": "array",
|
|
"description": "Tag-based filters. Either query or tagFilters must be provided.",
|
|
"items": {
|
|
"$ref": "#/components/schemas/TagFilter"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"workspaceId": "wsp_abc123",
|
|
"knowledgeBaseIds": ["kb_abc123"],
|
|
"query": "How do I reset my password?",
|
|
"topK": 5
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Search results.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"description": "Whether the request was successful."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"results": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/SearchResult"
|
|
},
|
|
"description": "Array of search result objects ranked by similarity."
|
|
},
|
|
"query": {
|
|
"type": "string",
|
|
"description": "The search query used."
|
|
},
|
|
"knowledgeBaseIds": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "Knowledge base IDs that were searched."
|
|
},
|
|
"topK": {
|
|
"type": "integer",
|
|
"description": "Maximum results requested."
|
|
},
|
|
"totalResults": {
|
|
"type": "integer",
|
|
"description": "Number of results returned."
|
|
}
|
|
},
|
|
"description": "Response payload containing the search results and metadata."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"data": {
|
|
"results": [
|
|
{
|
|
"documentId": "doc_abc123",
|
|
"documentName": "Getting Started.pdf",
|
|
"content": "To reset your password, go to Settings > Security.",
|
|
"chunkIndex": 3,
|
|
"similarity": 0.95,
|
|
"metadata": {}
|
|
}
|
|
],
|
|
"query": "How do I reset my password?",
|
|
"knowledgeBaseIds": ["kb_abc123"],
|
|
"topK": 5,
|
|
"totalResults": 1
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"404": {
|
|
"$ref": "#/components/responses/NotFound"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
},
|
|
"parameters": []
|
|
}
|
|
}
|
|
},
|
|
"components": {
|
|
"securitySchemes": {
|
|
"apiKey": {
|
|
"type": "apiKey",
|
|
"in": "header",
|
|
"name": "X-API-Key",
|
|
"description": "Your Sim API key (personal or workspace). Generate one from the Sim dashboard under Settings > API Keys."
|
|
}
|
|
},
|
|
"parameters": {
|
|
"TableId": {
|
|
"name": "tableId",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "tbl_abc123"
|
|
},
|
|
"description": "The unique identifier of the table."
|
|
},
|
|
"RowId": {
|
|
"name": "rowId",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "row_xyz789"
|
|
},
|
|
"description": "The unique identifier of the row."
|
|
},
|
|
"WorkspaceId": {
|
|
"name": "workspaceId",
|
|
"in": "query",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "The unique identifier of the workspace."
|
|
}
|
|
},
|
|
"schemas": {
|
|
"ColumnDefinition": {
|
|
"type": "object",
|
|
"description": "Definition of a table column including its type and constraints.",
|
|
"required": ["name", "type"],
|
|
"properties": {
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Column name. Must start with a letter or underscore.",
|
|
"example": "email",
|
|
"pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$"
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"enum": ["string", "number", "boolean", "date", "json"],
|
|
"description": "Data type of the column."
|
|
},
|
|
"required": {
|
|
"type": "boolean",
|
|
"description": "Whether the column requires a value on insert.",
|
|
"default": false
|
|
},
|
|
"unique": {
|
|
"type": "boolean",
|
|
"description": "Whether values in this column must be unique across all rows.",
|
|
"default": false
|
|
}
|
|
}
|
|
},
|
|
"Table": {
|
|
"type": "object",
|
|
"description": "A user-defined table with a typed schema.",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Unique table identifier.",
|
|
"example": "tbl_abc123"
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Table name.",
|
|
"example": "contacts"
|
|
},
|
|
"description": {
|
|
"type": "string",
|
|
"description": "Optional description of the table.",
|
|
"example": "Customer contact records"
|
|
},
|
|
"schema": {
|
|
"type": "object",
|
|
"description": "Table schema definition.",
|
|
"properties": {
|
|
"columns": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/ColumnDefinition"
|
|
},
|
|
"description": "Array of column definitions for the table."
|
|
}
|
|
}
|
|
},
|
|
"rowCount": {
|
|
"type": "integer",
|
|
"description": "Current number of rows in the table."
|
|
},
|
|
"maxRows": {
|
|
"type": "integer",
|
|
"description": "Maximum rows allowed by the current billing plan."
|
|
},
|
|
"createdAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "ISO 8601 timestamp when the table was created."
|
|
},
|
|
"updatedAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "ISO 8601 timestamp when the table was last modified."
|
|
}
|
|
}
|
|
},
|
|
"TableRow": {
|
|
"type": "object",
|
|
"description": "A single row in a table.",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Unique row identifier.",
|
|
"example": "row_xyz789"
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"description": "Row data as key-value pairs matching the table schema."
|
|
},
|
|
"position": {
|
|
"type": "integer",
|
|
"description": "Row's position/order in the table."
|
|
},
|
|
"createdAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "ISO 8601 timestamp when the row was created."
|
|
},
|
|
"updatedAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "ISO 8601 timestamp when the row was last modified."
|
|
}
|
|
}
|
|
},
|
|
"WorkflowSummary": {
|
|
"type": "object",
|
|
"description": "Summary representation of a workflow returned in list operations.",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Unique workflow identifier.",
|
|
"example": "wf_1a2b3c4d5e"
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Human-readable workflow name.",
|
|
"example": "Customer Support Agent"
|
|
},
|
|
"description": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Optional description of what the workflow does.",
|
|
"example": "Routes incoming support tickets and drafts responses"
|
|
},
|
|
"color": {
|
|
"type": "string",
|
|
"description": "Hex color code used for the workflow icon in the dashboard (e.g., #33c482).",
|
|
"example": "#33c482"
|
|
},
|
|
"folderId": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "The folder this workflow belongs to. null if at the workspace root.",
|
|
"example": "folder_abc123"
|
|
},
|
|
"workspaceId": {
|
|
"type": "string",
|
|
"description": "The workspace this workflow belongs to.",
|
|
"example": "ws_xyz789"
|
|
},
|
|
"isDeployed": {
|
|
"type": "boolean",
|
|
"description": "Whether the workflow is currently deployed and available for API execution.",
|
|
"example": true
|
|
},
|
|
"deployedAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"nullable": true,
|
|
"description": "ISO 8601 timestamp of the most recent deployment. null if never deployed.",
|
|
"example": "2025-06-15T10:30:00Z"
|
|
},
|
|
"runCount": {
|
|
"type": "integer",
|
|
"description": "Total number of times this workflow has been executed.",
|
|
"example": 142
|
|
},
|
|
"lastRunAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"nullable": true,
|
|
"description": "ISO 8601 timestamp of the most recent execution. null if never run.",
|
|
"example": "2025-06-20T14:15:22Z"
|
|
},
|
|
"createdAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "ISO 8601 timestamp when the workflow was created.",
|
|
"example": "2025-01-10T09:00:00Z"
|
|
},
|
|
"updatedAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "ISO 8601 timestamp when the workflow was last modified.",
|
|
"example": "2025-06-18T16:45:00Z"
|
|
}
|
|
}
|
|
},
|
|
"WorkflowDetail": {
|
|
"type": "object",
|
|
"description": "Full workflow representation including input field definitions and configuration.",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Unique workflow identifier.",
|
|
"example": "wf_1a2b3c4d5e"
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Human-readable workflow name.",
|
|
"example": "Customer Support Agent"
|
|
},
|
|
"description": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Optional description of what the workflow does.",
|
|
"example": "Routes incoming support tickets and drafts responses"
|
|
},
|
|
"color": {
|
|
"type": "string",
|
|
"description": "Hex color code used for the workflow icon in the dashboard.",
|
|
"example": "#33c482"
|
|
},
|
|
"folderId": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "The folder this workflow belongs to. null if at the workspace root.",
|
|
"example": "folder_abc123"
|
|
},
|
|
"workspaceId": {
|
|
"type": "string",
|
|
"description": "The workspace this workflow belongs to.",
|
|
"example": "ws_xyz789"
|
|
},
|
|
"isDeployed": {
|
|
"type": "boolean",
|
|
"description": "Whether the workflow is currently deployed and available for API execution.",
|
|
"example": true
|
|
},
|
|
"deployedAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"nullable": true,
|
|
"description": "ISO 8601 timestamp of the most recent deployment. null if never deployed.",
|
|
"example": "2025-06-15T10:30:00Z"
|
|
},
|
|
"runCount": {
|
|
"type": "integer",
|
|
"description": "Total number of times this workflow has been executed.",
|
|
"example": 142
|
|
},
|
|
"lastRunAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"nullable": true,
|
|
"description": "ISO 8601 timestamp of the most recent execution. null if never run.",
|
|
"example": "2025-06-20T14:15:22Z"
|
|
},
|
|
"variables": {
|
|
"type": "object",
|
|
"description": "Workflow-level variables and their current values.",
|
|
"example": {}
|
|
},
|
|
"inputs": {
|
|
"type": "object",
|
|
"description": "The workflow's input field definitions. Use these to construct the input object when executing the workflow.",
|
|
"properties": {
|
|
"fields": {
|
|
"type": "object",
|
|
"description": "Map of field names to their type definitions and configuration.",
|
|
"additionalProperties": true,
|
|
"example": {}
|
|
}
|
|
}
|
|
},
|
|
"createdAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "ISO 8601 timestamp when the workflow was created.",
|
|
"example": "2025-01-10T09:00:00Z"
|
|
},
|
|
"updatedAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "ISO 8601 timestamp when the workflow was last modified.",
|
|
"example": "2025-06-18T16:45:00Z"
|
|
}
|
|
}
|
|
},
|
|
"ExecutionResult": {
|
|
"type": "object",
|
|
"description": "Result of a synchronous workflow execution.",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"description": "Whether the workflow executed successfully without errors.",
|
|
"example": true
|
|
},
|
|
"executionId": {
|
|
"type": "string",
|
|
"description": "Unique identifier for this execution. Use this to query logs or cancel the execution.",
|
|
"example": "exec_9f8e7d6c5b"
|
|
},
|
|
"output": {
|
|
"type": "object",
|
|
"description": "Workflow output keyed by block name and output field. Structure depends on the workflow's block configuration.",
|
|
"additionalProperties": true,
|
|
"example": {
|
|
"result": "Hello, world!"
|
|
}
|
|
},
|
|
"error": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Error message if the execution failed. null on success.",
|
|
"example": null
|
|
},
|
|
"metadata": {
|
|
"type": "object",
|
|
"description": "Execution timing metadata.",
|
|
"properties": {
|
|
"duration": {
|
|
"type": "integer",
|
|
"description": "Total execution duration in milliseconds.",
|
|
"example": 1250
|
|
},
|
|
"startTime": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "ISO 8601 timestamp when execution started.",
|
|
"example": "2025-06-20T14:15:22Z"
|
|
},
|
|
"endTime": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "ISO 8601 timestamp when execution completed.",
|
|
"example": "2025-06-20T14:15:23Z"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"AsyncExecutionResult": {
|
|
"type": "object",
|
|
"description": "Response returned when a workflow execution is queued for asynchronous processing.",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"description": "Whether the execution was successfully queued.",
|
|
"example": true
|
|
},
|
|
"async": {
|
|
"type": "boolean",
|
|
"description": "Always true for async executions. Use this to distinguish from synchronous responses.",
|
|
"example": true
|
|
},
|
|
"jobId": {
|
|
"type": "string",
|
|
"description": "Internal job queue identifier for tracking the execution.",
|
|
"example": "job_4a3b2c1d0e"
|
|
},
|
|
"executionId": {
|
|
"type": "string",
|
|
"description": "Unique execution identifier. Use this to query execution status or cancel.",
|
|
"example": "exec_9f8e7d6c5b"
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"description": "Human-readable status message (e.g., \"Execution queued\").",
|
|
"example": "Execution queued"
|
|
},
|
|
"statusUrl": {
|
|
"type": "string",
|
|
"format": "uri",
|
|
"description": "URL to poll for execution status and results. Returns the full execution result once complete.",
|
|
"example": "https://www.sim.ai/api/jobs/job_4a3b2c1d0e"
|
|
}
|
|
}
|
|
},
|
|
"LogEntry": {
|
|
"type": "object",
|
|
"description": "Summary of a single workflow execution log entry.",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Unique log entry identifier.",
|
|
"example": "log_7x8y9z0a1b"
|
|
},
|
|
"workflowId": {
|
|
"type": "string",
|
|
"description": "The workflow that was executed.",
|
|
"example": "wf_1a2b3c4d5e"
|
|
},
|
|
"executionId": {
|
|
"type": "string",
|
|
"description": "Unique execution identifier for this run.",
|
|
"example": "exec_9f8e7d6c5b"
|
|
},
|
|
"level": {
|
|
"type": "string",
|
|
"description": "Log severity. info for successful executions, error for failures.",
|
|
"example": "info"
|
|
},
|
|
"trigger": {
|
|
"type": "string",
|
|
"description": "How the execution was triggered (e.g., api, manual, webhook, schedule, chat).",
|
|
"example": "api"
|
|
},
|
|
"startedAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "ISO 8601 timestamp when execution started.",
|
|
"example": "2025-06-20T14:15:22Z"
|
|
},
|
|
"endedAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "ISO 8601 timestamp when execution completed.",
|
|
"example": "2025-06-20T14:15:23Z"
|
|
},
|
|
"totalDurationMs": {
|
|
"type": "integer",
|
|
"description": "Total execution duration in milliseconds.",
|
|
"example": 1250
|
|
},
|
|
"cost": {
|
|
"type": "object",
|
|
"description": "Cost summary for this execution.",
|
|
"properties": {
|
|
"total": {
|
|
"type": "number",
|
|
"description": "Total cost of this execution in USD.",
|
|
"example": 0.0032
|
|
}
|
|
}
|
|
},
|
|
"files": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"description": "File outputs produced during execution. null if no files were generated.",
|
|
"example": null
|
|
}
|
|
}
|
|
},
|
|
"LogDetail": {
|
|
"type": "object",
|
|
"description": "Detailed log entry with full execution data, workflow metadata, and cost breakdown.",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Unique log entry identifier.",
|
|
"example": "log_7x8y9z0a1b"
|
|
},
|
|
"workflowId": {
|
|
"type": "string",
|
|
"description": "The workflow that was executed.",
|
|
"example": "wf_1a2b3c4d5e"
|
|
},
|
|
"executionId": {
|
|
"type": "string",
|
|
"description": "Unique execution identifier for this run.",
|
|
"example": "exec_9f8e7d6c5b"
|
|
},
|
|
"level": {
|
|
"type": "string",
|
|
"description": "Log severity. info for successful executions, error for failures.",
|
|
"example": "info"
|
|
},
|
|
"trigger": {
|
|
"type": "string",
|
|
"description": "How the execution was triggered (e.g., api, manual, webhook, schedule, chat).",
|
|
"example": "api"
|
|
},
|
|
"startedAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "ISO 8601 timestamp when execution started.",
|
|
"example": "2025-06-20T14:15:22Z"
|
|
},
|
|
"endedAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "ISO 8601 timestamp when execution completed.",
|
|
"example": "2025-06-20T14:15:23Z"
|
|
},
|
|
"totalDurationMs": {
|
|
"type": "integer",
|
|
"description": "Total execution duration in milliseconds.",
|
|
"example": 1250
|
|
},
|
|
"workflow": {
|
|
"type": "object",
|
|
"description": "Summary metadata about the workflow at the time of execution.",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Unique workflow identifier.",
|
|
"example": "wf_1a2b3c4d5e"
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Workflow name at the time of execution.",
|
|
"example": "Customer Support Agent"
|
|
},
|
|
"description": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Workflow description at the time of execution.",
|
|
"example": "Routes incoming support tickets and drafts responses"
|
|
}
|
|
}
|
|
},
|
|
"executionData": {
|
|
"type": "object",
|
|
"description": "Detailed execution data including block-level traces and final output.",
|
|
"properties": {
|
|
"traceSpans": {
|
|
"type": "array",
|
|
"description": "Block-level execution traces with timing, inputs, and outputs for each block that ran.",
|
|
"items": {
|
|
"type": "object"
|
|
}
|
|
},
|
|
"finalOutput": {
|
|
"type": "object",
|
|
"description": "The workflow's final output after all blocks completed."
|
|
}
|
|
}
|
|
},
|
|
"cost": {
|
|
"type": "object",
|
|
"description": "Detailed cost breakdown for this execution.",
|
|
"properties": {
|
|
"total": {
|
|
"type": "number",
|
|
"description": "Total cost of this execution in USD.",
|
|
"example": 0.0032
|
|
},
|
|
"tokens": {
|
|
"type": "object",
|
|
"description": "Aggregate token usage across all AI model calls in this execution.",
|
|
"properties": {
|
|
"prompt": {
|
|
"type": "integer",
|
|
"description": "Total prompt (input) tokens consumed.",
|
|
"example": 450
|
|
},
|
|
"completion": {
|
|
"type": "integer",
|
|
"description": "Total completion (output) tokens generated.",
|
|
"example": 120
|
|
},
|
|
"total": {
|
|
"type": "integer",
|
|
"description": "Total tokens (prompt + completion).",
|
|
"example": 570
|
|
}
|
|
}
|
|
},
|
|
"models": {
|
|
"type": "object",
|
|
"description": "Per-model cost and token breakdown. Keys are model identifiers (e.g., gpt-4o, claude-sonnet-4-20250514).",
|
|
"additionalProperties": {
|
|
"type": "object",
|
|
"description": "Cost and token details for a specific model.",
|
|
"properties": {
|
|
"input": {
|
|
"type": "number",
|
|
"description": "Cost of prompt tokens for this model in USD."
|
|
},
|
|
"output": {
|
|
"type": "number",
|
|
"description": "Cost of completion tokens for this model in USD."
|
|
},
|
|
"total": {
|
|
"type": "number",
|
|
"description": "Total cost for this model in USD."
|
|
},
|
|
"tokens": {
|
|
"type": "object",
|
|
"description": "Token usage for this specific model.",
|
|
"properties": {
|
|
"prompt": {
|
|
"type": "integer",
|
|
"description": "Prompt tokens consumed by this model."
|
|
},
|
|
"completion": {
|
|
"type": "integer",
|
|
"description": "Completion tokens generated by this model."
|
|
},
|
|
"total": {
|
|
"type": "integer",
|
|
"description": "Total tokens for this model."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"Limits": {
|
|
"type": "object",
|
|
"description": "Rate limit and usage information included in every API response.",
|
|
"properties": {
|
|
"workflowExecutionRateLimit": {
|
|
"type": "object",
|
|
"description": "Current rate limit status for workflow executions.",
|
|
"properties": {
|
|
"sync": {
|
|
"description": "Rate limit bucket for synchronous executions.",
|
|
"$ref": "#/components/schemas/RateLimitBucket"
|
|
},
|
|
"async": {
|
|
"description": "Rate limit bucket for asynchronous executions.",
|
|
"$ref": "#/components/schemas/RateLimitBucket"
|
|
}
|
|
}
|
|
},
|
|
"usage": {
|
|
"type": "object",
|
|
"description": "Current billing period usage and plan limits.",
|
|
"properties": {
|
|
"currentPeriodCost": {
|
|
"type": "number",
|
|
"description": "Total spend in the current billing period in USD.",
|
|
"example": 1.25
|
|
},
|
|
"limit": {
|
|
"type": "number",
|
|
"description": "Maximum allowed spend for the current billing period in USD.",
|
|
"example": 50.0
|
|
},
|
|
"plan": {
|
|
"type": "string",
|
|
"description": "Your current subscription plan (e.g., free, pro, team).",
|
|
"example": "pro"
|
|
},
|
|
"isExceeded": {
|
|
"type": "boolean",
|
|
"description": "Whether the usage limit has been exceeded. Executions may be blocked when true.",
|
|
"example": false
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"RateLimitBucket": {
|
|
"type": "object",
|
|
"description": "Rate limit status for a specific execution type.",
|
|
"properties": {
|
|
"requestsPerMinute": {
|
|
"type": "integer",
|
|
"description": "Maximum number of requests allowed per minute.",
|
|
"example": 60
|
|
},
|
|
"maxBurst": {
|
|
"type": "integer",
|
|
"description": "Maximum number of concurrent requests allowed in a burst.",
|
|
"example": 10
|
|
},
|
|
"remaining": {
|
|
"type": "integer",
|
|
"description": "Number of requests remaining in the current rate limit window.",
|
|
"example": 59
|
|
},
|
|
"resetAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "ISO 8601 timestamp when the rate limit window resets.",
|
|
"example": "2025-06-20T14:16:00Z"
|
|
}
|
|
}
|
|
},
|
|
"JobStatus": {
|
|
"type": "object",
|
|
"description": "Status of an asynchronous job.",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"description": "Whether the request was successful.",
|
|
"example": true
|
|
},
|
|
"taskId": {
|
|
"type": "string",
|
|
"description": "The unique identifier of the job.",
|
|
"example": "job_4a3b2c1d0e"
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"enum": ["queued", "processing", "completed", "failed"],
|
|
"description": "Current status of the job.",
|
|
"example": "completed"
|
|
},
|
|
"metadata": {
|
|
"type": "object",
|
|
"description": "Timing metadata for the job.",
|
|
"properties": {
|
|
"startedAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "ISO 8601 timestamp when the job started processing.",
|
|
"example": "2025-06-20T14:15:22Z"
|
|
},
|
|
"completedAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "ISO 8601 timestamp when the job completed. Present only when status is completed or failed.",
|
|
"example": "2025-06-20T14:15:23Z"
|
|
},
|
|
"duration": {
|
|
"type": "integer",
|
|
"description": "Duration of the job in milliseconds. Present only when status is completed or failed.",
|
|
"example": 1250
|
|
}
|
|
}
|
|
},
|
|
"output": {
|
|
"description": "The workflow execution output. Present only when status is completed.",
|
|
"type": "object",
|
|
"example": {
|
|
"result": "Hello, world!"
|
|
}
|
|
},
|
|
"error": {
|
|
"description": "Error details. Present only when status is failed.",
|
|
"type": "string",
|
|
"example": null
|
|
},
|
|
"estimatedDuration": {
|
|
"type": "integer",
|
|
"description": "Estimated duration in milliseconds. Present only when status is queued or processing.",
|
|
"example": 2000
|
|
}
|
|
}
|
|
},
|
|
"AuditLogEntry": {
|
|
"type": "object",
|
|
"description": "An enterprise audit log entry recording an action taken in the workspace.",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Unique identifier for the audit log entry.",
|
|
"example": "audit_2c3d4e5f6g"
|
|
},
|
|
"workspaceId": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "The workspace where the action occurred.",
|
|
"example": "ws_xyz789"
|
|
},
|
|
"actorId": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "The user ID of the person who performed the action.",
|
|
"example": "user_abc123"
|
|
},
|
|
"actorName": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Display name of the person who performed the action.",
|
|
"example": "Jane Smith"
|
|
},
|
|
"actorEmail": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Email address of the person who performed the action.",
|
|
"example": "jane@example.com"
|
|
},
|
|
"action": {
|
|
"type": "string",
|
|
"description": "The action that was performed (e.g., workflow.created, member.invited).",
|
|
"example": "workflow.deployed"
|
|
},
|
|
"resourceType": {
|
|
"type": "string",
|
|
"description": "The type of resource affected (e.g., workflow, workspace, member).",
|
|
"example": "workflow"
|
|
},
|
|
"resourceId": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "The unique identifier of the affected resource.",
|
|
"example": "wf_1a2b3c4d5e"
|
|
},
|
|
"resourceName": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Display name of the affected resource.",
|
|
"example": "Customer Support Agent"
|
|
},
|
|
"description": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Human-readable description of the action.",
|
|
"example": "Deployed workflow Customer Support Agent"
|
|
},
|
|
"metadata": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"description": "Additional context about the action.",
|
|
"example": null
|
|
},
|
|
"createdAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "ISO 8601 timestamp when the action occurred.",
|
|
"example": "2025-06-20T14:15:22Z"
|
|
}
|
|
}
|
|
},
|
|
"UsageLimits": {
|
|
"type": "object",
|
|
"description": "Current rate limits, usage, and storage information for the authenticated user.",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"description": "Whether the request was successful."
|
|
},
|
|
"rateLimit": {
|
|
"type": "object",
|
|
"description": "Rate limit status for workflow executions.",
|
|
"properties": {
|
|
"sync": {
|
|
"description": "Rate limit bucket for synchronous executions.",
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/RateLimitBucket"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"isLimited": {
|
|
"type": "boolean",
|
|
"description": "Whether the rate limit has been reached."
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"async": {
|
|
"description": "Rate limit bucket for asynchronous executions.",
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/RateLimitBucket"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"isLimited": {
|
|
"type": "boolean",
|
|
"description": "Whether the rate limit has been reached."
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"authType": {
|
|
"type": "string",
|
|
"description": "The authentication type used (api or manual)."
|
|
}
|
|
}
|
|
},
|
|
"usage": {
|
|
"type": "object",
|
|
"description": "Current billing period usage.",
|
|
"properties": {
|
|
"currentPeriodCost": {
|
|
"type": "number",
|
|
"description": "Total spend in the current billing period in USD."
|
|
},
|
|
"limit": {
|
|
"type": "number",
|
|
"description": "Maximum allowed spend for the current billing period in USD."
|
|
},
|
|
"plan": {
|
|
"type": "string",
|
|
"description": "Your current subscription plan (e.g., free, pro, team)."
|
|
}
|
|
}
|
|
},
|
|
"storage": {
|
|
"type": "object",
|
|
"description": "File storage usage.",
|
|
"properties": {
|
|
"usedBytes": {
|
|
"type": "integer",
|
|
"description": "Total storage used in bytes."
|
|
},
|
|
"limitBytes": {
|
|
"type": "integer",
|
|
"description": "Maximum storage allowed in bytes."
|
|
},
|
|
"percentUsed": {
|
|
"type": "number",
|
|
"description": "Percentage of storage used (0-100)."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"FileMetadata": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Unique file identifier.",
|
|
"example": "wf_1709571234_abc1234"
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Original filename.",
|
|
"example": "data.csv"
|
|
},
|
|
"size": {
|
|
"type": "integer",
|
|
"description": "File size in bytes.",
|
|
"example": 1024
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"description": "MIME type of the file.",
|
|
"example": "text/csv"
|
|
},
|
|
"key": {
|
|
"type": "string",
|
|
"description": "Storage key for the file.",
|
|
"example": "workspace/abc-123/1709571234-xyz-data.csv"
|
|
},
|
|
"uploadedBy": {
|
|
"type": "string",
|
|
"description": "User ID of the uploader."
|
|
},
|
|
"uploadedAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "ISO 8601 timestamp of when the file was uploaded."
|
|
}
|
|
}
|
|
},
|
|
"KnowledgeBase": {
|
|
"type": "object",
|
|
"description": "A knowledge base for storing and searching document embeddings.",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Unique knowledge base identifier."
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Knowledge base name."
|
|
},
|
|
"description": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Optional description."
|
|
},
|
|
"tokenCount": {
|
|
"type": "integer",
|
|
"description": "Total token count across all documents."
|
|
},
|
|
"embeddingModel": {
|
|
"type": "string",
|
|
"description": "Embedding model used (e.g. text-embedding-3-small)."
|
|
},
|
|
"embeddingDimension": {
|
|
"type": "integer",
|
|
"description": "Embedding vector dimension."
|
|
},
|
|
"chunkingConfig": {
|
|
"$ref": "#/components/schemas/ChunkingConfig"
|
|
},
|
|
"docCount": {
|
|
"type": "integer",
|
|
"description": "Number of documents in the knowledge base."
|
|
},
|
|
"connectorTypes": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "Types of connectors attached to this knowledge base."
|
|
},
|
|
"createdAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "ISO 8601 timestamp when the knowledge base was created."
|
|
},
|
|
"updatedAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "ISO 8601 timestamp when the knowledge base was last modified."
|
|
}
|
|
}
|
|
},
|
|
"ChunkingConfig": {
|
|
"type": "object",
|
|
"description": "Configuration for how documents are split into chunks for embedding.",
|
|
"properties": {
|
|
"maxSize": {
|
|
"type": "integer",
|
|
"minimum": 100,
|
|
"maximum": 4000,
|
|
"default": 1024,
|
|
"description": "Maximum chunk size in tokens."
|
|
},
|
|
"minSize": {
|
|
"type": "integer",
|
|
"minimum": 1,
|
|
"maximum": 2000,
|
|
"default": 100,
|
|
"description": "Minimum chunk size in characters."
|
|
},
|
|
"overlap": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"maximum": 500,
|
|
"default": 200,
|
|
"description": "Overlap between chunks in tokens."
|
|
}
|
|
}
|
|
},
|
|
"KnowledgeDocument": {
|
|
"type": "object",
|
|
"description": "A document in a knowledge base.",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Unique document identifier."
|
|
},
|
|
"knowledgeBaseId": {
|
|
"type": "string",
|
|
"description": "Knowledge base this document belongs to."
|
|
},
|
|
"filename": {
|
|
"type": "string",
|
|
"description": "Original filename."
|
|
},
|
|
"fileSize": {
|
|
"type": "integer",
|
|
"description": "File size in bytes."
|
|
},
|
|
"mimeType": {
|
|
"type": "string",
|
|
"description": "MIME type of the file."
|
|
},
|
|
"processingStatus": {
|
|
"type": "string",
|
|
"enum": ["pending", "processing", "completed", "failed"],
|
|
"description": "Current processing status."
|
|
},
|
|
"chunkCount": {
|
|
"type": "integer",
|
|
"description": "Number of chunks created from this document."
|
|
},
|
|
"tokenCount": {
|
|
"type": "integer",
|
|
"description": "Total token count."
|
|
},
|
|
"characterCount": {
|
|
"type": "integer",
|
|
"description": "Total character count."
|
|
},
|
|
"enabled": {
|
|
"type": "boolean",
|
|
"description": "Whether the document is enabled for search."
|
|
},
|
|
"createdAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "ISO 8601 timestamp when the document was uploaded."
|
|
}
|
|
}
|
|
},
|
|
"KnowledgeDocumentDetail": {
|
|
"type": "object",
|
|
"description": "Detailed document information including processing and connector details.",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Unique document identifier."
|
|
},
|
|
"knowledgeBaseId": {
|
|
"type": "string",
|
|
"description": "Knowledge base this document belongs to."
|
|
},
|
|
"filename": {
|
|
"type": "string",
|
|
"description": "Original filename."
|
|
},
|
|
"fileSize": {
|
|
"type": "integer",
|
|
"description": "File size in bytes."
|
|
},
|
|
"mimeType": {
|
|
"type": "string",
|
|
"description": "MIME type of the file."
|
|
},
|
|
"processingStatus": {
|
|
"type": "string",
|
|
"enum": ["pending", "processing", "completed", "failed"],
|
|
"description": "Current processing status."
|
|
},
|
|
"processingError": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Error message if processing failed."
|
|
},
|
|
"processingStartedAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"nullable": true,
|
|
"description": "When processing started."
|
|
},
|
|
"processingCompletedAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"nullable": true,
|
|
"description": "When processing completed."
|
|
},
|
|
"chunkCount": {
|
|
"type": "integer",
|
|
"description": "Number of chunks created."
|
|
},
|
|
"tokenCount": {
|
|
"type": "integer",
|
|
"description": "Total token count."
|
|
},
|
|
"characterCount": {
|
|
"type": "integer",
|
|
"description": "Total character count."
|
|
},
|
|
"enabled": {
|
|
"type": "boolean",
|
|
"description": "Whether the document is enabled for search."
|
|
},
|
|
"connectorId": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Connector ID if sourced from an external connector."
|
|
},
|
|
"connectorType": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Connector type (e.g. google-drive, notion)."
|
|
},
|
|
"sourceUrl": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Original source URL for connector-sourced documents."
|
|
},
|
|
"createdAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "ISO 8601 timestamp when the document was uploaded."
|
|
}
|
|
}
|
|
},
|
|
"SearchResult": {
|
|
"type": "object",
|
|
"description": "A single search result from knowledge base vector search.",
|
|
"properties": {
|
|
"documentId": {
|
|
"type": "string",
|
|
"description": "ID of the source document."
|
|
},
|
|
"documentName": {
|
|
"type": "string",
|
|
"description": "Filename of the source document."
|
|
},
|
|
"content": {
|
|
"type": "string",
|
|
"description": "The matched chunk content."
|
|
},
|
|
"chunkIndex": {
|
|
"type": "integer",
|
|
"description": "Index of the chunk within the document."
|
|
},
|
|
"metadata": {
|
|
"type": "object",
|
|
"description": "Tag metadata associated with the chunk (display names mapped to values)."
|
|
},
|
|
"similarity": {
|
|
"type": "number",
|
|
"minimum": 0,
|
|
"maximum": 1,
|
|
"description": "Similarity score (0-1, where 1 is most similar)."
|
|
}
|
|
}
|
|
},
|
|
"TagFilter": {
|
|
"type": "object",
|
|
"description": "A tag-based filter for knowledge base search.",
|
|
"required": ["tagName", "value"],
|
|
"properties": {
|
|
"tagName": {
|
|
"type": "string",
|
|
"description": "Display name of the tag to filter by."
|
|
},
|
|
"fieldType": {
|
|
"type": "string",
|
|
"enum": ["text", "number", "date", "boolean"],
|
|
"default": "text",
|
|
"description": "Data type of the tag field."
|
|
},
|
|
"operator": {
|
|
"type": "string",
|
|
"default": "eq",
|
|
"description": "Comparison operator (e.g. eq, neq, gt, lt, gte, lte, contains, between)."
|
|
},
|
|
"value": {
|
|
"oneOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "number"
|
|
},
|
|
{
|
|
"type": "boolean"
|
|
}
|
|
],
|
|
"description": "Value to filter by."
|
|
},
|
|
"valueTo": {
|
|
"oneOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "number"
|
|
}
|
|
],
|
|
"description": "Upper bound value for 'between' operator."
|
|
}
|
|
}
|
|
},
|
|
"PausedExecutionSummary": {
|
|
"type": "object",
|
|
"description": "Summary of a paused workflow execution.",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Unique identifier for the paused execution record."
|
|
},
|
|
"workflowId": {
|
|
"type": "string",
|
|
"description": "The workflow this execution belongs to."
|
|
},
|
|
"executionId": {
|
|
"type": "string",
|
|
"description": "The execution that was paused."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"description": "Current status of the paused execution.",
|
|
"example": "paused"
|
|
},
|
|
"totalPauseCount": {
|
|
"type": "integer",
|
|
"description": "Total number of pause points in this execution."
|
|
},
|
|
"resumedCount": {
|
|
"type": "integer",
|
|
"description": "Number of pause points that have been resumed."
|
|
},
|
|
"pausedAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"nullable": true,
|
|
"description": "When the execution was paused."
|
|
},
|
|
"updatedAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"nullable": true,
|
|
"description": "When the paused execution record was last updated."
|
|
},
|
|
"expiresAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"nullable": true,
|
|
"description": "When the paused execution will expire and be cleaned up."
|
|
},
|
|
"metadata": {
|
|
"type": "object",
|
|
"nullable": true,
|
|
"description": "Additional metadata associated with the paused execution.",
|
|
"additionalProperties": true
|
|
},
|
|
"triggerIds": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "IDs of triggers that initiated the original execution."
|
|
},
|
|
"pausePoints": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/PausePoint"
|
|
},
|
|
"description": "List of pause points in the execution."
|
|
}
|
|
}
|
|
},
|
|
"PausePoint": {
|
|
"type": "object",
|
|
"description": "A point in the workflow where execution has been paused awaiting human input.",
|
|
"properties": {
|
|
"contextId": {
|
|
"type": "string",
|
|
"description": "Unique identifier for this pause context. Used when resuming execution."
|
|
},
|
|
"blockId": {
|
|
"type": "string",
|
|
"description": "The block ID where execution paused."
|
|
},
|
|
"response": {
|
|
"description": "Data returned by the block before pausing, including display data and form fields."
|
|
},
|
|
"registeredAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "When this pause point was registered."
|
|
},
|
|
"resumeStatus": {
|
|
"type": "string",
|
|
"enum": ["paused", "resumed", "failed", "queued", "resuming"],
|
|
"description": "Current status of this pause point."
|
|
},
|
|
"snapshotReady": {
|
|
"type": "boolean",
|
|
"description": "Whether the execution snapshot is ready for resumption."
|
|
},
|
|
"resumeLinks": {
|
|
"type": "object",
|
|
"description": "Links for resuming this pause point.",
|
|
"properties": {
|
|
"apiUrl": {
|
|
"type": "string",
|
|
"format": "uri",
|
|
"description": "API endpoint URL to POST resume input to."
|
|
},
|
|
"uiUrl": {
|
|
"type": "string",
|
|
"format": "uri",
|
|
"description": "UI URL for a human to review and approve."
|
|
},
|
|
"contextId": {
|
|
"type": "string",
|
|
"description": "The context ID for this pause point."
|
|
},
|
|
"executionId": {
|
|
"type": "string",
|
|
"description": "The execution ID."
|
|
},
|
|
"workflowId": {
|
|
"type": "string",
|
|
"description": "The workflow ID."
|
|
}
|
|
}
|
|
},
|
|
"queuePosition": {
|
|
"type": "integer",
|
|
"nullable": true,
|
|
"description": "Position in the resume queue, if queued."
|
|
},
|
|
"latestResumeEntry": {
|
|
"$ref": "#/components/schemas/ResumeQueueEntry",
|
|
"nullable": true,
|
|
"description": "The most recent resume queue entry for this pause point."
|
|
},
|
|
"parallelScope": {
|
|
"type": "object",
|
|
"description": "Scope information when the pause occurs inside a parallel branch.",
|
|
"properties": {
|
|
"parallelId": {
|
|
"type": "string",
|
|
"description": "Identifier of the parallel execution group."
|
|
},
|
|
"branchIndex": {
|
|
"type": "integer",
|
|
"description": "Index of the branch within the parallel group."
|
|
},
|
|
"branchTotal": {
|
|
"type": "integer",
|
|
"description": "Total number of branches in the parallel group."
|
|
}
|
|
}
|
|
},
|
|
"loopScope": {
|
|
"type": "object",
|
|
"description": "Scope information when the pause occurs inside a loop.",
|
|
"properties": {
|
|
"loopId": {
|
|
"type": "string",
|
|
"description": "Identifier of the loop."
|
|
},
|
|
"iteration": {
|
|
"type": "integer",
|
|
"description": "Current loop iteration number."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"ResumeQueueEntry": {
|
|
"type": "object",
|
|
"description": "An entry in the resume execution queue.",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Unique identifier for this queue entry."
|
|
},
|
|
"pausedExecutionId": {
|
|
"type": "string",
|
|
"description": "The paused execution this entry belongs to."
|
|
},
|
|
"parentExecutionId": {
|
|
"type": "string",
|
|
"description": "The original execution that was paused."
|
|
},
|
|
"newExecutionId": {
|
|
"type": "string",
|
|
"description": "The new execution ID created for the resume."
|
|
},
|
|
"contextId": {
|
|
"type": "string",
|
|
"description": "The pause context ID being resumed."
|
|
},
|
|
"resumeInput": {
|
|
"description": "The input provided when resuming."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"description": "Status of this queue entry (e.g., pending, claimed, completed, failed)."
|
|
},
|
|
"queuedAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"nullable": true,
|
|
"description": "When the entry was added to the queue."
|
|
},
|
|
"claimedAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"nullable": true,
|
|
"description": "When execution started processing this entry."
|
|
},
|
|
"completedAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"nullable": true,
|
|
"description": "When execution completed."
|
|
},
|
|
"failureReason": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Reason for failure, if the resume failed."
|
|
}
|
|
}
|
|
},
|
|
"PausedExecutionDetail": {
|
|
"type": "object",
|
|
"description": "Detailed information about a paused execution, including the execution snapshot and resume queue.",
|
|
"allOf": [
|
|
{
|
|
"$ref": "#/components/schemas/PausedExecutionSummary"
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"executionSnapshot": {
|
|
"type": "object",
|
|
"description": "Serialized execution state for resumption.",
|
|
"properties": {
|
|
"snapshot": {
|
|
"type": "string",
|
|
"description": "Serialized execution snapshot data."
|
|
},
|
|
"triggerIds": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "Trigger IDs from the snapshot."
|
|
}
|
|
}
|
|
},
|
|
"queue": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/ResumeQueueEntry"
|
|
},
|
|
"description": "Resume queue entries for this execution."
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"PauseContextDetail": {
|
|
"type": "object",
|
|
"description": "Detailed information about a specific pause context within a paused execution.",
|
|
"properties": {
|
|
"execution": {
|
|
"$ref": "#/components/schemas/PausedExecutionSummary",
|
|
"description": "Summary of the parent paused execution."
|
|
},
|
|
"pausePoint": {
|
|
"$ref": "#/components/schemas/PausePoint",
|
|
"description": "The specific pause point for this context."
|
|
},
|
|
"queue": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/ResumeQueueEntry"
|
|
},
|
|
"description": "Resume queue entries for this context."
|
|
},
|
|
"activeResumeEntry": {
|
|
"$ref": "#/components/schemas/ResumeQueueEntry",
|
|
"nullable": true,
|
|
"description": "The currently active resume entry, if any."
|
|
}
|
|
}
|
|
},
|
|
"ResumeResult": {
|
|
"type": "object",
|
|
"description": "Result of a synchronous resume execution.",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"description": "Whether the resume execution completed successfully."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"description": "Execution status.",
|
|
"enum": ["completed", "failed", "paused", "cancelled"],
|
|
"example": "completed"
|
|
},
|
|
"executionId": {
|
|
"type": "string",
|
|
"description": "The new execution ID for the resumed workflow."
|
|
},
|
|
"output": {
|
|
"type": "object",
|
|
"description": "Workflow output from the resumed execution.",
|
|
"additionalProperties": true
|
|
},
|
|
"error": {
|
|
"type": "string",
|
|
"nullable": true,
|
|
"description": "Error message if the execution failed."
|
|
},
|
|
"metadata": {
|
|
"type": "object",
|
|
"description": "Execution timing metadata.",
|
|
"properties": {
|
|
"duration": {
|
|
"type": "integer",
|
|
"description": "Total execution duration in milliseconds."
|
|
},
|
|
"startTime": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "When the resume execution started."
|
|
},
|
|
"endTime": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "When the resume execution completed."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"BadRequest": {
|
|
"description": "Invalid request parameters. Check the details array for specific validation errors.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"error": {
|
|
"type": "string",
|
|
"description": "Human-readable error message describing the validation failure."
|
|
},
|
|
"details": {
|
|
"type": "array",
|
|
"description": "List of specific validation errors with field-level details.",
|
|
"items": {
|
|
"type": "object"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"Unauthorized": {
|
|
"description": "Invalid or missing API key. Ensure the X-API-Key header is set with a valid key.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"error": {
|
|
"type": "string",
|
|
"description": "Human-readable error message."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"Forbidden": {
|
|
"description": "Access denied. You do not have permission to access this resource. For audit log endpoints, this requires an Enterprise subscription and organization admin/owner role.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"error": {
|
|
"type": "string",
|
|
"description": "Human-readable error message."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"NotFound": {
|
|
"description": "The requested resource was not found. Verify the ID is correct and belongs to your workspace.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"error": {
|
|
"type": "string",
|
|
"description": "Human-readable error message."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"RateLimited": {
|
|
"description": "Rate limit exceeded. Wait for the duration specified in the Retry-After header before retrying.",
|
|
"headers": {
|
|
"Retry-After": {
|
|
"description": "Number of seconds to wait before retrying the request.",
|
|
"schema": {
|
|
"type": "integer"
|
|
}
|
|
}
|
|
},
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"error": {
|
|
"type": "string",
|
|
"description": "Human-readable error message with rate limit details."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"RowsUpdated": {
|
|
"description": "Rows updated.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"description": "Indicates whether the request was successful."
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"message": {
|
|
"type": "string",
|
|
"description": "Confirmation message describing how many rows were updated."
|
|
},
|
|
"updatedCount": {
|
|
"type": "integer",
|
|
"description": "Number of rows that were updated."
|
|
},
|
|
"updatedRowIds": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"description": "Array of IDs for each row that was updated."
|
|
}
|
|
},
|
|
"description": "Response payload."
|
|
}
|
|
}
|
|
},
|
|
"example": {
|
|
"success": true,
|
|
"data": {
|
|
"message": "Rows updated successfully",
|
|
"updatedCount": 2,
|
|
"updatedRowIds": ["row_abc123", "row_def456"]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|