github/sim
1
1
Fork 0
mirror of https://github.com/simstudioai/sim.git synced 2026-04-28 03:00:29 -04:00
Code Issues Packages Projects Releases Wiki Activity
Files
6e542ed8241a919b1e1ba09eaed970cd6489ffd5
sim/apps/docs/openapi.json
Waleed Latif 149ad9f36a lint
2026-04-09 13:54:40 -07:00

6819 lines
234 KiB
JSON
Raw Blame History

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