mirror of
https://github.com/simstudioai/sim.git
synced 2026-04-06 03:00:16 -04:00
4c562c8e04
* feat(tables): add column operations, row ordering, V1 columns API, and OpenAPI spec
Adds column rename/delete/type change/constraint updates to the tables module,
row ordering via position column, UI metadata schema, V1 public API for column
operations with rate limiting and audit logging, and OpenAPI documentation.
Key changes:
- Service-layer column operations with validation (name pattern, type compatibility, unique/required constraints)
- Position column on user_table_rows with composite index for efficient ordering
- V1 /api/v1/tables/{tableId}/columns endpoint (POST/PATCH/DELETE) with rate limiting and audit
- Shared Zod schemas extracted to table/utils.ts using COLUMN_TYPES constant
- Targeted React Query invalidation (row vs schema mutations) with consistent onSettled usage
- OpenAPI 3.1.0 spec for columns endpoint with code samples
- Position field added to all row response mappings for consistency
- Sort fallback to position ordering when buildSortClause returns null
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(tables): use specific error prefixes instead of broad "Cannot" match
Prevents internal TypeErrors (e.g. "Cannot read properties of undefined")
from leaking as 400 responses. Now matches only domain-specific errors:
"Cannot delete the last column" and "Cannot set column".
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(tables): reject Infinity and NaN in number type compatibility check
Number.isFinite rejects Infinity, -Infinity, and NaN, preventing
non-finite values from passing column type validation.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(tables): invalidate table list on row create/delete for stale rowCount
Row create and delete mutations now invalidate the table list cache since
it includes a computed rowCount. Row updates (which don't change count)
continue to only invalidate row queries.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(tables): add column name length check, deduplicate name gen, reset pagination on clear
- Add MAX_COLUMN_NAME_LENGTH validation to addTableColumn (was missing,
renameColumn already had it)
- Extract generateColumnName helper to eliminate triplicated logic across
handleAddColumn, handleInsertColumnLeft, handleInsertColumnRight
- Reset pagination to page 0 when clearing sort/filter to prevent showing
empty pages after narrowing filters are removed
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: hoist tableId above try block in V1 columns route, add detail invalidation to invalidateRowCount
- V1 columns route: `tableId` was declared inside `try` but referenced in
`catch` logger.error, causing undefined in error logs. Hoisted `await params`
above try in all three handlers (POST, PATCH, DELETE).
- invalidateRowCount: added `tableKeys.detail(tableId)` invalidation since the
single-table GET response includes `rowCount`, which becomes stale after
row create/delete without this.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: add position to all row mutation responses, remove dead filter code
- Add `position` field to POST (single + batch) and PATCH row responses
across both internal and V1 routes, matching GET responses and OpenAPI spec.
- Remove unused `filterConfig`, `handleFilterToggle`, `handleFilterClear`,
and `activeFilters` — dead code left over from merge conflict resolution.
`handleFilterApply` (the one actually wired to JSX) is preserved.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: invalidateTableSchema now also invalidates table list cache
Column add/rename/delete/update mutations now invalidate tableKeys.list()
since the list endpoint returns schema.columns for each table. Without this,
the sidebar table list would show stale column schemas until staleTime expires.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: replace window.prompt/confirm with emcn Modal dialogs
Replace non-standard browser dialogs with proper emcn Modal components
to match the existing codebase pattern (e.g. delete table confirmation).
- Column rename: Modal with Input field + Enter key support
- Column delete: Modal with destructive confirmation
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
5290 lines
179 KiB
JSON
5290 lines
179 KiB
JSON
{
|
|
"openapi": "3.1.0",
|
|
"info": {
|
|
"title": "Sim API",
|
|
"description": "API for executing workflows, querying logs, and managing resources in Sim.",
|
|
"version": "1.0.0"
|
|
},
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Synchronous execution completed successfully.",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ExecutionResult"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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": [
|
|
{
|
|
"name": "workspaceId",
|
|
"in": "query",
|
|
"required": true,
|
|
"description": "The unique identifier for your workspace. Found in the Sim dashboard URL or workspace settings.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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": [
|
|
{
|
|
"name": "workspaceId",
|
|
"in": "query",
|
|
"required": true,
|
|
"description": "The unique identifier for your workspace.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"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"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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"
|
|
}
|
|
},
|
|
{
|
|
"name": "workspaceId",
|
|
"in": "query",
|
|
"description": "Filter to audit logs from a specific workspace.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"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"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/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": [
|
|
{
|
|
"name": "workspaceId",
|
|
"in": "query",
|
|
"required": true,
|
|
"description": "The workspace to list tables from.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/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": [
|
|
{
|
|
"name": "tableId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The table ID.",
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "tbl_abc123"
|
|
}
|
|
},
|
|
{
|
|
"name": "workspaceId",
|
|
"in": "query",
|
|
"required": true,
|
|
"description": "The workspace the table belongs to.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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": [
|
|
{
|
|
"name": "tableId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The table ID to delete.",
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "tbl_abc123"
|
|
}
|
|
},
|
|
{
|
|
"name": "workspaceId",
|
|
"in": "query",
|
|
"required": true,
|
|
"description": "The workspace the table belongs to.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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": [
|
|
{
|
|
"name": "tableId",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": { "type": "string" },
|
|
"description": "The table ID"
|
|
}
|
|
],
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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" }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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": [
|
|
{
|
|
"name": "tableId",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": { "type": "string" },
|
|
"description": "The table ID"
|
|
}
|
|
],
|
|
"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"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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" }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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": [
|
|
{
|
|
"name": "tableId",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": { "type": "string" },
|
|
"description": "The table ID"
|
|
}
|
|
],
|
|
"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"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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" }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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": [
|
|
{
|
|
"name": "tableId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The table to query rows from.",
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "tbl_abc123"
|
|
}
|
|
},
|
|
{
|
|
"name": "workspaceId",
|
|
"in": "query",
|
|
"required": true,
|
|
"description": "The workspace the table belongs to.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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": [
|
|
{
|
|
"name": "tableId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The table to insert rows into.",
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "tbl_abc123"
|
|
}
|
|
}
|
|
],
|
|
"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."
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"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
|
|
},
|
|
"maxItems": 1000,
|
|
"description": "Array of row objects to insert. Each object contains key-value pairs matching the table schema."
|
|
}
|
|
}
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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": [
|
|
{
|
|
"name": "tableId",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "tbl_abc123"
|
|
},
|
|
"description": "The table to update rows in."
|
|
}
|
|
],
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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": [
|
|
{
|
|
"name": "tableId",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "tbl_abc123"
|
|
},
|
|
"description": "The table to delete rows from."
|
|
}
|
|
],
|
|
"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)."
|
|
}
|
|
}
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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": [
|
|
{
|
|
"name": "tableId",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "tbl_abc123"
|
|
},
|
|
"description": "The table the row belongs to."
|
|
},
|
|
{
|
|
"name": "rowId",
|
|
"in": "path",
|
|
"required": true,
|
|
"description": "The row ID to retrieve.",
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "row_xyz789"
|
|
}
|
|
},
|
|
{
|
|
"name": "workspaceId",
|
|
"in": "query",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "The workspace that owns the table."
|
|
}
|
|
],
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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": [
|
|
{
|
|
"name": "tableId",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "tbl_abc123"
|
|
},
|
|
"description": "The table the row belongs to."
|
|
},
|
|
{
|
|
"name": "rowId",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "row_xyz789"
|
|
},
|
|
"description": "The unique identifier of the row."
|
|
}
|
|
],
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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}?workspaceId=YOUR_WORKSPACE_ID\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "tableId",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "tbl_abc123"
|
|
},
|
|
"description": "The table the row belongs to."
|
|
},
|
|
{
|
|
"name": "rowId",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "row_xyz789"
|
|
},
|
|
"description": "The unique identifier of the row."
|
|
},
|
|
{
|
|
"name": "workspaceId",
|
|
"in": "query",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "The workspace that owns the table."
|
|
}
|
|
],
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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/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": [
|
|
{
|
|
"name": "tableId",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"example": "tbl_abc123"
|
|
},
|
|
"description": "The table to upsert the row into."
|
|
}
|
|
],
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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": [
|
|
{
|
|
"name": "workspaceId",
|
|
"in": "query",
|
|
"required": true,
|
|
"description": "The workspace to list files from.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/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"
|
|
}
|
|
},
|
|
{
|
|
"name": "workspaceId",
|
|
"in": "query",
|
|
"required": true,
|
|
"description": "The workspace the file belongs to.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"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"
|
|
}
|
|
},
|
|
{
|
|
"name": "workspaceId",
|
|
"in": "query",
|
|
"required": true,
|
|
"description": "The workspace the file belongs to.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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": [
|
|
{
|
|
"name": "workspaceId",
|
|
"in": "query",
|
|
"required": true,
|
|
"description": "The workspace to list knowledge bases from.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"$ref": "#/components/responses/BadRequest"
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
},
|
|
"429": {
|
|
"$ref": "#/components/responses/RateLimited"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/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"
|
|
}
|
|
},
|
|
{
|
|
"name": "workspaceId",
|
|
"in": "query",
|
|
"required": true,
|
|
"description": "The workspace the knowledge base belongs to.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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"
|
|
}
|
|
},
|
|
{
|
|
"name": "workspaceId",
|
|
"in": "query",
|
|
"required": true,
|
|
"description": "The workspace the knowledge base belongs to.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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"
|
|
}
|
|
},
|
|
{
|
|
"name": "workspaceId",
|
|
"in": "query",
|
|
"required": true,
|
|
"description": "The workspace the knowledge base belongs to.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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"
|
|
}
|
|
},
|
|
{
|
|
"name": "workspaceId",
|
|
"in": "query",
|
|
"required": true,
|
|
"description": "The workspace the knowledge base belongs to.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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"
|
|
}
|
|
},
|
|
{
|
|
"name": "workspaceId",
|
|
"in": "query",
|
|
"required": true,
|
|
"description": "The workspace the knowledge base belongs to.",
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
],
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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."
|
|
}
|
|
},
|
|
"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."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|