sim/apps/docs/openapi.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": "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/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."
          }
        }
      }
    },
    "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"]
              }
            }
          }
        }
      }
    }
  }
}