{ "openapi": "3.0.0", "paths": { "/connections": { "get": { "description": "Connections in the active organization. Credentials are never included: each row carries the stored config as ciphertext, plus `variant` for the multi-variant types. Requires `secrets:view`.", "operationId": "ConnectionController.list", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionListResponseDto" }, "example": { "total": 2, "data": [ { "id": "9c2f4d51-8b7a-4e0c-9d13-2a5f6b8c1e04", "suid": "q7m2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "billing-api", "type": "api-key", "config": "", "metadata": {}, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" }, { "id": "5b8e0a37-1c4d-4f92-8a06-7d3e9f1b2c58", "suid": "x3t8", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "customer_portal_login", "type": "form-auth", "config": "", "metadata": {}, "variant": "password", "createdAt": "2026-07-20T09:15:02.117Z", "updatedAt": "2026-07-24T11:41:37.903Z" } ] } } } } }, "summary": "List connections", "tags": [ "Connections" ] }, "post": { "description": "Validates `config` against the schema for `type`, then encrypts it before it is stored. The response echoes the connection with `config` still encrypted — a created credential is never played back in plaintext. `name` must be a valid identifier and unique within the organization. Requires `secrets:admin`.", "operationId": "ConnectionController.create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateConnectionDto" }, "examples": { "apiKey": { "summary": "API key", "value": { "name": "billing-api", "type": "api-key", "config": { "apiKey": "", "headerName": "Authorization", "prefix": "Bearer" } } }, "basicAuth": { "summary": "Username and password", "value": { "name": "partner_sftp_portal", "type": "basic-auth", "config": { "username": "svc-quickflo", "password": "" } } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionResponseDto" }, "example": { "id": "9c2f4d51-8b7a-4e0c-9d13-2a5f6b8c1e04", "suid": "q7m2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "billing-api", "type": "api-key", "config": "", "metadata": {}, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } } } }, "400": { "description": "Unknown connection type, a config that does not match that type’s schema, or a name already used in this organization." }, "403": { "description": "Caller lacks `secrets:admin`." } }, "summary": "Create a connection", "tags": [ "Connections" ] } }, "/connections/types/list": { "get": { "description": "Every value accepted for a connection’s `type`. Pair with `GET /connections/types/{type}/schema` to learn what config each one expects.", "operationId": "ConnectionController.getConnectionTypes", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionTypesResponseDto" }, "example": { "types": [ "five9", "basic-auth", "database", "api-key", "gcp-service-account", "aws-credentials", "sftp", "smtp", "twilio", "custom", "form-auth", "custom-oauth", "oauth-google", "oauth-microsoft", "oauth-salesforce", "oauth-github", "oauth-slack", "oauth-zoom", "oauth-webex" ] } } } } }, "summary": "List connection types", "tags": [ "Connections" ] } }, "/connections/types/{type}/schema": { "get": { "description": "JSON Schema for the `config` a given type expects, generated from the server-side definition — so it is always the same rules create and update validate against. Types whose config has several shapes (for example `form-auth`) publish as a union keyed on a discriminant field.", "operationId": "ConnectionController.getConnectionTypeSchema", "parameters": [ { "name": "type", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionTypeSchemaResponseDto" }, "example": { "type": "api-key", "schema": { "type": "object", "properties": { "apiKey": { "type": "string", "minLength": 1, "description": "API key value", "format": "password", "writeOnly": true }, "headerName": { "type": "string", "default": "Authorization", "description": "HTTP header name for the API key" }, "prefix": { "type": "string", "default": "Bearer", "description": "Optional prefix for the API key", "x-hint": "e.g., \"Bearer\" or \"Token\"" } }, "required": [ "apiKey" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } } }, "404": { "description": "Unknown connection type." } }, "summary": "Get the config schema for a connection type", "tags": [ "Connections" ] } }, "/connections/{id}": { "delete": { "description": "Returns the deleted connection as it last stood. Workflow steps still referencing it by name will fail at run time. Requires `secrets:admin`.", "operationId": "ConnectionController.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionResponseDto" }, "example": { "id": "9c2f4d51-8b7a-4e0c-9d13-2a5f6b8c1e04", "suid": "q7m2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "billing-api", "type": "api-key", "config": "", "metadata": {}, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } } } }, "403": { "description": "Caller lacks `secrets:admin`." }, "404": { "description": "No such connection in an organization the caller can read." } }, "summary": "Delete a connection", "tags": [ "Connections" ] }, "get": { "description": "The connection without its credentials: `config` is the encrypted envelope. Requires `secrets:view`.", "operationId": "ConnectionController.get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionResponseDto" }, "example": { "id": "9c2f4d51-8b7a-4e0c-9d13-2a5f6b8c1e04", "suid": "q7m2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "billing-api", "type": "api-key", "config": "", "metadata": {}, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } } } }, "404": { "description": "No such connection in an organization the caller can read." } }, "summary": "Get a connection", "tags": [ "Connections" ] }, "patch": { "description": "Every field is optional. `config` has no merge semantics here: supply it and the whole config is replaced, so a partial config drops the fields it omits. Omit `config` entirely to change only `name`, `settings` or `metadata`. Requires `secrets:admin`.", "operationId": "ConnectionController.update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateConnectionDto" }, "examples": { "rename": { "summary": "Rename", "value": { "name": "billing_api_v2" } }, "rotate": { "summary": "Replace the credentials", "value": { "config": { "apiKey": "", "headerName": "Authorization", "prefix": "Bearer" } } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionResponseDto" }, "example": { "id": "9c2f4d51-8b7a-4e0c-9d13-2a5f6b8c1e04", "suid": "q7m2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "billing-api", "type": "api-key", "config": "", "metadata": {}, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } } } }, "400": { "description": "The supplied config does not match the schema for the connection’s type." }, "403": { "description": "Caller lacks `secrets:admin`." }, "404": { "description": "No such connection in an organization the caller can read." } }, "summary": "Update a connection", "tags": [ "Connections" ] } }, "/connections/{id}/config": { "get": { "description": "Returns the connection’s credentials in PLAINTEXT — passwords, API keys, OAuth tokens, whatever the type stores. It exists so the credential editor can pre-fill a form. Gated on `secrets:view`, the same permission as reading the connection itself: within an organization, being able to see a connection is being able to read its secrets, and no separate permission narrows that. Treat the response as a secret — do not log it or persist it.", "operationId": "ConnectionController.getDecryptedConfig", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The decrypted config, keyed exactly as the connection type declares. Fetch `GET /connections/types/{type}/schema` for the field list of a given type.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "apiKey": "", "headerName": "Authorization", "prefix": "Bearer" } } } }, "404": { "description": "No such connection in an organization the caller can read." } }, "summary": "Get a connection’s decrypted config", "tags": [ "Connections" ] } }, "/dashboards": { "get": { "description": "Dashboards in the active organization, newest first. Widgets are not included: fetch a single dashboard to get them. Dashboards belonging to a package installed as a dependency of another package are hidden — they are reachable through their parent package instead.", "operationId": "DashboardController.listDashboards", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardListResponseDto" }, "example": [ { "id": "d41c8f6a-2b7e-4c19-83af-5e2d6b90c714", "suid": "dsh7q2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Contact Center Overview", "description": "Daily call volume and handle time.", "isDefault": true, "layout": [ { "widgetId": "b8e51d34-79c2-4f61-9a08-2d47c6e13f85", "x": 0, "y": 0, "w": 6, "h": 4 } ], "filterConfig": [ { "id": "1f0b7d55-8c31-42a6-9e74-6b0d2f83a915", "dataSourceId": "9a2f47c1-6e83-4b52-a0d7-3c5148ef9b26", "dimension": "direction", "label": "Direction" } ], "filterDefaults": { "1f0b7d55-8c31-42a6-9e74-6b0d2f83a915": [ "inbound" ] }, "timezone": "America/Los_Angeles", "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } ] } } } }, "summary": "List dashboards", "tags": [ "Dashboards" ] }, "post": { "description": "Creates an empty dashboard. Add widgets with `POST /dashboards/{dashboardId}/widgets`.", "operationId": "DashboardController.createDashboard", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDashboardDto" }, "examples": { "minimal": { "summary": "Name only", "value": { "name": "Contact Center Overview" } }, "pinned": { "summary": "Default dashboard in a fixed timezone", "value": { "name": "Contact Center Overview", "description": "Daily call volume and handle time.", "isDefault": true, "timezone": "America/Los_Angeles" } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardResponseDto" }, "example": { "id": "d41c8f6a-2b7e-4c19-83af-5e2d6b90c714", "suid": "dsh7q2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Contact Center Overview", "description": "Daily call volume and handle time.", "isDefault": true, "layout": [], "timezone": "America/Los_Angeles", "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } } } } }, "summary": "Create a dashboard", "tags": [ "Dashboards" ] } }, "/dashboards/analytics/distinct-values": { "post": { "description": "The values behind a filter control. An unknown or disabled data source answers with an empty list rather than an error.", "operationId": "DashboardController.distinctValues", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DistinctValuesRequestDto" }, "examples": { "all": { "summary": "All values", "value": { "dataSourceId": "9a2f47c1-6e83-4b52-a0d7-3c5148ef9b26", "dimension": "direction" } }, "typeahead": { "summary": "Narrow by substring for a typeahead", "value": { "dataSourceId": "9a2f47c1-6e83-4b52-a0d7-3c5148ef9b26", "dimension": "direction", "search": "in", "limit": 20, "dateRange": "last 30 days" } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DistinctValuesResultResponseDto" }, "example": { "values": [ "inbound", "outbound" ] } } } } }, "summary": "List distinct values for a dimension", "tags": [ "Dashboards" ] } }, "/dashboards/analytics/export-csv": { "post": { "description": "Runs the same query as `POST /dashboards/analytics/query` and streams the rows as a CSV attachment rather than JSON, so it is not bounded by a response body you have to hold in memory. `title` only names the downloaded file.", "operationId": "DashboardController.exportCsv", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportCsvDto" }, "examples": { "dailyCounts": { "summary": "Export a daily breakdown", "value": { "query": { "measures": [ "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.count" ], "dimensions": [ "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.direction" ], "timeDimensions": [ { "dimension": "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.startTime", "granularity": "day", "dateRange": "last 7 days" } ], "timezone": "America/Los_Angeles", "limit": 500 }, "title": "Calls by day" } } } } } }, "responses": { "200": { "description": "CSV attachment, streamed. The filename is your `title` plus today’s date.", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } } }, "summary": "Export query results as CSV", "tags": [ "Dashboards" ] } }, "/dashboards/analytics/meta": { "get": { "description": "One entry per data source, listing the measures and dimensions a query may reference by their fully qualified names. Start here when building a query by hand.", "operationId": "DashboardController.analyticsMeta", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsMetaListResponseDto" }, "example": [ { "name": "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26", "title": "Call Logs - Production", "measures": [ { "name": "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.count", "title": "Count", "type": "number" }, { "name": "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.duration", "title": "Duration (s)", "type": "number" }, { "name": "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.talkMinutes", "title": "Talk minutes", "type": "number", "calculated": true } ], "dimensions": [ { "name": "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.startTime", "title": "Start time", "type": "time" }, { "name": "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.direction", "title": "Direction", "type": "string" } ] } ] } } } }, "summary": "List queryable fields", "tags": [ "Dashboards" ] } }, "/dashboards/analytics/query": { "post": { "description": "The query surface every widget renders through. Fields are addressed as `.`; list what is available with `GET /dashboards/analytics/meta`. Returns rows shaped by the measures and dimensions you asked for, so the column set is yours, not fixed.", "operationId": "DashboardController.analyticsQuery", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsQueryRequestDto" }, "examples": { "dailyCounts": { "summary": "Daily counts split by a dimension", "value": { "query": { "measures": [ "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.count" ], "dimensions": [ "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.direction" ], "timeDimensions": [ { "dimension": "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.startTime", "granularity": "day", "dateRange": "last 7 days" } ], "timezone": "America/Los_Angeles", "limit": 500 } } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsQueryResultResponseDto" }, "example": { "data": [ { "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.startTime": "2026-07-26T00:00:00.000Z", "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.direction": "inbound", "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.count": 1842 }, { "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.startTime": "2026-07-26T00:00:00.000Z", "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.direction": "outbound", "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.count": 967 } ], "annotation": {}, "query": { "measures": [ "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.count" ], "dimensions": [ "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.direction" ], "timeDimensions": [ { "dimension": "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.startTime", "granularity": "day", "dateRange": "last 7 days" } ], "timezone": "America/Los_Angeles", "limit": 500 } } } } }, "400": { "description": "The query names no data source, or references a shared source whose share is no longer active." } }, "summary": "Run an analytics query", "tags": [ "Dashboards" ] } }, "/dashboards/data-feeds/toggle": { "post": { "description": "Turns a built-in feed on or off for one connection. Enabling creates (or re-enables) the data source and its recurring sync; disabling stops the sync and leaves the records in place.", "operationId": "DashboardController.toggleDataFeed", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToggleDataFeedDto" }, "examples": { "enable": { "summary": "Enable", "value": { "feedKey": "twilio:calls", "connectionId": "6d18b4e0-9f27-4c53-a81b-2e5074c3a9d6", "connectionName": "Production Voice", "enabled": true, "syncIntervalMinutes": 60 } }, "disable": { "summary": "Disable", "value": { "feedKey": "twilio:calls", "connectionId": "6d18b4e0-9f27-4c53-a81b-2e5074c3a9d6", "connectionName": "Production Voice", "enabled": false } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToggleDataFeedResultResponseDto" }, "example": { "enabled": true, "dataSourceId": "9a2f47c1-6e83-4b52-a0d7-3c5148ef9b26" } } } } }, "summary": "Toggle a data feed", "tags": [ "Dashboards" ] } }, "/dashboards/data-sources": { "get": { "description": "Every data source in the organization, newest first, each with the hot-copy placement actually in force for its table.", "operationId": "DashboardController.listDataSources", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardDataSourceListResponseDto" }, "example": [ { "id": "9a2f47c1-6e83-4b52-a0d7-3c5148ef9b26", "suid": "dsc9pv", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Call Logs - Production", "type": "twilio:calls", "connectionId": "6d18b4e0-9f27-4c53-a81b-2e5074c3a9d6", "connectionName": "Production Voice", "dataStoreTableName": "call_logs", "recordSchema": { "name": "Call", "fields": { "startTime": { "type": "date", "label": "Start time", "timeDimension": true }, "direction": { "type": "string", "label": "Direction" }, "duration": { "type": "number", "label": "Duration (s)", "measure": true } }, "calculatedFields": [ { "id": "c5a0e7f2-3d41-4b96-8e02-7f14b3d95c68", "name": "talkMinutes", "label": "Talk minutes", "type": "number", "expression": { "type": "BinaryExpression", "operator": "/", "left": { "type": "Identifier", "name": "duration" }, "right": { "type": "Literal", "value": 60, "raw": "60" } }, "formula": "duration / 60", "measure": true } ] }, "syncConfig": { "syncIntervalMinutes": 60, "lastSyncAt": "2026-07-27T16:04:11.482Z", "lastSyncStatus": "success" }, "enabled": true, "servingEngine": "clickhouse", "servingRelation": "ds_call_logs_3f7c1a92", "hotPathMode": "retain", "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z", "effectiveHotPathMode": "retain" } ] } } } }, "summary": "List data sources", "tags": [ "Dashboards" ] }, "post": { "description": "Points analytics at a data store table. `recordSchema` describes the fields: mark the numeric ones `measure` and the one date field that ranges filter on `timeDimension`.", "operationId": "DashboardController.createDataSource", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDataSourceDto" }, "examples": { "ownTable": { "summary": "Read a table in this organization", "value": { "name": "Call Logs - Production", "type": "custom", "dataStoreTableName": "call_logs", "recordSchema": { "name": "Call", "fields": { "startTime": { "type": "date", "label": "Start time", "timeDimension": true }, "direction": { "type": "string", "label": "Direction" }, "duration": { "type": "number", "label": "Duration (s)", "measure": true } } } } }, "shared": { "summary": "Read a table another organization shared with you", "value": { "name": "Northwind Retail - Calls", "type": "custom", "dataStoreTableName": "call_logs", "sharedFromOrganizationId": "7c2e9d81-4b60-4a37-95f2-1e8a3c05d6b4", "recordSchema": { "name": "Call", "fields": { "startTime": { "type": "date", "label": "Start time", "timeDimension": true } } } } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardDataSourceResponseDto" }, "example": { "id": "9a2f47c1-6e83-4b52-a0d7-3c5148ef9b26", "suid": "dsc9pv", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Call Logs - Production", "type": "twilio:calls", "connectionId": "6d18b4e0-9f27-4c53-a81b-2e5074c3a9d6", "connectionName": "Production Voice", "dataStoreTableName": "call_logs", "recordSchema": { "name": "Call", "fields": { "startTime": { "type": "date", "label": "Start time", "timeDimension": true }, "direction": { "type": "string", "label": "Direction" }, "duration": { "type": "number", "label": "Duration (s)", "measure": true } }, "calculatedFields": [ { "id": "c5a0e7f2-3d41-4b96-8e02-7f14b3d95c68", "name": "talkMinutes", "label": "Talk minutes", "type": "number", "expression": { "type": "BinaryExpression", "operator": "/", "left": { "type": "Identifier", "name": "duration" }, "right": { "type": "Literal", "value": 60, "raw": "60" } }, "formula": "duration / 60", "measure": true } ] }, "syncConfig": { "syncIntervalMinutes": 60, "lastSyncAt": "2026-07-27T16:04:11.482Z", "lastSyncStatus": "success" }, "enabled": true, "servingEngine": "clickhouse", "servingRelation": "ds_call_logs_3f7c1a92", "hotPathMode": "retain", "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } } } }, "400": { "description": "The referenced share is not active, or the shared/aggregate options conflict." } }, "summary": "Create a data source", "tags": [ "Dashboards" ] } }, "/dashboards/data-sources/{dataSourceId}": { "delete": { "description": "Removes the source and its analytics serving table. Refused while another organization still reads the table through an active share.", "operationId": "DashboardController.deleteDataSource", "parameters": [ { "name": "dataSourceId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedAckResponseDto" }, "example": { "deleted": true } } } }, "400": { "description": "An active share still depends on this source." }, "404": { "description": "No such data source." } }, "summary": "Delete a data source", "tags": [ "Dashboards" ] }, "get": { "operationId": "DashboardController.getDataSource", "parameters": [ { "name": "dataSourceId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardDataSourceReadResponseDto" }, "example": { "id": "9a2f47c1-6e83-4b52-a0d7-3c5148ef9b26", "suid": "dsc9pv", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Call Logs - Production", "type": "twilio:calls", "connectionId": "6d18b4e0-9f27-4c53-a81b-2e5074c3a9d6", "connectionName": "Production Voice", "dataStoreTableName": "call_logs", "recordSchema": { "name": "Call", "fields": { "startTime": { "type": "date", "label": "Start time", "timeDimension": true }, "direction": { "type": "string", "label": "Direction" }, "duration": { "type": "number", "label": "Duration (s)", "measure": true } }, "calculatedFields": [ { "id": "c5a0e7f2-3d41-4b96-8e02-7f14b3d95c68", "name": "talkMinutes", "label": "Talk minutes", "type": "number", "expression": { "type": "BinaryExpression", "operator": "/", "left": { "type": "Identifier", "name": "duration" }, "right": { "type": "Literal", "value": 60, "raw": "60" } }, "formula": "duration / 60", "measure": true } ] }, "syncConfig": { "syncIntervalMinutes": 60, "lastSyncAt": "2026-07-27T16:04:11.482Z", "lastSyncStatus": "success" }, "enabled": true, "servingEngine": "clickhouse", "servingRelation": "ds_call_logs_3f7c1a92", "hotPathMode": "retain", "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z", "effectiveHotPathMode": "retain" } } } }, "404": { "description": "No such data source." } }, "summary": "Get a data source", "tags": [ "Dashboards" ] }, "patch": { "description": "Renaming, pausing sync and re-declaring the record schema. Changing which field is the time dimension can require rebuilding the underlying analytics table, which is why some edits are refused without `confirmTimeFieldRekey`.", "operationId": "DashboardController.updateDataSource", "parameters": [ { "name": "dataSourceId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDataSourceDto" }, "examples": { "rename": { "summary": "Rename", "value": { "name": "Call Logs - EU" } }, "pause": { "summary": "Pause syncing", "value": { "enabled": false } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardDataSourceResponseDto" }, "example": { "id": "9a2f47c1-6e83-4b52-a0d7-3c5148ef9b26", "suid": "dsc9pv", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Call Logs - Production", "type": "twilio:calls", "connectionId": "6d18b4e0-9f27-4c53-a81b-2e5074c3a9d6", "connectionName": "Production Voice", "dataStoreTableName": "call_logs", "recordSchema": { "name": "Call", "fields": { "startTime": { "type": "date", "label": "Start time", "timeDimension": true }, "direction": { "type": "string", "label": "Direction" }, "duration": { "type": "number", "label": "Duration (s)", "measure": true } }, "calculatedFields": [ { "id": "c5a0e7f2-3d41-4b96-8e02-7f14b3d95c68", "name": "talkMinutes", "label": "Talk minutes", "type": "number", "expression": { "type": "BinaryExpression", "operator": "/", "left": { "type": "Identifier", "name": "duration" }, "right": { "type": "Literal", "value": 60, "raw": "60" } }, "formula": "duration / 60", "measure": true } ] }, "syncConfig": { "syncIntervalMinutes": 60, "lastSyncAt": "2026-07-27T16:04:11.482Z", "lastSyncStatus": "success" }, "enabled": true, "servingEngine": "clickhouse", "servingRelation": "ds_call_logs_3f7c1a92", "hotPathMode": "retain", "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } } } }, "400": { "description": "The edit would re-key or destroy data that another organization is actively reading through a share, or needs explicit confirmation." }, "404": { "description": "No such data source." } }, "summary": "Update a data source", "tags": [ "Dashboards" ] } }, "/dashboards/data-sources/{dataSourceId}/calculated-fields": { "post": { "description": "A field derived from other fields at query time — no data is rewritten, and it becomes referenceable by name like any native field. Send the parsed `expression`; `formula` is the source text kept for the editor.", "operationId": "DashboardController.addCalculatedField", "parameters": [ { "name": "dataSourceId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCalculatedFieldDto" }, "examples": { "derivedMeasure": { "summary": "Seconds to minutes, usable as a measure", "value": { "name": "talkMinutes", "label": "Talk minutes", "type": "number", "expression": { "type": "BinaryExpression", "operator": "/", "left": { "type": "Identifier", "name": "duration" }, "right": { "type": "Literal", "value": 60, "raw": "60" } }, "formula": "duration / 60", "measure": true } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalculatedFieldResponseDto" }, "example": { "id": "c5a0e7f2-3d41-4b96-8e02-7f14b3d95c68", "name": "talkMinutes", "label": "Talk minutes", "type": "number", "expression": { "type": "BinaryExpression", "operator": "/", "left": { "type": "Identifier", "name": "duration" }, "right": { "type": "Literal", "value": 60, "raw": "60" } }, "formula": "duration / 60", "measure": true } } } }, "400": { "description": "The name collides with a native or existing field, or the expression references a field that does not exist." }, "404": { "description": "No such data source." } }, "summary": "Add a calculated field", "tags": [ "Dashboards" ] } }, "/dashboards/data-sources/{dataSourceId}/calculated-fields/preview": { "post": { "description": "Evaluates an expression over a sample of rows without saving it, so you can see what a formula actually produces before committing to it.", "operationId": "DashboardController.previewCalculatedField", "parameters": [ { "name": "dataSourceId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewCalculatedFieldDto" }, "examples": { "derived": { "summary": "Preview a derived number", "value": { "expression": { "type": "BinaryExpression", "operator": "/", "left": { "type": "Identifier", "name": "duration" }, "right": { "type": "Literal", "value": 60, "raw": "60" } }, "type": "number" } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalculatedFieldPreviewResponseDto" }, "example": { "values": [ 3.5, 12.25, 0.75, 8 ] } } } }, "400": { "description": "The expression references a field that does not exist." } }, "summary": "Preview a calculated field", "tags": [ "Dashboards" ] } }, "/dashboards/data-sources/{dataSourceId}/calculated-fields/{fieldId}": { "delete": { "description": "Widgets still referencing the field are not updated: they will match nothing until you edit them.", "operationId": "DashboardController.removeCalculatedField", "parameters": [ { "name": "dataSourceId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "fieldId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedAckResponseDto" }, "example": { "deleted": true } } } }, "404": { "description": "No such data source or calculated field." } }, "summary": "Delete a calculated field", "tags": [ "Dashboards" ] }, "patch": { "description": "Renaming a field does NOT rewrite widgets that reference it by the old name, so update those too.", "operationId": "DashboardController.updateCalculatedField", "parameters": [ { "name": "dataSourceId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "fieldId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCalculatedFieldDto" }, "examples": { "relabel": { "summary": "Change the display label", "value": { "label": "Talk time (min)" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalculatedFieldResponseDto" }, "example": { "id": "c5a0e7f2-3d41-4b96-8e02-7f14b3d95c68", "name": "talkMinutes", "label": "Talk minutes", "type": "number", "expression": { "type": "BinaryExpression", "operator": "/", "left": { "type": "Identifier", "name": "duration" }, "right": { "type": "Literal", "value": 60, "raw": "60" } }, "formula": "duration / 60", "measure": true } } } }, "404": { "description": "No such data source or calculated field." } }, "summary": "Update a calculated field", "tags": [ "Dashboards" ] } }, "/dashboards/data-sources/{dataSourceId}/refresh-schema": { "post": { "description": "Re-samples the stored records to pick up fields that appeared after the source was created. Your own customizations — measure and time dimension flags, calculated fields — are preserved. When there is nothing to sample the schema is left alone and the acknowledgement says so instead of returning a source.", "operationId": "DashboardController.refreshSchema", "parameters": [ { "name": "dataSourceId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshSchemaResultResponseDto" }, "example": { "id": "9a2f47c1-6e83-4b52-a0d7-3c5148ef9b26", "suid": "dsc9pv", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Call Logs - Production", "type": "twilio:calls", "connectionId": "6d18b4e0-9f27-4c53-a81b-2e5074c3a9d6", "connectionName": "Production Voice", "dataStoreTableName": "call_logs", "recordSchema": { "name": "Call", "fields": { "startTime": { "type": "date", "label": "Start time", "timeDimension": true }, "direction": { "type": "string", "label": "Direction" }, "duration": { "type": "number", "label": "Duration (s)", "measure": true } }, "calculatedFields": [ { "id": "c5a0e7f2-3d41-4b96-8e02-7f14b3d95c68", "name": "talkMinutes", "label": "Talk minutes", "type": "number", "expression": { "type": "BinaryExpression", "operator": "/", "left": { "type": "Identifier", "name": "duration" }, "right": { "type": "Literal", "value": 60, "raw": "60" } }, "formula": "duration / 60", "measure": true } ] }, "syncConfig": { "syncIntervalMinutes": 60, "lastSyncAt": "2026-07-27T16:04:11.482Z", "lastSyncStatus": "success" }, "enabled": true, "servingEngine": "clickhouse", "servingRelation": "ds_call_logs_3f7c1a92", "hotPathMode": "retain", "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } } } }, "404": { "description": "No such data source." } }, "summary": "Refresh a data source’s schema", "tags": [ "Dashboards" ] } }, "/dashboards/data-sources/{dataSourceId}/reindex": { "post": { "description": "Drops and recreates the analytics indexes. A maintenance operation for when queries have gone slow; it does not change any data.", "operationId": "DashboardController.reindexDataSource", "parameters": [ { "name": "dataSourceId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReindexedAckResponseDto" }, "example": { "reindexed": true } } } }, "404": { "description": "No such data source." } }, "summary": "Rebuild a data source’s indexes", "tags": [ "Dashboards" ] } }, "/dashboards/data-sources/{dataSourceId}/sync": { "post": { "description": "Queues the sync workflow and returns immediately: the records land asynchronously. Omit the dates to sync from the last successful sync up to now.", "operationId": "DashboardController.triggerSync", "parameters": [ { "name": "dataSourceId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerSyncDto" }, "examples": { "incremental": { "summary": "Since the last sync", "value": {} }, "backfill": { "summary": "Backfill an explicit window", "value": { "startDate": "2026-07-01T00:00:00.000Z", "endDate": "2026-07-27T00:00:00.000Z" } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerSyncResultResponseDto" }, "example": { "message": "Sync triggered" } } } }, "500": { "description": "The source is disabled, has no connection, or has no sync workflow for its feed type." } }, "summary": "Trigger a data source sync", "tags": [ "Dashboards" ] } }, "/dashboards/data-sources/{dataSourceId}/window-dimensions": { "post": { "description": "A rank-within-group field: number each row inside a group, ordered by a field — \"which attempt was this call for this number?\". Filtering to rank 1 then gives you the first (or, with `direction: desc`, the latest) row per group. Only available on ClickHouse-served, non-aggregate sources.", "operationId": "DashboardController.addWindowDimension", "parameters": [ { "name": "dataSourceId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWindowDimensionDto" }, "examples": { "attemptNumber": { "summary": "Rank attempts per dialed number", "value": { "name": "attemptNumber", "label": "Attempt number", "function": "row_number", "partitionBy": [ "dialedNumber" ], "orderBy": "startTime", "direction": "asc", "semantic": "lifetime" } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WindowDimensionResponseDto" }, "example": { "id": "4e93a1c7-0b58-4d26-9f31-8a705c2e6b49", "name": "attemptNumber", "label": "Attempt number", "function": "row_number", "partitionBy": [ "dialedNumber" ], "orderBy": "startTime", "direction": "asc", "semantic": "lifetime" } } } }, "400": { "description": "The source cannot serve window dimensions, the name is taken, or a referenced field does not exist." }, "404": { "description": "No such data source." } }, "summary": "Add a window dimension", "tags": [ "Dashboards" ] } }, "/dashboards/data-sources/{dataSourceId}/window-dimensions/{fieldId}": { "delete": { "operationId": "DashboardController.removeWindowDimension", "parameters": [ { "name": "dataSourceId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "fieldId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedAckResponseDto" }, "example": { "deleted": true } } } }, "404": { "description": "No such data source or window dimension." } }, "summary": "Delete a window dimension", "tags": [ "Dashboards" ] }, "patch": { "operationId": "DashboardController.updateWindowDimension", "parameters": [ { "name": "dataSourceId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "fieldId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWindowDimensionDto" }, "examples": { "latestPerGroup": { "summary": "Rank from the newest row instead of the oldest", "value": { "direction": "desc" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WindowDimensionResponseDto" }, "example": { "id": "4e93a1c7-0b58-4d26-9f31-8a705c2e6b49", "name": "attemptNumber", "label": "Attempt number", "function": "row_number", "partitionBy": [ "dialedNumber" ], "orderBy": "startTime", "direction": "desc", "semantic": "lifetime" } } } }, "404": { "description": "No such data source or window dimension." } }, "summary": "Update a window dimension", "tags": [ "Dashboards" ] } }, "/dashboards/import": { "post": { "description": "Recreates a dashboard from an export payload. The export references its data sources by portable `exportId`; `dataSourceMappings` says which source in THIS organization each one becomes, and every field ref in the widgets is rewritten to match.", "operationId": "DashboardController.importDashboard", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportDashboardDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardWithWidgetsResponseDto" }, "example": { "id": "d41c8f6a-2b7e-4c19-83af-5e2d6b90c714", "suid": "dsh7q2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Contact Center Overview", "description": "Daily call volume and handle time.", "isDefault": true, "layout": [ { "widgetId": "b8e51d34-79c2-4f61-9a08-2d47c6e13f85", "x": 0, "y": 0, "w": 6, "h": 4 } ], "filterConfig": [ { "id": "1f0b7d55-8c31-42a6-9e74-6b0d2f83a915", "dataSourceId": "9a2f47c1-6e83-4b52-a0d7-3c5148ef9b26", "dimension": "direction", "label": "Direction" } ], "filterDefaults": { "1f0b7d55-8c31-42a6-9e74-6b0d2f83a915": [ "inbound" ] }, "timezone": "America/Los_Angeles", "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z", "widgets": [ { "id": "b8e51d34-79c2-4f61-9a08-2d47c6e13f85", "suid": "wgt4kx", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "dashboardId": "d41c8f6a-2b7e-4c19-83af-5e2d6b90c714", "title": "Calls by day", "chartType": "line", "dataSourceId": "9a2f47c1-6e83-4b52-a0d7-3c5148ef9b26", "queryConfig": { "measures": [ "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.count" ], "timeDimensions": [ { "dimension": "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.startTime", "granularity": "day", "dateRange": "last 30 days" } ], "filters": [ { "dimension": "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.direction", "operator": "equals", "values": [ "inbound" ] } ] }, "displayConfig": { "legend": { "show": false } }, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } ] } } } }, "400": { "description": "A mapped data source is missing, or a dashboard of that name already exists in this organization." } }, "summary": "Import a dashboard", "tags": [ "Dashboards" ] } }, "/dashboards/proxy": { "get": { "description": "Fetches a resource that lives behind a data source’s connection — a call recording, say — using credentials the caller never sees, and streams it back. The `url` is the `proxy+service:type://` reference that appears in the record; it is not a general-purpose URL fetcher.", "operationId": "DashboardController.proxy", "parameters": [ { "name": "url", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The upstream resource, streamed. Content type mirrors upstream, so this can be audio, an image, or anything else the provider returns.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Missing `url` query parameter." }, "404": { "description": "The upstream returned an error or an empty body." } }, "summary": "Proxy an external resource", "tags": [ "Dashboards" ] } }, "/dashboards/shares": { "post": { "description": "Grants another organization read access to one table, so they can build their own data source and dashboards on it. Identify the recipient by id or by the short id they can read off their own organization. Sharing requires a Growth plan or above.", "operationId": "DashboardController.createShare", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDataStoreShareDto" }, "examples": { "bySuid": { "summary": "Share with an organization by its short id", "value": { "tableName": "call_logs", "sharedToOrganizationSuid": "nw3x7p", "alias": "Northwind Retail - Calls" } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataStoreShareResponseDto" }, "example": { "id": "e07b3c94-1a55-4d82-b6f0-9c2e48d15a37", "suid": "shr2mz", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "ownerOrganizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "tableName": "call_logs", "sharedToOrganizationId": "7c2e9d81-4b60-4a37-95f2-1e8a3c05d6b4", "alias": "Northwind Retail - Calls", "readOnly": true, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } } } }, "400": { "description": "No recipient given, the recipient does not exist, it is your own organization, or the plan does not include data store sharing." } }, "summary": "Share a data store table", "tags": [ "Dashboards" ] } }, "/dashboards/shares/granted": { "get": { "description": "Active shares only: revoked ones are not returned.", "operationId": "DashboardController.listGrantedShares", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataStoreShareListResponseDto" }, "example": [ { "id": "e07b3c94-1a55-4d82-b6f0-9c2e48d15a37", "suid": "shr2mz", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "ownerOrganizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "tableName": "call_logs", "sharedToOrganizationId": "7c2e9d81-4b60-4a37-95f2-1e8a3c05d6b4", "alias": "Northwind Retail - Calls", "readOnly": true, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } ] } } } }, "summary": "List shares you granted", "tags": [ "Dashboards" ] } }, "/dashboards/shares/received": { "get": { "description": "Tables other organizations have shared with you, each tagged with the kind of records it holds so you know what you are pointing a data source at.", "operationId": "DashboardController.listReceivedShares", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivedDataStoreShareListResponseDto" }, "example": [ { "id": "e07b3c94-1a55-4d82-b6f0-9c2e48d15a37", "suid": "shr2mz", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "ownerOrganizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "tableName": "call_logs", "sharedToOrganizationId": "7c2e9d81-4b60-4a37-95f2-1e8a3c05d6b4", "alias": "Northwind Retail - Calls", "readOnly": true, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z", "analyticsTag": "twilio:calls" } ] } } }, "403": { "description": "Caller has no access to the active organization." } }, "summary": "List shares granted to you", "tags": [ "Dashboards" ] } }, "/dashboards/shares/{shareId}": { "delete": { "description": "The recipient loses access immediately, and any of their widgets reading the table start failing rather than quietly returning nothing.", "operationId": "DashboardController.revokeShare", "parameters": [ { "name": "shareId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokedAckResponseDto" }, "example": { "revoked": true } } } }, "404": { "description": "No such share." } }, "summary": "Revoke a share", "tags": [ "Dashboards" ] } }, "/dashboards/validate": { "post": { "description": "Checks widgets without saving them, and catches the mistakes that otherwise fail silently: a mistyped field ref matches zero rows and never raises, so a broken widget just looks empty. Always answers 200 — an invalid config is a successful check with `ok: false`, including when the payload itself is malformed.", "operationId": "DashboardController.validateDashboard", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateDashboardRequestDto" }, "examples": { "oneWidget": { "summary": "Check one widget before saving it", "value": { "widgets": [ { "title": "Calls by day", "dataSourceId": "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26", "queryConfig": { "measures": [ "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.count" ], "dimensions": [ "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.CAMPAIGN_TYPE" ] } } ] } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardValidationResultResponseDto" }, "example": { "ok": false, "errors": [ { "ruleId": "field-refs", "severity": "error", "widget": "Calls by day", "message": "dimension ref \"ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.CAMPAIGN_TYPE\" does not exist. Did you mean \"ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.campaignType\"?" } ], "warnings": [] } } } } }, "summary": "Validate widget configs", "tags": [ "Dashboards" ] } }, "/dashboards/widgets/{widgetId}": { "delete": { "description": "Also removes the widget from its dashboard’s grid layout.", "operationId": "DashboardController.removeWidget", "parameters": [ { "name": "widgetId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedAckResponseDto" }, "example": { "deleted": true } } } }, "404": { "description": "No such widget." } }, "summary": "Delete a widget", "tags": [ "Dashboards" ] }, "patch": { "description": "Every field is optional; only what you send changes. Sending `queryConfig` replaces it wholesale rather than merging.", "operationId": "DashboardController.updateWidget", "parameters": [ { "name": "widgetId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWidgetDto" }, "examples": { "retitle": { "summary": "Rename", "value": { "title": "Inbound calls by day" } }, "rechart": { "summary": "Change chart type", "value": { "chartType": "bar" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardWidgetResponseDto" }, "example": { "id": "b8e51d34-79c2-4f61-9a08-2d47c6e13f85", "suid": "wgt4kx", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "dashboardId": "d41c8f6a-2b7e-4c19-83af-5e2d6b90c714", "title": "Calls by day", "chartType": "line", "dataSourceId": "9a2f47c1-6e83-4b52-a0d7-3c5148ef9b26", "queryConfig": { "measures": [ "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.count" ], "timeDimensions": [ { "dimension": "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.startTime", "granularity": "day", "dateRange": "last 30 days" } ], "filters": [ { "dimension": "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.direction", "operator": "equals", "values": [ "inbound" ] } ] }, "displayConfig": { "legend": { "show": false } }, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } } } }, "400": { "description": "The new data source belongs to another organization." }, "404": { "description": "No such widget." } }, "summary": "Update a widget", "tags": [ "Dashboards" ] } }, "/dashboards/{dashboardId}/widgets": { "post": { "description": "Creates a widget and appends it to the bottom of the grid at a default size. Field refs in `queryConfig` are `.`; check them first with `POST /dashboards/validate`, because a bad ref saves cleanly and then renders empty.", "operationId": "DashboardController.addWidget", "parameters": [ { "name": "dashboardId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWidgetDto" }, "examples": { "timeSeries": { "summary": "Daily counts as a line chart", "value": { "title": "Calls by day", "chartType": "line", "dataSourceId": "9a2f47c1-6e83-4b52-a0d7-3c5148ef9b26", "queryConfig": { "measures": [ "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.count" ], "timeDimensions": [ { "dimension": "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.startTime", "granularity": "day", "dateRange": "last 30 days" } ], "filters": [ { "dimension": "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.direction", "operator": "equals", "values": [ "inbound" ] } ] } } }, "statCard": { "summary": "A single number", "value": { "title": "Total calls", "chartType": "stat-card", "dataSourceId": "9a2f47c1-6e83-4b52-a0d7-3c5148ef9b26", "queryConfig": { "measures": [ "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.count" ], "timeRange": { "type": "relative", "value": "7d" } } } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardWidgetResponseDto" }, "example": { "id": "b8e51d34-79c2-4f61-9a08-2d47c6e13f85", "suid": "wgt4kx", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "dashboardId": "d41c8f6a-2b7e-4c19-83af-5e2d6b90c714", "title": "Calls by day", "chartType": "line", "dataSourceId": "9a2f47c1-6e83-4b52-a0d7-3c5148ef9b26", "queryConfig": { "measures": [ "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.count" ], "timeDimensions": [ { "dimension": "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.startTime", "granularity": "day", "dateRange": "last 30 days" } ], "filters": [ { "dimension": "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.direction", "operator": "equals", "values": [ "inbound" ] } ] }, "displayConfig": { "legend": { "show": false } }, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } } } }, "400": { "description": "The data source belongs to another organization." }, "404": { "description": "No such dashboard." } }, "summary": "Add a widget", "tags": [ "Dashboards" ] } }, "/dashboards/{id}": { "delete": { "description": "Deletes its widgets too. The data sources they read are untouched.", "operationId": "DashboardController.deleteDashboard", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedAckResponseDto" }, "example": { "deleted": true } } } }, "404": { "description": "No such dashboard." } }, "summary": "Delete a dashboard", "tags": [ "Dashboards" ] }, "get": { "description": "The dashboard with its widgets inline, oldest first. `layout` places them on the grid by widget id.", "operationId": "DashboardController.getDashboard", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardWithWidgetsResponseDto" }, "example": { "id": "d41c8f6a-2b7e-4c19-83af-5e2d6b90c714", "suid": "dsh7q2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Contact Center Overview", "description": "Daily call volume and handle time.", "isDefault": true, "layout": [ { "widgetId": "b8e51d34-79c2-4f61-9a08-2d47c6e13f85", "x": 0, "y": 0, "w": 6, "h": 4 } ], "filterConfig": [ { "id": "1f0b7d55-8c31-42a6-9e74-6b0d2f83a915", "dataSourceId": "9a2f47c1-6e83-4b52-a0d7-3c5148ef9b26", "dimension": "direction", "label": "Direction" } ], "filterDefaults": { "1f0b7d55-8c31-42a6-9e74-6b0d2f83a915": [ "inbound" ] }, "timezone": "America/Los_Angeles", "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z", "widgets": [ { "id": "b8e51d34-79c2-4f61-9a08-2d47c6e13f85", "suid": "wgt4kx", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "dashboardId": "d41c8f6a-2b7e-4c19-83af-5e2d6b90c714", "title": "Calls by day", "chartType": "line", "dataSourceId": "9a2f47c1-6e83-4b52-a0d7-3c5148ef9b26", "queryConfig": { "measures": [ "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.count" ], "timeDimensions": [ { "dimension": "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.startTime", "granularity": "day", "dateRange": "last 30 days" } ], "filters": [ { "dimension": "ds_9a2f47c1_6e83_4b52_a0d7_3c5148ef9b26.direction", "operator": "equals", "values": [ "inbound" ] } ] }, "displayConfig": { "legend": { "show": false } }, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } ] } } } }, "404": { "description": "No such dashboard." } }, "summary": "Get a dashboard", "tags": [ "Dashboards" ] }, "patch": { "description": "Only what you send changes. Setting `isDefault` clears it on whatever dashboard held it before, since an organization has one default. Widgets are not touched here.", "operationId": "DashboardController.updateDashboard", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDashboardDto" }, "examples": { "rename": { "summary": "Rename", "value": { "name": "Contact Center - EU" } }, "clearTimezone": { "summary": "Fall back to each viewer’s own timezone", "value": { "timezone": null } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardResponseDto" }, "example": { "id": "d41c8f6a-2b7e-4c19-83af-5e2d6b90c714", "suid": "dsh7q2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Contact Center Overview", "description": "Daily call volume and handle time.", "isDefault": true, "layout": [ { "widgetId": "b8e51d34-79c2-4f61-9a08-2d47c6e13f85", "x": 0, "y": 0, "w": 6, "h": 4 } ], "filterConfig": [ { "id": "1f0b7d55-8c31-42a6-9e74-6b0d2f83a915", "dataSourceId": "9a2f47c1-6e83-4b52-a0d7-3c5148ef9b26", "dimension": "direction", "label": "Direction" } ], "filterDefaults": { "1f0b7d55-8c31-42a6-9e74-6b0d2f83a915": [ "inbound" ] }, "timezone": "America/Los_Angeles", "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } } } }, "400": { "description": "A filter references a data source in another organization." }, "404": { "description": "No such dashboard." } }, "summary": "Update a dashboard", "tags": [ "Dashboards" ] } }, "/dashboards/{id}/export-pdf": { "post": { "description": "Renders HTML you supply — the browser sends its own rendered dashboard — into a print-styled PDF. This endpoint does NOT re-run the widgets, so it cannot be used to fetch a dashboard headlessly.", "operationId": "DashboardController.exportPdf", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportPdfDto" }, "examples": { "landscape": { "summary": "Landscape A4", "value": { "html": "

Contact Center Overview

", "title": "Contact Center Overview", "landscape": true, "pageSize": "A4" } } } } } }, "responses": { "200": { "description": "PDF attachment named after the title, or the dashboard.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "No such dashboard." } }, "summary": "Export a dashboard as PDF", "tags": [ "Dashboards" ] } }, "/dashboards/{id}/layout": { "patch": { "description": "Replaces the grid placement wholesale, so send every widget you want to keep: any widget missing from `layout` disappears from the grid.", "operationId": "DashboardController.saveLayout", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveDashboardLayoutDto" }, "examples": { "twoUp": { "summary": "Two widgets side by side", "value": { "layout": [ { "widgetId": "b8e51d34-79c2-4f61-9a08-2d47c6e13f85", "x": 0, "y": 0, "w": 6, "h": 4 }, { "widgetId": "f2c47a10-5b93-4e28-8d6f-1a05b7e42c93", "x": 6, "y": 0, "w": 6, "h": 4 } ] } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardResponseDto" }, "example": { "id": "d41c8f6a-2b7e-4c19-83af-5e2d6b90c714", "suid": "dsh7q2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Contact Center Overview", "description": "Daily call volume and handle time.", "isDefault": true, "layout": [ { "widgetId": "b8e51d34-79c2-4f61-9a08-2d47c6e13f85", "x": 0, "y": 0, "w": 6, "h": 4 } ], "filterConfig": [ { "id": "1f0b7d55-8c31-42a6-9e74-6b0d2f83a915", "dataSourceId": "9a2f47c1-6e83-4b52-a0d7-3c5148ef9b26", "dimension": "direction", "label": "Direction" } ], "filterDefaults": { "1f0b7d55-8c31-42a6-9e74-6b0d2f83a915": [ "inbound" ] }, "timezone": "America/Los_Angeles", "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } } } }, "404": { "description": "No such dashboard." } }, "summary": "Save a dashboard layout", "tags": [ "Dashboards" ] } }, "/data-stores": { "get": { "description": "Records addressed as rows rather than by table and key: one flat, filterable list across every table in the organization. Useful for sweeps and exports; for reading a table, `GET /data-stores/tables/{tableName}` is the endpoint that understands prefixes and value filters. Note this list does include the reserved `__meta__` marker rows, which the table routes hide. Requires `workflows:view`.", "operationId": "DataStoreController.list", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataStoreListResponseDto" }, "example": { "total": 2, "data": [ { "id": "9c2f0f2a-7d41-4a6e-8b03-2f5c1d9e4a77", "suid": "q7m2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "tableName": "order_status", "key": "ord_10428", "value": { "status": "shipped", "carrier": "regional-freight", "attempts": 1 }, "expiresAt": null, "recordTimestamp": "2026-07-26T18:22:04.000Z", "createdAt": "2026-07-26T18:22:05.118Z", "updatedAt": "2026-07-27T09:14:41.702Z" }, { "id": "b41d8e60-3c92-4f17-9a55-6e0b7c2d8813", "suid": "r3k8", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "tableName": "order_status", "key": "ord_10429", "value": { "status": "pending", "carrier": null, "attempts": 0 }, "expiresAt": null, "recordTimestamp": "2026-07-27T08:05:00.000Z", "createdAt": "2026-07-27T08:05:01.004Z", "updatedAt": "2026-07-27T08:05:01.004Z" } ] } } } } }, "summary": "List records across tables", "tags": [ "Data Stores" ] }, "post": { "description": "Writes one record with the table named in the body. Unlike the table write endpoint this is a plain insert, not an upsert: a `tableName` + `key` pair that already exists fails on the unique index instead of overwriting. Prefer `POST /data-stores/tables/{tableName}` for day-to-day writes. Requires `workflows:admin`.", "operationId": "DataStoreController.create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDataStoreDto" }, "examples": { "record": { "summary": "A record", "value": { "tableName": "order_status", "key": "ord_10428", "value": { "status": "shipped", "carrier": "regional-freight", "attempts": 1 } } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataStoreEntryResponseDto" }, "example": { "id": "9c2f0f2a-7d41-4a6e-8b03-2f5c1d9e4a77", "suid": "q7m2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "tableName": "order_status", "key": "ord_10428", "value": { "status": "shipped", "carrier": "regional-freight", "attempts": 1 }, "expiresAt": null, "recordTimestamp": "2026-07-26T18:22:04.000Z", "createdAt": "2026-07-26T18:22:05.118Z", "updatedAt": "2026-07-27T09:14:41.702Z" } } } }, "400": { "description": "`tableName`, `key` or `value` was missing or malformed." } }, "summary": "Create a record", "tags": [ "Data Stores" ] } }, "/data-stores/tables": { "get": { "description": "Every registered table in the active organization with its record count. There is no schema to define: a table is registered by creating it, by importing into it, or by a workflow step writing to it. Counts exclude the reserved `__meta__` marker row. Requires `workflows:view`.", "operationId": "DataStoreController.listTables", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Tables per page. Defaults to 100; a negative value returns all of them.", "schema": { "type": "string" } }, { "name": "offset", "required": false, "in": "query", "description": "Tables to skip. Defaults to 0.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataStoreTablesListResponseDto" }, "example": { "tables": [ { "tableName": "order_status", "keyCount": 1284 }, { "tableName": "suppression_list", "keyCount": 52310, "analyticsTag": "suppression" } ], "total": 2, "hasMore": false } } } } }, "summary": "List tables", "tags": [ "Data Stores" ] }, "post": { "description": "Registers an empty table so it is visible before anything is written to it. Idempotent: an existing table is left untouched and comes back with `created: false`. Requires `workflows:admin`.", "operationId": "DataStoreController.createTable", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDataStoreTableBodyDto" }, "examples": { "table": { "summary": "New table", "value": { "tableName": "order_status" } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataStoreCreateTableResponseDto" }, "example": { "tableName": "order_status", "created": true } } } }, "400": { "description": "`tableName` was missing." } }, "summary": "Create a table", "tags": [ "Data Stores" ] } }, "/data-stores/tables/{tableName}": { "delete": { "description": "Permanently removes every record in the table, in operational and analytics storage alike, and the table itself. There is no undo and no recycle bin — take an export first if the records matter. The count includes the marker row that represents the table, so it is one higher than the record count. Requires `workflows:admin`.", "operationId": "DataStoreController.deleteTable", "parameters": [ { "name": "tableName", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataStoreDeletedCountResponseDto" }, "example": { "deleted": 1285 } } } } }, "summary": "Delete a table", "tags": [ "Data Stores" ] }, "get": { "description": "A page of records from one table, values returned exactly as stored. Two ways to narrow the page: `prefix` matches against the key, and `filter` matches against fields inside the value. They are not combined — `filter` wins when both are sent. The reserved `__meta__` marker row is never returned. Requires `workflows:view`.", "operationId": "DataStoreController.listTableEntries", "parameters": [ { "name": "tableName", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "prefix", "required": false, "in": "query", "description": "Case-insensitive substring match on the key. Despite the name it matches anywhere in the key, not only at the start.", "schema": { "type": "string" } }, { "name": "filter", "required": false, "in": "query", "description": "Match on a field inside the value: `field:value` for a partial match, `field:=value` for an exact one. Dots walk nested objects (`customer.tier:=gold`), `[]` reaches into arrays (`items[].sku:AB-12`), and brackets quote a field name that is not a plain identifier (`[ORDER TOTAL]:=42`).", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Records per page. Defaults to 100.", "schema": { "type": "string" } }, { "name": "offset", "required": false, "in": "query", "description": "Records to skip. Defaults to 0.", "schema": { "type": "string" } }, { "name": "sortBy", "required": false, "in": "query", "description": "One of `key`, `createdAt`, `updatedAt`. Anything else is ignored and `key` is used.", "schema": { "type": "string" } }, { "name": "sortDirection", "required": false, "in": "query", "description": "`asc` or `desc`. Defaults to `asc`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataStoreEntriesListResponseDto" }, "example": { "entries": [ { "id": "9c2f0f2a-7d41-4a6e-8b03-2f5c1d9e4a77", "suid": "q7m2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "tableName": "order_status", "key": "ord_10428", "value": { "status": "shipped", "carrier": "regional-freight", "attempts": 1 }, "expiresAt": null, "recordTimestamp": "2026-07-26T18:22:04.000Z", "createdAt": "2026-07-26T18:22:05.118Z", "updatedAt": "2026-07-27T09:14:41.702Z" }, { "id": "b41d8e60-3c92-4f17-9a55-6e0b7c2d8813", "suid": "r3k8", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "tableName": "order_status", "key": "ord_10429", "value": { "status": "pending", "carrier": null, "attempts": 0 }, "expiresAt": null, "recordTimestamp": "2026-07-27T08:05:00.000Z", "createdAt": "2026-07-27T08:05:01.004Z", "updatedAt": "2026-07-27T08:05:01.004Z" } ], "total": 1284, "hasMore": true, "source": "postgres" } } } } }, "summary": "List records in a table", "tags": [ "Data Stores" ] }, "post": { "description": "Writes one record. An upsert: writing an existing key replaces its value outright rather than merging into it. `ttlSeconds` makes the record self-expire — it stops being returned once it lapses. Unlike import, this does not register the table, so a first write into a table that was never created leaves it out of `GET /data-stores/tables` until something registers it. Requires `workflows:admin`.", "operationId": "DataStoreController.createTableEntry", "parameters": [ { "name": "tableName", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDataStoreEntryDto" }, "examples": { "record": { "summary": "A record", "value": { "key": "ord_10428", "value": { "status": "shipped", "carrier": "regional-freight", "attempts": 1 } } }, "expiring": { "summary": "Expires after an hour", "value": { "key": "quote_5581", "value": { "total": 149.5, "currency": "USD" }, "ttlSeconds": 3600 } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataStoreEntryResponseDto" }, "example": { "id": "9c2f0f2a-7d41-4a6e-8b03-2f5c1d9e4a77", "suid": "q7m2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "tableName": "order_status", "key": "ord_10428", "value": { "status": "shipped", "carrier": "regional-freight", "attempts": 1 }, "expiresAt": null, "recordTimestamp": "2026-07-26T18:22:04.000Z", "createdAt": "2026-07-26T18:22:05.118Z", "updatedAt": "2026-07-27T09:14:41.702Z" } } } }, "400": { "description": "`key` or `value` was missing, or `ttlSeconds` was outside 60 seconds to one year." } }, "summary": "Write a record", "tags": [ "Data Stores" ] } }, "/data-stores/tables/{tableName}/analytics-tag": { "patch": { "description": "Sets the label that groups a table for dashboards. Send an empty `analyticsTag`, or omit it, to clear the tag. Records are untouched either way. Requires `workflows:admin`.", "operationId": "DataStoreController.updateAnalyticsTag", "parameters": [ { "name": "tableName", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDataStoreAnalyticsTagBodyDto" }, "examples": { "set": { "summary": "Set the tag", "value": { "analyticsTag": "orders" } }, "clear": { "summary": "Clear the tag", "value": { "analyticsTag": "" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataStoreAnalyticsTagResponseDto" }, "example": { "tableName": "order_status", "analyticsTag": "orders" } } } }, "404": { "description": "No such table in the caller’s organization." } }, "summary": "Tag a table for analytics", "tags": [ "Data Stores" ] } }, "/data-stores/tables/{tableName}/bulk-delete": { "post": { "description": "Permanently removes up to 50,000 records by key. There is no undo and no soft-delete tier: a deleted record is gone from operational and analytics storage alike. A `POST` because the key list travels in the body. Keys that match nothing are reported in `notFound` rather than failing the call, so the request is safe to retry. The reserved `__meta__` key is refused, which is what keeps the table itself alive. Requires `workflows:admin`.", "operationId": "DataStoreController.bulkDeleteTableEntries", "parameters": [ { "name": "tableName", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeleteEntriesDto" }, "examples": { "keys": { "summary": "Two keys", "value": { "keys": [ "ord_10428", "ord_10429" ] } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataStoreBulkDeleteResponseDto" }, "example": { "deleted": 1, "notFound": [ "ord_10429" ], "errors": [] } } } }, "400": { "description": "`keys` was empty or over 50,000 long." } }, "summary": "Delete records by key", "tags": [ "Data Stores" ] } }, "/data-stores/tables/{tableName}/import": { "post": { "description": "Upserts up to 50,000 records in one call, creating the table if it does not exist. An existing key is overwritten in full — this is a replace, not a merge, so a partial value drops the fields it omits. Duplicate keys within one payload collapse to the last occurrence, and the reserved `__meta__` key is refused and reported in `errors` rather than failing the import. Requires `workflows:admin`.", "operationId": "DataStoreController.importTableEntries", "parameters": [ { "name": "tableName", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkImportDto" }, "examples": { "records": { "summary": "Two records", "value": { "entries": [ { "key": "ord_10428", "value": { "status": "shipped", "attempts": 1 } }, { "key": "ord_10429", "value": { "status": "pending", "attempts": 0 } } ] } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataStoreImportResponseDto" }, "example": { "total": 2, "created": 1, "updated": 1, "errors": [] } } } }, "400": { "description": "`entries` was empty, over 50,000 long, or an entry was missing `key` or `value`." } }, "summary": "Import records", "tags": [ "Data Stores" ] } }, "/data-stores/tables/{tableName}/{key}": { "delete": { "description": "Permanently removes one record from every storage that holds it, including the analytics copy. There is no undo. Idempotent: deleting a record that is already gone returns `deleted: false` rather than an error. Requires `workflows:admin`.", "operationId": "DataStoreController.deleteTableEntry", "parameters": [ { "name": "tableName", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "key", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataStoreDeletedFlagResponseDto" }, "example": { "deleted": true } } } } }, "summary": "Delete a record", "tags": [ "Data Stores" ] }, "get": { "description": "One record by table and key. Requires `workflows:view`.", "operationId": "DataStoreController.getTableEntry", "parameters": [ { "name": "tableName", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "key", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataStoreEntryResponseDto" }, "example": { "id": "9c2f0f2a-7d41-4a6e-8b03-2f5c1d9e4a77", "suid": "q7m2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "tableName": "order_status", "key": "ord_10428", "value": { "status": "shipped", "carrier": "regional-freight", "attempts": 1 }, "expiresAt": null, "recordTimestamp": "2026-07-26T18:22:04.000Z", "createdAt": "2026-07-26T18:22:05.118Z", "updatedAt": "2026-07-27T09:14:41.702Z" } } } }, "404": { "description": "No such record in the caller’s organization. An expired record reads as missing." } }, "summary": "Get a record", "tags": [ "Data Stores" ] }, "patch": { "description": "Replaces the value of an existing record. `PATCH` addresses the record, not the fields inside it: the value you send becomes the whole value. Expiry is preserved unless `ttlSeconds` is sent — a number restarts the countdown from now, and `null` removes expiry entirely. Requires `workflows:admin`.", "operationId": "DataStoreController.updateTableEntry", "parameters": [ { "name": "tableName", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "key", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDataStoreEntryDto" }, "examples": { "replace": { "summary": "Replace the value", "value": { "value": { "status": "delivered", "carrier": "regional-freight", "attempts": 1 } } }, "clearExpiry": { "summary": "Keep it forever", "value": { "value": { "status": "delivered" }, "ttlSeconds": null } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataStoreEntryResponseDto" }, "example": { "id": "9c2f0f2a-7d41-4a6e-8b03-2f5c1d9e4a77", "suid": "q7m2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "tableName": "order_status", "key": "ord_10428", "value": { "status": "delivered", "carrier": "regional-freight", "attempts": 1 }, "expiresAt": null, "recordTimestamp": "2026-07-26T18:22:04.000Z", "createdAt": "2026-07-26T18:22:05.118Z", "updatedAt": "2026-07-27T09:14:41.702Z" } } } }, "404": { "description": "No such record. Use the write endpoint to create one." } }, "summary": "Update a record", "tags": [ "Data Stores" ] } }, "/data-stores/tables/{tableName}/{key}/forget": { "delete": { "description": "Erases one record everywhere it is held. Reach for this when you have to be able to state that a record is gone — a deletion request, for example. It is not stronger than deleting the record: that route is storage-aware too and reaches the same end state. What differs is the permission, `data-stores:admin` rather than `workflows:admin`, so the operation can be granted to a narrower set of people. Idempotent: forgetting an already-forgotten record returns `forgotten: false`.", "operationId": "DataStoreController.forgetTableEntry", "parameters": [ { "name": "tableName", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "key", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataStoreForgottenFlagResponseDto" }, "example": { "forgotten": true } } } }, "403": { "description": "Caller does not hold `data-stores:admin`." } }, "summary": "Forget a record", "tags": [ "Data Stores" ] } }, "/data-stores/{id}": { "delete": { "description": "Permanently removes the record with this id and returns what was removed. There is no undo. This addresses the operational row directly, so for a table whose records have been shipped to analytics storage use `DELETE /data-stores/tables/{tableName}/{key}`, which clears both. Requires `workflows:admin`.", "operationId": "DataStoreController.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataStoreEntryResponseDto" }, "example": { "id": "9c2f0f2a-7d41-4a6e-8b03-2f5c1d9e4a77", "suid": "q7m2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "tableName": "order_status", "key": "ord_10428", "value": { "status": "shipped", "carrier": "regional-freight", "attempts": 1 }, "expiresAt": null, "recordTimestamp": "2026-07-26T18:22:04.000Z", "createdAt": "2026-07-26T18:22:05.118Z", "updatedAt": "2026-07-27T09:14:41.702Z" } } } }, "404": { "description": "No such record in the caller’s organization." } }, "summary": "Delete a record by id", "tags": [ "Data Stores" ] }, "get": { "description": "One record addressed by row id. Requires `workflows:view`.", "operationId": "DataStoreController.get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataStoreEntryResponseDto" }, "example": { "id": "9c2f0f2a-7d41-4a6e-8b03-2f5c1d9e4a77", "suid": "q7m2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "tableName": "order_status", "key": "ord_10428", "value": { "status": "shipped", "carrier": "regional-freight", "attempts": 1 }, "expiresAt": null, "recordTimestamp": "2026-07-26T18:22:04.000Z", "createdAt": "2026-07-26T18:22:05.118Z", "updatedAt": "2026-07-27T09:14:41.702Z" } } } }, "404": { "description": "No such record in the caller’s organization." } }, "summary": "Get a record by id", "tags": [ "Data Stores" ] }, "patch": { "description": "Replaces the value of the record with this id. Only `value` is writable — the table and key are fixed once the record exists, and expiry is left alone. Requires `workflows:admin`.", "operationId": "DataStoreController.update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDataStoreDto" }, "examples": { "replace": { "summary": "Replace the value", "value": { "value": { "status": "delivered", "attempts": 1 } } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataStoreEntryResponseDto" }, "example": { "id": "9c2f0f2a-7d41-4a6e-8b03-2f5c1d9e4a77", "suid": "q7m2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "tableName": "order_status", "key": "ord_10428", "value": { "status": "delivered", "attempts": 1 }, "expiresAt": null, "recordTimestamp": "2026-07-26T18:22:04.000Z", "createdAt": "2026-07-26T18:22:05.118Z", "updatedAt": "2026-07-27T09:14:41.702Z" } } } }, "404": { "description": "No such record in the caller’s organization." } }, "summary": "Update a record by id", "tags": [ "Data Stores" ] } }, "/environments": { "get": { "description": "Environments in the caller’s organization. Each one carries its full variable list, but the values are ciphertext: use `GET /environments/{id}/variables` to read them. Requires `secrets:view`.", "operationId": "EnvironmentController.list", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentListResponseDto" }, "example": { "total": 1, "data": [ { "id": "9b1d4c07-2f8a-4e63-9c15-7a0e5d3b1f42", "suid": "q7m2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "production", "metadata": {}, "variables": [ { "id": "e2c8b5a1-7d34-4f90-b6e2-1c9d0a4f7b83", "suid": "p3xd", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "key": "CRM_API_TOKEN", "encryptedValue": "{\"version\":1,\"iv\":\"\",\"data\":\"\",\"tag\":\"\"}", "environment": "9b1d4c07-2f8a-4e63-9c15-7a0e5d3b1f42", "metadata": {}, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" }, { "id": "5a41f0d6-9b27-4c85-8e13-2f6b7c04a9de", "suid": "w8kt", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "key": "CRM_BASE_URL", "encryptedValue": "{\"version\":1,\"iv\":\"\",\"data\":\"\",\"tag\":\"\"}", "environment": "9b1d4c07-2f8a-4e63-9c15-7a0e5d3b1f42", "metadata": {}, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } ], "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } ] } } } } }, "summary": "List environments", "tags": [ "Environments" ] }, "post": { "description": "Creates an environment and encrypts any variables sent with it. Names are unique per organization and must be a valid identifier; `shared` is reserved by the platform. Requires `secrets:admin`.", "operationId": "EnvironmentController.create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEnvironmentDto" }, "examples": { "empty": { "summary": "Name only", "value": { "name": "production" } }, "withVariables": { "summary": "With variables", "value": { "name": "production", "variables": [ { "key": "CRM_BASE_URL", "value": "https://acme.example.com" }, { "key": "CRM_API_TOKEN", "value": "" } ] } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentResponseDto" }, "example": { "id": "9b1d4c07-2f8a-4e63-9c15-7a0e5d3b1f42", "suid": "q7m2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "production", "metadata": {}, "variables": [ { "id": "e2c8b5a1-7d34-4f90-b6e2-1c9d0a4f7b83", "suid": "p3xd", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "key": "CRM_API_TOKEN", "encryptedValue": "{\"version\":1,\"iv\":\"\",\"data\":\"\",\"tag\":\"\"}", "environment": "9b1d4c07-2f8a-4e63-9c15-7a0e5d3b1f42", "metadata": {}, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" }, { "id": "5a41f0d6-9b27-4c85-8e13-2f6b7c04a9de", "suid": "w8kt", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "key": "CRM_BASE_URL", "encryptedValue": "{\"version\":1,\"iv\":\"\",\"data\":\"\",\"tag\":\"\"}", "environment": "9b1d4c07-2f8a-4e63-9c15-7a0e5d3b1f42", "metadata": {}, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } ], "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } } } }, "400": { "description": "The name is reserved by the platform, or is not a valid identifier." }, "403": { "description": "Caller lacks `secrets:admin`." } }, "summary": "Create an environment", "tags": [ "Environments" ] } }, "/environments/{id}": { "delete": { "description": "Deletes the environment and every variable in it. Workflows that read `{{ $env.KEY }}` against it will fail to resolve afterwards. The reserved `shared` environment cannot be deleted. Requires `secrets:admin`.", "operationId": "EnvironmentController.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentResponseDto" }, "example": { "id": "9b1d4c07-2f8a-4e63-9c15-7a0e5d3b1f42", "suid": "q7m2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "production", "metadata": {}, "variables": [ { "id": "e2c8b5a1-7d34-4f90-b6e2-1c9d0a4f7b83", "suid": "p3xd", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "key": "CRM_API_TOKEN", "encryptedValue": "{\"version\":1,\"iv\":\"\",\"data\":\"\",\"tag\":\"\"}", "environment": "9b1d4c07-2f8a-4e63-9c15-7a0e5d3b1f42", "metadata": {}, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" }, { "id": "5a41f0d6-9b27-4c85-8e13-2f6b7c04a9de", "suid": "w8kt", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "key": "CRM_BASE_URL", "encryptedValue": "{\"version\":1,\"iv\":\"\",\"data\":\"\",\"tag\":\"\"}", "environment": "9b1d4c07-2f8a-4e63-9c15-7a0e5d3b1f42", "metadata": {}, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } ], "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } } } }, "400": { "description": "The environment is reserved by the platform." }, "403": { "description": "Caller lacks `secrets:admin`." }, "404": { "description": "No such environment in the caller’s organization." } }, "summary": "Delete an environment", "tags": [ "Environments" ] }, "get": { "description": "Variable values come back encrypted. Requires `secrets:view`.", "operationId": "EnvironmentController.get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentResponseDto" }, "example": { "id": "9b1d4c07-2f8a-4e63-9c15-7a0e5d3b1f42", "suid": "q7m2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "production", "metadata": {}, "variables": [ { "id": "e2c8b5a1-7d34-4f90-b6e2-1c9d0a4f7b83", "suid": "p3xd", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "key": "CRM_API_TOKEN", "encryptedValue": "{\"version\":1,\"iv\":\"\",\"data\":\"\",\"tag\":\"\"}", "environment": "9b1d4c07-2f8a-4e63-9c15-7a0e5d3b1f42", "metadata": {}, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" }, { "id": "5a41f0d6-9b27-4c85-8e13-2f6b7c04a9de", "suid": "w8kt", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "key": "CRM_BASE_URL", "encryptedValue": "{\"version\":1,\"iv\":\"\",\"data\":\"\",\"tag\":\"\"}", "environment": "9b1d4c07-2f8a-4e63-9c15-7a0e5d3b1f42", "metadata": {}, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } ], "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } } } }, "404": { "description": "No such environment in the caller’s organization." } }, "summary": "Get an environment", "tags": [ "Environments" ] }, "patch": { "description": "Sending `variables` REPLACES the whole set — anything not listed is deleted. Omit the field to change only the name and leave variables untouched; use `PATCH /environments/{id}/variables` to merge instead. The reserved `shared` environment cannot be modified. Requires `secrets:admin`.", "operationId": "EnvironmentController.update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEnvironmentDto" }, "examples": { "rename": { "summary": "Rename, keeping variables", "value": { "name": "production-eu" } }, "replaceVariables": { "summary": "Replace every variable", "value": { "variables": [ { "key": "CRM_API_TOKEN", "value": "" } ] } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentResponseDto" }, "example": { "id": "9b1d4c07-2f8a-4e63-9c15-7a0e5d3b1f42", "suid": "q7m2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "production-eu", "metadata": {}, "variables": [ { "id": "e2c8b5a1-7d34-4f90-b6e2-1c9d0a4f7b83", "suid": "p3xd", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "key": "CRM_API_TOKEN", "encryptedValue": "{\"version\":1,\"iv\":\"\",\"data\":\"\",\"tag\":\"\"}", "environment": "9b1d4c07-2f8a-4e63-9c15-7a0e5d3b1f42", "metadata": {}, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" }, { "id": "5a41f0d6-9b27-4c85-8e13-2f6b7c04a9de", "suid": "w8kt", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "key": "CRM_BASE_URL", "encryptedValue": "{\"version\":1,\"iv\":\"\",\"data\":\"\",\"tag\":\"\"}", "environment": "9b1d4c07-2f8a-4e63-9c15-7a0e5d3b1f42", "metadata": {}, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } ], "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } } } }, "400": { "description": "The environment is reserved by the platform, or the new name is." }, "403": { "description": "Caller lacks `secrets:admin`." }, "404": { "description": "No such environment in the caller’s organization." } }, "summary": "Update an environment", "tags": [ "Environments" ] } }, "/environments/{id}/variable-keys": { "get": { "description": "Names only. Loads no encrypted values and runs no decryption, so this is the right call when you are mapping or checking for keys rather than reading them. Requires `secrets:view`.", "operationId": "EnvironmentController.listVariableKeys", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "404": { "description": "No such environment in the caller’s organization." } }, "summary": "List variable names", "tags": [ "Environments" ] } }, "/environments/{id}/variables": { "get": { "description": "The only endpoint that decrypts. Returns every variable in the environment as a flat map of name to **plaintext** value; every other environment response carries ciphertext.\n\nIt is gated on `secrets:view`, not `secrets:admin` — the same permission that lists environments — so anyone who can see an environment can read its secrets. If you only need the names, call `GET /environments/{id}/variable-keys`, which never decrypts.\n\nA value that cannot be decrypted (for example after a key rotation that dropped its key version) comes back as the literal string `[DECRYPTION_FAILED]` rather than failing the request.", "operationId": "EnvironmentController.getDecryptedVariables", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } }, "example": { "CRM_BASE_URL": "https://acme.example.com", "CRM_API_TOKEN": "" } } } }, "404": { "description": "No such environment in the caller’s organization." } }, "summary": "Read decrypted variables", "tags": [ "Environments" ] }, "patch": { "description": "Merges the listed variables into the environment: names not in the body are left alone. To replace the whole set instead, send `variables` to `PATCH /environments/{id}`. Requires `secrets:admin`.", "operationId": "EnvironmentController.bulkUpsertVariables", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkUpsertVariablesBodyDto" }, "examples": { "twoVariables": { "summary": "Set two variables", "value": { "variables": [ { "key": "CRM_BASE_URL", "value": "https://acme.example.com" }, { "key": "CRM_API_TOKEN", "value": "" } ] } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentResponseDto" }, "example": { "id": "9b1d4c07-2f8a-4e63-9c15-7a0e5d3b1f42", "suid": "q7m2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "production", "metadata": {}, "variables": [ { "id": "e2c8b5a1-7d34-4f90-b6e2-1c9d0a4f7b83", "suid": "p3xd", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "key": "CRM_API_TOKEN", "encryptedValue": "{\"version\":1,\"iv\":\"\",\"data\":\"\",\"tag\":\"\"}", "environment": "9b1d4c07-2f8a-4e63-9c15-7a0e5d3b1f42", "metadata": {}, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" }, { "id": "5a41f0d6-9b27-4c85-8e13-2f6b7c04a9de", "suid": "w8kt", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "key": "CRM_BASE_URL", "encryptedValue": "{\"version\":1,\"iv\":\"\",\"data\":\"\",\"tag\":\"\"}", "environment": "9b1d4c07-2f8a-4e63-9c15-7a0e5d3b1f42", "metadata": {}, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } ], "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } } } }, "403": { "description": "Caller lacks `secrets:admin`." }, "404": { "description": "No such environment in the caller’s organization." } }, "summary": "Create or update several variables", "tags": [ "Environments" ] } }, "/environments/{id}/variables/bulk-delete": { "post": { "description": "Removes every listed name in one write. Names that are not there are ignored. Requires `secrets:admin`.", "operationId": "EnvironmentController.bulkDeleteVariables", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeleteVariablesBodyDto" }, "examples": { "twoKeys": { "summary": "Drop two variables", "value": { "keys": [ "CRM_API_TOKEN", "CRM_BASE_URL" ] } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentResponseDto" }, "example": { "id": "9b1d4c07-2f8a-4e63-9c15-7a0e5d3b1f42", "suid": "q7m2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "production", "metadata": {}, "variables": [ { "id": "e2c8b5a1-7d34-4f90-b6e2-1c9d0a4f7b83", "suid": "p3xd", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "key": "CRM_API_TOKEN", "encryptedValue": "{\"version\":1,\"iv\":\"\",\"data\":\"\",\"tag\":\"\"}", "environment": "9b1d4c07-2f8a-4e63-9c15-7a0e5d3b1f42", "metadata": {}, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" }, { "id": "5a41f0d6-9b27-4c85-8e13-2f6b7c04a9de", "suid": "w8kt", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "key": "CRM_BASE_URL", "encryptedValue": "{\"version\":1,\"iv\":\"\",\"data\":\"\",\"tag\":\"\"}", "environment": "9b1d4c07-2f8a-4e63-9c15-7a0e5d3b1f42", "metadata": {}, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } ], "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } } } }, "403": { "description": "Caller lacks `secrets:admin`." }, "404": { "description": "No such environment in the caller’s organization." } }, "summary": "Delete several variables", "tags": [ "Environments" ] } }, "/environments/{id}/variables/{key}": { "delete": { "description": "Removing a name that is not there succeeds and changes nothing. Requires `secrets:admin`.", "operationId": "EnvironmentController.deleteVariable", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "key", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentResponseDto" }, "example": { "id": "9b1d4c07-2f8a-4e63-9c15-7a0e5d3b1f42", "suid": "q7m2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "production", "metadata": {}, "variables": [ { "id": "e2c8b5a1-7d34-4f90-b6e2-1c9d0a4f7b83", "suid": "p3xd", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "key": "CRM_API_TOKEN", "encryptedValue": "{\"version\":1,\"iv\":\"\",\"data\":\"\",\"tag\":\"\"}", "environment": "9b1d4c07-2f8a-4e63-9c15-7a0e5d3b1f42", "metadata": {}, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" }, { "id": "5a41f0d6-9b27-4c85-8e13-2f6b7c04a9de", "suid": "w8kt", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "key": "CRM_BASE_URL", "encryptedValue": "{\"version\":1,\"iv\":\"\",\"data\":\"\",\"tag\":\"\"}", "environment": "9b1d4c07-2f8a-4e63-9c15-7a0e5d3b1f42", "metadata": {}, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } ], "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } } } }, "403": { "description": "Caller lacks `secrets:admin`." }, "404": { "description": "No such environment in the caller’s organization." } }, "summary": "Delete one variable", "tags": [ "Environments" ] }, "patch": { "description": "Encrypts `value` and stores it under `key`, overwriting an existing entry. Returns the whole environment, with values still encrypted. Requires `secrets:admin`.", "operationId": "EnvironmentController.upsertVariable", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "key", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertVariableBodyDto" }, "examples": { "rotate": { "summary": "Rotate a token", "value": { "value": "" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentResponseDto" }, "example": { "id": "9b1d4c07-2f8a-4e63-9c15-7a0e5d3b1f42", "suid": "q7m2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "production", "metadata": {}, "variables": [ { "id": "e2c8b5a1-7d34-4f90-b6e2-1c9d0a4f7b83", "suid": "p3xd", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "key": "CRM_API_TOKEN", "encryptedValue": "{\"version\":1,\"iv\":\"\",\"data\":\"\",\"tag\":\"\"}", "environment": "9b1d4c07-2f8a-4e63-9c15-7a0e5d3b1f42", "metadata": {}, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" }, { "id": "5a41f0d6-9b27-4c85-8e13-2f6b7c04a9de", "suid": "w8kt", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "key": "CRM_BASE_URL", "encryptedValue": "{\"version\":1,\"iv\":\"\",\"data\":\"\",\"tag\":\"\"}", "environment": "9b1d4c07-2f8a-4e63-9c15-7a0e5d3b1f42", "metadata": {}, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } ], "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } } } }, "403": { "description": "Caller lacks `secrets:admin`." }, "404": { "description": "No such environment in the caller’s organization." } }, "summary": "Create or update one variable", "tags": [ "Environments" ] } }, "/execution-traces": { "get": { "description": "Workflow runs in the caller’s organization. Filter with `where[...]`: `where[status]=failed`, `where[workflowId]=`, or `where[searchAttributes][customer.region]=us-west` for the attributes a workflow marked searchable. Archived runs are excluded. Send `where[parentExecutionId]=null` for top-level runs only — that query additionally returns `childCounts`, so a grouped view can show how many sub-workflow runs sit under each root.", "operationId": "ExecutionTraceController.list", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionTraceListResponseDto" }, "example": { "total": 1, "data": [ { "id": "8c2f4b61-9a07-4d3e-b512-6f0e1a7c84d9", "suid": "q7m2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "workflowId": "d94a17e0-3c62-4f88-bb15-2e7d905ac431", "workflowName": "Nightly lead sync", "status": "success", "operationalStatus": "ok", "startedAt": "2026-07-27T04:00:00.118Z", "completedAt": "2026-07-27T04:00:07.642Z", "durationMilliseconds": 7524, "totalSteps": 2, "stepsExecuted": 2, "stepsFailed": 0, "stepsSkipped": 0, "triggerType": "schedule", "workerTier": "standard", "searchAttributes": { "customer.region": "us-west" }, "stepStatuses": { "fetch-leads": { "s": "s", "d": 1840, "b": 24576 }, "upsert-leads": { "s": "s", "d": 5610, "b": 512 } }, "stepPaths": { "fetch-leads": "fetch-leads", "upsert-leads": "upsert-leads" }, "traceStorageUri": "gs://example-traces/traces/3f7c1a92/d94a17e0/8c2f4b61.json.enc", "executionEpoch": 0, "resumeAttempts": 0, "metadata": {}, "createdAt": "2026-07-27T04:00:00.118Z", "updatedAt": "2026-07-27T04:00:07.701Z" } ] } } } } }, "summary": "List executions", "tags": [ "Executions" ] }, "post": { "description": "Writes an execution row directly. The engine does this itself as it runs a workflow, so a partner normally reads executions rather than creating them — reach for this only when importing runs from somewhere else. `id` is the execution id and is yours to choose.", "operationId": "ExecutionTraceController.create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateExecutionTraceDto" }, "examples": { "completedRun": { "summary": "A finished run", "value": { "id": "8c2f4b61-9a07-4d3e-b512-6f0e1a7c84d9", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "workflowId": "d94a17e0-3c62-4f88-bb15-2e7d905ac431", "workflowName": "Nightly lead sync", "status": "success", "startedAt": "2026-07-27T04:00:00.118Z", "completedAt": "2026-07-27T04:00:07.642Z", "durationMilliseconds": 7524 } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionTraceResponseDto" }, "example": { "id": "8c2f4b61-9a07-4d3e-b512-6f0e1a7c84d9", "suid": "q7m2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "workflowId": "d94a17e0-3c62-4f88-bb15-2e7d905ac431", "workflowName": "Nightly lead sync", "status": "success", "operationalStatus": "ok", "startedAt": "2026-07-27T04:00:00.118Z", "completedAt": "2026-07-27T04:00:07.642Z", "durationMilliseconds": 7524, "totalSteps": 2, "stepsExecuted": 2, "stepsFailed": 0, "stepsSkipped": 0, "triggerType": "schedule", "workerTier": "standard", "searchAttributes": { "customer.region": "us-west" }, "stepStatuses": { "fetch-leads": { "s": "s", "d": 1840, "b": 24576 }, "upsert-leads": { "s": "s", "d": 5610, "b": 512 } }, "stepPaths": { "fetch-leads": "fetch-leads", "upsert-leads": "upsert-leads" }, "traceStorageUri": "gs://example-traces/traces/3f7c1a92/d94a17e0/8c2f4b61.json.enc", "executionEpoch": 0, "resumeAttempts": 0, "metadata": {}, "createdAt": "2026-07-27T04:00:00.118Z", "updatedAt": "2026-07-27T04:00:07.701Z" } } } } }, "summary": "Record an execution", "tags": [ "Executions" ] } }, "/execution-traces/bulk/archive": { "post": { "description": "Hides runs from list queries and queues them for deletion once the organization’s retention window elapses. With retention set to zero days the rows and their traces are deleted immediately. Requires the `executions:edit` permission, and only touches runs in the active organization.", "operationId": "ExecutionTraceController.bulkArchive", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkExecutionTraceIdsDto" }, "examples": { "twoRuns": { "summary": "Archive two runs", "value": { "ids": [ "8c2f4b61-9a07-4d3e-b512-6f0e1a7c84d9", "b31d7ac4-2e58-4f10-9c76-5a4e08d2f613" ] } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionBulkArchiveResponseDto" }, "example": { "archived": 2 } } } } }, "summary": "Archive executions", "tags": [ "Executions" ] } }, "/execution-traces/bulk/cancel": { "post": { "description": "Asks every running run in the set to stop. Runs that already finished are skipped silently, so `cancelled` can be lower than the number of ids sent. Cancellation is cooperative: each run halts at its next safe boundary, so it stays `running` for a moment after this returns. Requires the `executions:cancel` permission.", "operationId": "ExecutionTraceController.bulkCancel", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkExecutionTraceIdsDto" }, "examples": { "twoRuns": { "summary": "Cancel two runs", "value": { "ids": [ "8c2f4b61-9a07-4d3e-b512-6f0e1a7c84d9", "b31d7ac4-2e58-4f10-9c76-5a4e08d2f613" ] } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionBulkCancelResponseDto" }, "example": { "cancelled": 1 } } } } }, "summary": "Cancel executions", "tags": [ "Executions" ] } }, "/execution-traces/bulk/unarchive": { "post": { "description": "Undoes an archive: the runs reappear in list queries and are no longer queued for deletion. Only works while the retention window is still open — once a run has been reaped there is nothing to restore. Requires the `executions:edit` permission.", "operationId": "ExecutionTraceController.bulkUnarchive", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkExecutionTraceIdsDto" }, "examples": { "oneRun": { "summary": "Restore one run", "value": { "ids": [ "8c2f4b61-9a07-4d3e-b512-6f0e1a7c84d9" ] } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionBulkUnarchiveResponseDto" }, "example": { "unarchived": 1 } } } } }, "summary": "Restore archived executions", "tags": [ "Executions" ] } }, "/execution-traces/{id}": { "delete": { "description": "Permanently removes one run. There is no grace period — prefer archiving if you may want the run back. The response is the row as it was before deletion.", "operationId": "ExecutionTraceController.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionTraceResponseDto" }, "example": { "id": "8c2f4b61-9a07-4d3e-b512-6f0e1a7c84d9", "suid": "q7m2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "workflowId": "d94a17e0-3c62-4f88-bb15-2e7d905ac431", "workflowName": "Nightly lead sync", "status": "success", "operationalStatus": "ok", "startedAt": "2026-07-27T04:00:00.118Z", "completedAt": "2026-07-27T04:00:07.642Z", "durationMilliseconds": 7524, "totalSteps": 2, "stepsExecuted": 2, "stepsFailed": 0, "stepsSkipped": 0, "triggerType": "schedule", "workerTier": "standard", "searchAttributes": { "customer.region": "us-west" }, "stepStatuses": { "fetch-leads": { "s": "s", "d": 1840, "b": 24576 }, "upsert-leads": { "s": "s", "d": 5610, "b": 512 } }, "stepPaths": { "fetch-leads": "fetch-leads", "upsert-leads": "upsert-leads" }, "traceStorageUri": "gs://example-traces/traces/3f7c1a92/d94a17e0/8c2f4b61.json.enc", "executionEpoch": 0, "resumeAttempts": 0, "metadata": {}, "createdAt": "2026-07-27T04:00:00.118Z", "updatedAt": "2026-07-27T04:00:07.701Z" } } } }, "404": { "description": "No such execution." } }, "summary": "Delete an execution", "tags": [ "Executions" ] }, "get": { "description": "The run’s index: status, counts, timings and lineage. Step outputs are not included — fetch one step at a time, or download the whole trace.", "operationId": "ExecutionTraceController.get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionTraceResponseDto" }, "example": { "id": "8c2f4b61-9a07-4d3e-b512-6f0e1a7c84d9", "suid": "q7m2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "workflowId": "d94a17e0-3c62-4f88-bb15-2e7d905ac431", "workflowName": "Nightly lead sync", "status": "success", "operationalStatus": "ok", "startedAt": "2026-07-27T04:00:00.118Z", "completedAt": "2026-07-27T04:00:07.642Z", "durationMilliseconds": 7524, "totalSteps": 2, "stepsExecuted": 2, "stepsFailed": 0, "stepsSkipped": 0, "triggerType": "schedule", "workerTier": "standard", "searchAttributes": { "customer.region": "us-west" }, "stepStatuses": { "fetch-leads": { "s": "s", "d": 1840, "b": 24576 }, "upsert-leads": { "s": "s", "d": 5610, "b": 512 } }, "stepPaths": { "fetch-leads": "fetch-leads", "upsert-leads": "upsert-leads" }, "traceStorageUri": "gs://example-traces/traces/3f7c1a92/d94a17e0/8c2f4b61.json.enc", "executionEpoch": 0, "resumeAttempts": 0, "metadata": {}, "createdAt": "2026-07-27T04:00:00.118Z", "updatedAt": "2026-07-27T04:00:07.701Z" } } } }, "404": { "description": "No such execution, or it belongs to another organization." } }, "summary": "Get an execution", "tags": [ "Executions" ] }, "patch": { "description": "Amends a recorded run. The engine owns these columns while a workflow is in flight, so writing to a live run races it — this is for correcting rows you imported yourself. `id` and `organizationId` cannot be changed.", "operationId": "ExecutionTraceController.update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateExecutionTraceDto" }, "examples": { "correctOutcome": { "summary": "Correct the outcome", "value": { "status": "failed", "error": "Upstream API returned 503" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionTraceResponseDto" }, "example": { "id": "8c2f4b61-9a07-4d3e-b512-6f0e1a7c84d9", "suid": "q7m2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "workflowId": "d94a17e0-3c62-4f88-bb15-2e7d905ac431", "workflowName": "Nightly lead sync", "status": "success", "operationalStatus": "ok", "startedAt": "2026-07-27T04:00:00.118Z", "completedAt": "2026-07-27T04:00:07.642Z", "durationMilliseconds": 7524, "totalSteps": 2, "stepsExecuted": 2, "stepsFailed": 0, "stepsSkipped": 0, "triggerType": "schedule", "workerTier": "standard", "searchAttributes": { "customer.region": "us-west" }, "stepStatuses": { "fetch-leads": { "s": "s", "d": 1840, "b": 24576 }, "upsert-leads": { "s": "s", "d": 5610, "b": 512 } }, "stepPaths": { "fetch-leads": "fetch-leads", "upsert-leads": "upsert-leads" }, "traceStorageUri": "gs://example-traces/traces/3f7c1a92/d94a17e0/8c2f4b61.json.enc", "executionEpoch": 0, "resumeAttempts": 0, "metadata": {}, "createdAt": "2026-07-27T04:00:00.118Z", "updatedAt": "2026-07-27T04:00:07.701Z" } } } }, "404": { "description": "No such execution." } }, "summary": "Update an execution", "tags": [ "Executions" ] } }, "/execution-traces/{id}/cancel": { "post": { "description": "Asks a running execution to stop. The response is the run with `cancelRequestedAt` set — cancellation is cooperative, so the run keeps `status` `running` until it reaches its next safe boundary and flips to `cancelled`. Requires the `executions:cancel` permission.", "operationId": "ExecutionTraceController.cancel", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionTraceResponseDto" }, "example": { "id": "8c2f4b61-9a07-4d3e-b512-6f0e1a7c84d9", "suid": "q7m2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "workflowId": "d94a17e0-3c62-4f88-bb15-2e7d905ac431", "workflowName": "Nightly lead sync", "status": "running", "startedAt": "2026-07-27T04:00:00.118Z", "totalSteps": 2, "stepsExecuted": 1, "triggerType": "schedule", "workerTier": "standard", "cancelRequestedAt": "2026-07-27T04:00:04.902Z", "cancelRequestedBy": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "executionEpoch": 0, "resumeAttempts": 0, "metadata": {}, "createdAt": "2026-07-27T04:00:00.118Z", "updatedAt": "2026-07-27T04:00:04.902Z" } } } }, "400": { "description": "The execution already finished, so there is nothing to stop." }, "404": { "description": "No such execution." } }, "summary": "Cancel an execution", "tags": [ "Executions" ] } }, "/execution-traces/{id}/external-input": { "post": { "description": "Records an answer against a suspended run and wakes it. `path` names the waiting step, exactly as the run’s `suspension` reported it. The answer is stored before the wake is attempted, so a failed wake never loses it — retrying re-records and re-publishes. Requires the `executions:edit` permission.", "operationId": "ExecutionTraceController.recordExternalInput", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordExternalInputDto" }, "examples": { "approval": { "summary": "Approve a waiting step", "value": { "path": "await-approval", "payload": { "approved": true, "approver": "dana@example.com" } } }, "noValue": { "summary": "An answer that carries no value", "value": { "path": "await-approval", "payload": null } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionExternalInputResponseDto" }, "example": { "recorded": true, "resumed": true } } } }, "404": { "description": "No such execution, or it is not waiting on an answer." }, "409": { "description": "The answer was recorded, but the run cannot be re-entered — the payload it would resume from is missing. Nothing further will happen to this execution." } }, "summary": "Answer a waiting execution", "tags": [ "Executions" ] } }, "/execution-traces/{id}/signed-url": { "post": { "description": "Turns a storage reference a step produced into a time-limited download link. The execution id is what authorizes the read: the file must sit inside the storage namespace of the organization that ran it, so a reference from another organization is refused.", "operationId": "ExecutionTraceController.getSignedUrl", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "The `gs://` or `s3://` reference to sign, taken from a step’s output. No other scheme is accepted." }, "expiresInMinutes": { "type": "number", "default": 60, "description": "How long the link stays valid." } } }, "examples": { "exportedCsv": { "summary": "Sign a file a step wrote", "value": { "url": "gs://example-files/orgs/3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471/exports/leads.csv", "expiresInMinutes": 15 } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionSignedUrlResponseDto" }, "example": { "signedUrl": "https://storage.example.com/example-files/orgs/3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471/exports/leads.csv?signature=EXAMPLE-NOT-A-REAL-SIGNATURE", "expiresAt": "2026-07-27T04:15:00.000Z" } } } }, "400": { "description": "The reference is missing, uses an unsupported scheme, or points outside this organization’s storage namespace." }, "404": { "description": "No such execution." } }, "summary": "Get a download link for a step’s file", "tags": [ "Executions" ] } }, "/execution-traces/{id}/steps/{stepId}": { "get": { "description": "What one step produced, plus the `$meta` block the engine attaches and the `$input` it ran on. Credential values are redacted. An output too large to return in full comes back as a bounded sketch marked with `$preview` and `$truncated`, still at HTTP 200 — download the full trace for the untruncated value.", "operationId": "ExecutionTraceController.getStepOutput", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "stepId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "stepPath", "required": false, "in": "query", "description": "Disambiguates a nested step whose id repeats — a loop body, or a step inside a branch. Take the value from the execution’s `stepPaths`, e.g. `for-each-1/3/send-email`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionStepOutputResponseDto" }, "example": { "$meta": { "success": true, "error": null, "skipped": false, "stepType": "core.http", "durationMilliseconds": 1840, "outputSizeBytes": 24576 }, "$input": { "method": "GET", "url": "https://api.example.com/v1/leads?updated_since=2026-07-26" }, "status": 200, "data": { "leads": [ { "id": "lead_8842", "email": "dana@example.com" } ], "nextCursor": null } } } } }, "404": { "description": "No such execution, or that step produced no stored output — a step that never ran has nothing to return." } }, "summary": "Get a step’s output", "tags": [ "Executions" ] } }, "/execution-traces/{id}/trace-data": { "get": { "description": "The run’s stored summary blob as a JSON attachment: `success`, `metadata`, `metrics`, and an `output` holding the initial input, the run’s variables and its errors. Step outputs are NOT included and large variables are sampled — use the full trace download when you need every step.", "operationId": "ExecutionTraceController.getTraceData", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "showSecrets", "required": false, "in": "query", "description": "Set to `true` to return credential values unmasked. Requires the `secrets:view` permission; without it the trace comes back masked rather than refused.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The summary blob, as a JSON file attachment.", "content": { "application/json": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "No such execution, or it has no stored trace." } }, "summary": "Download the trace summary", "tags": [ "Executions" ] } }, "/execution-traces/{id}/trace-download": { "get": { "description": "The complete run as one JSON attachment: `success`, `metadata`, `metrics`, and an `output` object holding the initial input, the run’s variables and errors, and every step’s full output including nested ones. Streamed, and bounded — a pathologically large step degrades to its `$meta` stub rather than failing the download.", "operationId": "ExecutionTraceController.downloadFullTrace", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "showSecrets", "required": false, "in": "query", "description": "Set to `true` to return credential values unmasked. Requires the `secrets:view` permission; without it the trace comes back masked rather than refused.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The trace, as a JSON file attachment named after the workflow and its start time.", "content": { "application/json": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "No such execution, or it has no stored trace — a run rejected before it started never writes one." } }, "summary": "Download the full trace", "tags": [ "Executions" ] } }, "/knowledge-bases": { "get": { "description": "Knowledge bases in the caller’s organization. Documents are not included: fetch them per knowledge base with `GET /knowledge-bases/{id}/documents`.", "operationId": "KnowledgeBaseController.list", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseListResponseDto" }, "example": { "total": 1, "data": [ { "id": "9c2f4b0e-1d77-4a3f-b6c8-3e51a9d02f14", "suid": "p8t2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Support Playbooks", "description": "Refund policy, escalation paths and tier-2 runbooks.", "embeddingModel": "text-embedding-3-small", "metadata": {}, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } ] } } } } }, "summary": "List knowledge bases", "tags": [ "Knowledge Bases" ] }, "post": { "description": "Creates an empty collection. Add documents to it with `POST /knowledge-bases/{id}/documents` (file upload) or `POST /knowledge-bases/{id}/documents/url`. Requires the `workflows:admin` permission.", "operationId": "KnowledgeBaseController.create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKnowledgeBaseDto" }, "examples": { "minimal": { "summary": "Name only", "value": { "name": "Support Playbooks" } }, "described": { "summary": "With a description", "value": { "name": "Support Playbooks", "description": "Refund policy, escalation paths and tier-2 runbooks." } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseResponseDto" }, "example": { "id": "9c2f4b0e-1d77-4a3f-b6c8-3e51a9d02f14", "suid": "p8t2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Support Playbooks", "description": "Refund policy, escalation paths and tier-2 runbooks.", "embeddingModel": "text-embedding-3-small", "metadata": {}, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } } } }, "403": { "description": "Caller lacks the `workflows:admin` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseErrorResponseDto" } } } } }, "summary": "Create a knowledge base", "tags": [ "Knowledge Bases" ] } }, "/knowledge-bases/{id}": { "delete": { "description": "Permanently removes the collection along with every document and embedded chunk in it, and releases the documents against the organization’s quota. Returns the deleted record. Requires the `workflows:admin` permission.", "operationId": "KnowledgeBaseController.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseResponseDto" }, "example": { "id": "9c2f4b0e-1d77-4a3f-b6c8-3e51a9d02f14", "suid": "p8t2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Support Playbooks", "description": "Refund policy, escalation paths and tier-2 runbooks.", "embeddingModel": "text-embedding-3-small", "metadata": {}, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } } } }, "403": { "description": "Caller lacks the `workflows:admin` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseErrorResponseDto" } } } }, "404": { "description": "No such knowledge base, or it belongs to another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseErrorResponseDto" } } } } }, "summary": "Delete a knowledge base", "tags": [ "Knowledge Bases" ] }, "get": { "operationId": "KnowledgeBaseController.get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseResponseDto" }, "example": { "id": "9c2f4b0e-1d77-4a3f-b6c8-3e51a9d02f14", "suid": "p8t2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Support Playbooks", "description": "Refund policy, escalation paths and tier-2 runbooks.", "embeddingModel": "text-embedding-3-small", "metadata": {}, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } } } }, "404": { "description": "No such knowledge base, or it belongs to another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseErrorResponseDto" } } } } }, "summary": "Get a knowledge base", "tags": [ "Knowledge Bases" ] }, "patch": { "description": "Renames or re-describes the collection. `embeddingModel` is not updatable: changing it would leave the stored chunks embedded with a model the query side no longer uses. Requires the `workflows:admin` permission.", "operationId": "KnowledgeBaseController.update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateKnowledgeBaseDto" }, "examples": { "rename": { "summary": "Rename", "value": { "name": "Tier-2 Playbooks" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseResponseDto" }, "example": { "id": "9c2f4b0e-1d77-4a3f-b6c8-3e51a9d02f14", "suid": "p8t2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Tier-2 Playbooks", "description": "Refund policy, escalation paths and tier-2 runbooks.", "embeddingModel": "text-embedding-3-small", "metadata": {}, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } } } }, "403": { "description": "Caller lacks the `workflows:admin` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseErrorResponseDto" } } } }, "404": { "description": "No such knowledge base, or it belongs to another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseErrorResponseDto" } } } } }, "summary": "Update a knowledge base", "tags": [ "Knowledge Bases" ] } }, "/knowledge-bases/{id}/documents": { "get": { "description": "Every document in the collection, newest first. Not paged and not filtered — there is no `{ total, data }` envelope. This is also the endpoint to poll while a document is ingesting.", "operationId": "KnowledgeBaseController.listDocuments", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeBaseDocumentResponseDto" } }, "example": [ { "id": "c04e7a51-9b6d-4e28-8f13-25ad6c9b7e40", "suid": "w6r1", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "knowledgeBase": "9c2f4b0e-1d77-4a3f-b6c8-3e51a9d02f14", "name": "https://docs.example.com/support/escalation", "mimeType": "text/html", "fileSize": "0", "sourceType": "url", "sourceUrl": "https://docs.example.com/support/escalation", "storagePath": "", "status": "ready", "chunkCount": 12, "metadata": {}, "createdAt": "2026-07-27T16:18:44.028Z", "updatedAt": "2026-07-27T16:19:02.551Z" }, { "id": "6b1d8f33-42ac-4f0d-9a5e-7c02b8e14d90", "suid": "m3q7", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "knowledgeBase": "9c2f4b0e-1d77-4a3f-b6c8-3e51a9d02f14", "name": "refund-policy.pdf", "mimeType": "application/pdf", "fileSize": "184320", "sourceType": "file", "storagePath": "gs://example-managed-bucket/orgs/3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471/knowledge-bases/9c2f4b0e-1d77-4a3f-b6c8-3e51a9d02f14/6b1d8f33-42ac-4f0d-9a5e-7c02b8e14d90/refund-policy.pdf", "status": "pending", "chunkCount": 0, "metadata": {}, "createdAt": "2026-07-27T16:12:03.117Z", "updatedAt": "2026-07-27T16:12:03.964Z" } ] } } }, "404": { "description": "No such knowledge base, or it belongs to another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseErrorResponseDto" } } } } }, "summary": "List documents in a knowledge base", "tags": [ "Knowledge Bases" ] }, "post": { "description": "Stores the file and queues it for parsing and embedding. PDF, DOCX, plain text, Markdown, CSV and HTML are parsed natively; other types are read as UTF-8 text. Uploading a file whose name already exists in the collection replaces that document instead of adding a second one, and a replacement does not consume additional document quota. Ingestion is asynchronous: the response is the queued record, always `status: \"pending\"` with `chunkCount: 0`. Poll `GET /knowledge-bases/{id}/documents` until the document reports `ready` (searchable) or `failed` (`errorMessage` says why). Requires the `workflows:admin` permission.", "operationId": "KnowledgeBaseController.uploadDocument", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "The document. Capped at 52428800 bytes." } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseDocumentResponseDto" }, "example": { "id": "6b1d8f33-42ac-4f0d-9a5e-7c02b8e14d90", "suid": "m3q7", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "knowledgeBase": "9c2f4b0e-1d77-4a3f-b6c8-3e51a9d02f14", "name": "refund-policy.pdf", "mimeType": "application/pdf", "fileSize": "184320", "sourceType": "file", "storagePath": "gs://example-managed-bucket/orgs/3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471/knowledge-bases/9c2f4b0e-1d77-4a3f-b6c8-3e51a9d02f14/6b1d8f33-42ac-4f0d-9a5e-7c02b8e14d90/refund-policy.pdf", "status": "pending", "chunkCount": 0, "metadata": {}, "createdAt": "2026-07-27T16:12:03.117Z", "updatedAt": "2026-07-27T16:12:03.964Z" } } } }, "400": { "description": "The organization is at its knowledge-base document limit for its plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseErrorResponseDto" } } } }, "403": { "description": "Caller lacks the `workflows:admin` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseErrorResponseDto" } } } }, "404": { "description": "No such knowledge base, or the request carried no `file` part.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseErrorResponseDto" } } } }, "413": { "description": "File exceeds the 52428800-byte upload limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseErrorResponseDto" } } } } }, "summary": "Upload a document", "tags": [ "Knowledge Bases" ] } }, "/knowledge-bases/{id}/documents/url": { "post": { "description": "Creates one document per URL and queues each for fetching and embedding. Up to 50 URLs per request. Every URL is validated before anything is created, so an unreachable or non-public address rejects the whole request. A URL already in the collection replaces its existing document. Ingestion is asynchronous: the response is the queued record, always `status: \"pending\"` with `chunkCount: 0`. Poll `GET /knowledge-bases/{id}/documents` until the document reports `ready` (searchable) or `failed` (`errorMessage` says why). Requires the `workflows:admin` permission.", "operationId": "KnowledgeBaseController.addUrlDocuments", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "urls" ], "properties": { "urls": { "type": "array", "maxItems": 50, "items": { "type": "string", "format": "uri" } } } }, "examples": { "single": { "summary": "One page", "value": { "urls": [ "https://docs.example.com/support/escalation" ] } }, "several": { "summary": "Several pages", "value": { "urls": [ "https://docs.example.com/support/escalation", "https://docs.example.com/support/refunds" ] } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeBaseDocumentResponseDto" } }, "example": [ { "id": "c04e7a51-9b6d-4e28-8f13-25ad6c9b7e40", "suid": "w6r1", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "knowledgeBase": "9c2f4b0e-1d77-4a3f-b6c8-3e51a9d02f14", "name": "https://docs.example.com/support/escalation", "mimeType": "text/html", "fileSize": "0", "sourceType": "url", "sourceUrl": "https://docs.example.com/support/escalation", "storagePath": "", "status": "pending", "chunkCount": 0, "metadata": {}, "createdAt": "2026-07-27T16:18:44.028Z", "updatedAt": "2026-07-27T16:18:44.028Z" } ] } } }, "400": { "description": "Empty list, more than 50 URLs, a URL that does not resolve to a public address, or the organization is at its document limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseErrorResponseDto" } } } }, "403": { "description": "Caller lacks the `workflows:admin` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseErrorResponseDto" } } } }, "404": { "description": "No such knowledge base, or it belongs to another organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseErrorResponseDto" } } } } }, "summary": "Add documents from URLs", "tags": [ "Knowledge Bases" ] } }, "/knowledge-bases/{id}/documents/{documentId}": { "delete": { "description": "Removes the document and its embedded chunks, releases it against the organization’s document quota, and deletes the stored original. Returns an acknowledgement rather than the deleted record. Requires the `workflows:admin` permission.", "operationId": "KnowledgeBaseController.removeDocument", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "documentId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseDocumentDeletedResponseDto" }, "example": { "deleted": true } } } }, "403": { "description": "Caller lacks the `workflows:admin` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseErrorResponseDto" } } } }, "404": { "description": "No such knowledge base, or no such document within it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseErrorResponseDto" } } } } }, "summary": "Delete a document", "tags": [ "Knowledge Bases" ] } }, "/knowledge-bases/{id}/documents/{documentId}/resync": { "post": { "description": "Re-fetches the source URL and re-embeds it. Only `url` documents can be resynced — an uploaded file has no source to re-read. The existing chunks stay searchable until the new ones are stored, so a failed resync does not empty the document. Ingestion is asynchronous: the response is the queued record, always `status: \"pending\"` with `chunkCount: 0`. Poll `GET /knowledge-bases/{id}/documents` until the document reports `ready` (searchable) or `failed` (`errorMessage` says why). Requires the `workflows:admin` permission.", "operationId": "KnowledgeBaseController.resyncDocument", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "documentId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "The document reset to `pending`, with any previous `errorMessage` cleared.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseDocumentResponseDto" }, "example": { "id": "c04e7a51-9b6d-4e28-8f13-25ad6c9b7e40", "suid": "w6r1", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "knowledgeBase": "9c2f4b0e-1d77-4a3f-b6c8-3e51a9d02f14", "name": "https://docs.example.com/support/escalation", "mimeType": "text/html", "fileSize": "0", "sourceType": "url", "sourceUrl": "https://docs.example.com/support/escalation", "storagePath": "", "status": "pending", "chunkCount": 0, "metadata": {}, "createdAt": "2026-07-27T16:18:44.028Z", "updatedAt": "2026-07-27T16:18:44.028Z" } } } }, "403": { "description": "Caller lacks the `workflows:admin` permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseErrorResponseDto" } } } }, "404": { "description": "No such knowledge base, or no such document within it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseErrorResponseDto" } } } }, "500": { "description": "The document is an uploaded file, not a URL document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeBaseErrorResponseDto" } } } } }, "summary": "Resync a URL document", "tags": [ "Knowledge Bases" ] } }, "/logs/reveal": { "post": { "description": "Un-masks a SINGLE field of a SINGLE log row and returns it in plaintext. Requires `logs:view-sensitive`, which is separate from the permission that let the caller see the row at all: the masked view is the default for everyone, including owners, until an explicit reveal.\n\nEvery successful reveal writes a `logs.sensitive.reveal` audit event recording who revealed which path of which row — never the value itself. A denied attempt writes nothing.\n\n`path` must be one of the row’s `redactedPaths` as returned by `POST /logs/search`; anything else is rejected, so this cannot be used to pull an arbitrary field out of a payload. `timestamp` is the row’s own timestamp and is what keeps the single-row lookup bounded.", "operationId": "LogsController.reveal", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogsRevealDto" }, "examples": { "revealHeader": { "summary": "Reveal a masked request header", "value": { "rowId": "b3f1c0a94d27e5f8", "path": "headers.authorization", "timestamp": "2026-07-27T16:04:11.482Z" } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogRevealResponseDto" }, "example": { "value": "", "source": "workflow", "auditContext": { "timestamp": "2026-07-27T16:04:11.482Z", "level": "error", "channel": "step", "origin": "engine", "workflowId": "7d1b6c0e-2a49-4f83-b5d6-9e0c3a1f7b24", "executionId": "e1a4f7c2-3b08-4d95-8f61-0c7a2e5d9b13", "stepId": "fetch_accounts", "connectionId": "9c2f4d51-8b7a-4e0c-9d13-2a5f6b8c1e04", "triggerId": "", "eventId": "" } } } } }, "400": { "description": "The path is not a value that was masked on this entry, so there is nothing to reveal." }, "403": { "description": "Caller lacks `logs:view-sensitive`, is not a member of the active organization, or is a platform admin viewing as another organization (reveal is refused outright in that mode so the audit trail always names the real acting user against their own org)." }, "404": { "description": "No row matches that id and timestamp within the sources the caller can read." } }, "summary": "Reveal one redacted log value", "tags": [ "Logs" ] } }, "/logs/search": { "post": { "description": "Searches the unified log surface for the active organization. A POST because the query is structured, not because it writes anything.\n\nWhat comes back is scoped two ways. By organization, always. And by `source`: each source maps to a permission (`workflow` and `trigger` to `executions:view`; `connection`, `event-receiver` and `integration-sync` to `secrets:view`; `audit` to `members:manage`), and the filter is applied server-side, so a source the caller cannot read is invisible rather than forbidden. Asking for one of those sources explicitly simply returns nothing from it.\n\nSensitive values are masked for everyone by default; `redactedPaths` on each row names what was masked, and `POST /logs/reveal` un-masks a single field for a caller holding `logs:view-sensitive`.\n\nThe window defaults to a recent lookback when `from`/`to` are omitted. `limit` defaults to 200 and caps at 1000; page backwards by resending the oldest `timestamp` you received as `before` while `hasMore` is true.", "operationId": "LogsController.search", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogsSearchDto" }, "examples": { "recentErrors": { "summary": "Recent workflow errors", "value": { "sources": [ "workflow" ], "level": [ "error" ], "limit": 50 } }, "oneExecution": { "summary": "Everything from one execution", "value": { "executionId": "e1a4f7c2-3b08-4d95-8f61-0c7a2e5d9b13" } }, "payloadPredicate": { "summary": "Match a field inside the payload", "value": { "from": "2026-07-27T00:00:00Z", "to": "2026-07-28T00:00:00Z", "dataFilters": [ { "path": [ "status" ], "operator": "gte", "value": "500" }, { "path": [ "headers", "x-request-id" ], "value": "req_9f21" } ] } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogsSearchResponseDto" }, "example": { "entries": [ { "id": "b3f1c0a94d27e5f8", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "source": "workflow", "channel": "step", "level": "error", "origin": "engine", "timestamp": "2026-07-27T16:04:11.482Z", "message": "HTTP request failed with status 502", "workflowId": "7d1b6c0e-2a49-4f83-b5d6-9e0c3a1f7b24", "workflowName": "Nightly CRM sync", "executionId": "e1a4f7c2-3b08-4d95-8f61-0c7a2e5d9b13", "stepId": "fetch_accounts", "connectionId": "9c2f4d51-8b7a-4e0c-9d13-2a5f6b8c1e04", "connectionName": "billing-api", "triggerId": "", "instanceId": "", "provider": "", "eventId": "", "actorUserId": "", "actorType": "", "action": "", "resourceType": "", "resourceId": "", "sensitivity": "", "data": { "status": 502, "url": "https://api.example.com/v2/accounts", "headers": { "authorization": "[REDACTED]" } }, "tags": [ "crm", "nightly" ], "redactedPaths": [ "headers.authorization" ] } ], "hasMore": false, "facets": { "source": [ { "value": "workflow", "count": 1 } ], "level": [ { "value": "error", "count": 1 } ], "channel": [ { "value": "step", "count": 1 } ], "provider": [], "origin": [ { "value": "engine", "count": 1 } ], "tags": [ { "value": "crm", "count": 1 }, { "value": "nightly", "count": 1 } ] }, "histogram": [ { "ts": "2026-07-27T16:00:00.000Z", "counts": { "debug": 0, "info": 0, "warn": 0, "error": 1 } } ] } } } } }, "summary": "Search logs", "tags": [ "Logs" ] } }, "/organizations": { "get": { "description": "Organizations the caller belongs to. A personal access token is scoped to a single organization, so it always sees exactly one.", "operationId": "OrganizationController.list", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationListResponseDto" }, "example": { "total": 1, "data": [ { "id": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "suid": "k4v9", "name": "Acme Contact Center", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "metadata": { "industry": "contact-center" }, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } ] } } } } }, "summary": "List organizations", "tags": [ "Organizations" ] }, "post": { "description": "Creates a standalone organization owned by the caller and assigns it the free plan. It pays for itself: whoever owns it picks a plan and enters payment details from the app. `name` and `metadata` are the only fields accepted here; plan, ownership and billing are not settable at creation.\n\nPartners creating an organization they will pay for should use `POST /partner/managed-orgs` instead. That endpoint takes a `planSlug` and bills the new org to the partner org, consolidated onto one invoice. An organization created here can never be converted into a child afterwards through the API.\n\nThe token used to create it stays scoped to its original organization: mint a new token to operate on the one you just created.", "operationId": "OrganizationController.create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationBodyDto" }, "examples": { "minimal": { "summary": "Name only", "value": { "name": "Acme Contact Center" } }, "withMetadata": { "summary": "With your own metadata", "value": { "name": "Acme Contact Center", "metadata": { "industry": "contact-center", "accountManager": "jordan" } } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponseDto" }, "example": { "id": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "suid": "k4v9", "name": "Acme Contact Center", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "metadata": { "industry": "contact-center" }, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } } } } }, "summary": "Create an organization", "tags": [ "Organizations" ] } }, "/organizations/{id}": { "get": { "operationId": "OrganizationController.get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponseDto" }, "example": { "id": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "suid": "k4v9", "name": "Acme Contact Center", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "metadata": { "industry": "contact-center" }, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } } } }, "404": { "description": "No such organization, or the caller is not a member." } }, "summary": "Get an organization", "tags": [ "Organizations" ] }, "patch": { "description": "Requires the `org:owner` permission on the target organization.", "operationId": "OrganizationController.update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationBodyDto" }, "examples": { "rename": { "summary": "Rename", "value": { "name": "Acme CX" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponseDto" }, "example": { "id": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "suid": "k4v9", "name": "Acme CX", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "metadata": { "industry": "contact-center" }, "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } } } }, "403": { "description": "Caller is not an owner of this organization." } }, "summary": "Update an organization", "tags": [ "Organizations" ] } }, "/package-installs": { "get": { "description": "Packages installed into the organization this request is scoped to. The packages and versions the rows point at come back alongside them, so a list view needs no follow-up requests. Rows with `parentPackageInstallId` set were pulled in as a dependency of another install rather than chosen directly.", "operationId": "PackageInstallsController.listInstalls", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageInstallListResponseDto" }, "example": { "total": 1, "data": [ { "id": "2a6e91f3-7c04-4bb5-83d2-9f10c5e78a46", "suid": "i9ck", "organizationId": "5c0a97e4-1b62-4d39-8f7a-3e5b21c60d84", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "packageId": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "packageVersionId": "c4d81e07-2b93-4a6f-9d15-7e0b83af5c62", "installedAt": "2026-07-20T16:45:02.881Z", "installedByUserId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "installedResources": [ { "kind": "workflow", "id": "e83b5f20-9d47-4a16-b2c8-6017fa39d5be", "name": "onboard-agent", "didCreate": true }, { "kind": "sub-workflow", "id": "4fc7a018-6b93-42de-85a1-7c02e9b34d67", "name": "assign-skills", "didCreate": true }, { "kind": "trigger", "id": "b1470ce9-3a28-4d75-90ef-58c2d6b3419a", "name": "nightly-roster-sync", "didCreate": true }, { "kind": "connection-shape", "id": "0d7c4b81-52ae-4f39-9c60-8b13e7a2f405", "name": "five9-admin", "didCreate": false } ], "setupChecklist": [ { "id": "7e2c0a94-1d38-4b6f-902a-5cb741e83d20", "kind": "authenticate-connection", "label": "Authenticate the five9-admin connection", "relatedResourceId": "0d7c4b81-52ae-4f39-9c60-8b13e7a2f405", "completedAt": "2026-07-20T16:52:41.309Z" } ], "createdEnvs": [], "aliases": [ { "kind": "connection", "source": { "name": "five9-admin" }, "target": { "connectionId": "0d7c4b81-52ae-4f39-9c60-8b13e7a2f405" } } ], "extensionPointBindings": {}, "createdAt": "2026-07-20T16:45:02.881Z", "updatedAt": "2026-07-20T16:52:41.309Z" } ], "packages": [ { "id": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "suid": "p3wq", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "slug": "@k4v9/agent-onboarding", "name": "Agent Onboarding", "description": "Provisions a new contact-center agent: creates the profile, assigns skills, and files the welcome ticket.", "supportContactEmail": "support@acme.example", "documentationUrl": "https://docs.acme.example/agent-onboarding", "websiteUrl": "https://acme.example", "icon": "https://cdn.quickflo.app/packages/9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845/icon-4f1c9ab2e037.png", "readme": "# Agent Onboarding\n\nRun this once per new hire. See the setup checklist after installing.", "tags": [ "contact-center", "onboarding" ], "visibility": "public", "latestVersionId": "c4d81e07-2b93-4a6f-9d15-7e0b83af5c62", "installCount": 12, "isVerified": true, "hasAgentTools": false, "resourceCounts": { "workflows": 2, "subWorkflows": 1, "triggers": 1, "dashboards": 1 }, "createdAt": "2026-05-04T14:22:08.117Z", "updatedAt": "2026-07-19T09:31:44.902Z" } ], "versions": [ { "id": "c4d81e07-2b93-4a6f-9d15-7e0b83af5c62", "suid": "v7hn", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "packageId": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "version": "1.4.0", "manifest": { "schemaVersion": 1, "slug": "@k4v9/agent-onboarding", "version": "1.4.0", "name": "Agent Onboarding", "description": "Provisions a new contact-center agent.", "tags": [ "contact-center", "onboarding" ], "packageId": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "authorOrganizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "authorOrgSuid": "k4v9", "resources": [ { "kind": "workflow", "name": "onboard-agent", "isRoot": true }, { "kind": "sub-workflow", "name": "assign-skills" }, { "kind": "trigger", "name": "nightly-roster-sync", "triggerType": "schedule", "scheduleCron": "0 3 * * *" }, { "kind": "dashboard", "name": "onboarding-health" } ], "peerDeps": { "connections": [ { "name": "five9-admin", "type": "five9", "description": "Admin credentials used to create the agent profile." } ], "env": { "required": [ { "kind": "shared", "key": "AGENT_DEFAULT_SKILL_GROUP", "default": "inbound-sales" } ], "optional": [] }, "dataStoreTables": [ { "name": "agent_roster", "description": "Source of truth for the nightly sync." } ] }, "extensionPoints": [] }, "artifactUrl": "gs://quickflo-package-artifacts/packages/9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845/1.4.0/agent-onboarding.qfpkg", "artifactDigest": "7d0f3a1c9b48e25f6a0d7c31be94f28d5a637c0e18b4d92f5c73a0e6b184df29", "summary": "Add the nightly roster sync trigger", "releaseNotes": "## 1.4.0\n\n- Nightly roster sync keeps the agent list current.\n- Welcome ticket now includes the assigned skill group.", "publishedAt": "2026-07-19T09:31:44.902Z", "publishedByUserId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "createdAt": "2026-07-19T09:31:44.902Z", "updatedAt": "2026-07-19T09:31:44.902Z" } ] } } } } }, "summary": "List installed packages", "tags": [ "Packages" ] } }, "/package-installs/{id}": { "delete": { "description": "Deletes the workflows, triggers and dashboards the package created, along with any packages installed as its dependencies, and removes the install record. Deliberately incomplete: environment variables, connections and data stores stay, because the data in them is yours and outlives the package. The counts in the response cover only what was deleted.", "operationId": "PackageInstallsController.uninstall", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UninstallResponseDto" }, "example": { "deleted": { "workflows": 2, "triggers": 1, "dashboards": 1, "dashboardDataSources": 2 } } } } }, "404": { "description": "No such install in your organization." } }, "summary": "Uninstall a package", "tags": [ "Packages" ] }, "get": { "description": "The full record: what the install created, what setup is still outstanding, and what its slots are wired to.", "operationId": "PackageInstallsController.getInstall", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageInstallResponseDto" }, "example": { "id": "2a6e91f3-7c04-4bb5-83d2-9f10c5e78a46", "suid": "i9ck", "organizationId": "5c0a97e4-1b62-4d39-8f7a-3e5b21c60d84", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "packageId": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "packageVersionId": "c4d81e07-2b93-4a6f-9d15-7e0b83af5c62", "installedAt": "2026-07-20T16:45:02.881Z", "installedByUserId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "installedResources": [ { "kind": "workflow", "id": "e83b5f20-9d47-4a16-b2c8-6017fa39d5be", "name": "onboard-agent", "didCreate": true }, { "kind": "sub-workflow", "id": "4fc7a018-6b93-42de-85a1-7c02e9b34d67", "name": "assign-skills", "didCreate": true }, { "kind": "trigger", "id": "b1470ce9-3a28-4d75-90ef-58c2d6b3419a", "name": "nightly-roster-sync", "didCreate": true }, { "kind": "connection-shape", "id": "0d7c4b81-52ae-4f39-9c60-8b13e7a2f405", "name": "five9-admin", "didCreate": false } ], "setupChecklist": [ { "id": "7e2c0a94-1d38-4b6f-902a-5cb741e83d20", "kind": "authenticate-connection", "label": "Authenticate the five9-admin connection", "relatedResourceId": "0d7c4b81-52ae-4f39-9c60-8b13e7a2f405", "completedAt": "2026-07-20T16:52:41.309Z" } ], "createdEnvs": [], "aliases": [ { "kind": "connection", "source": { "name": "five9-admin" }, "target": { "connectionId": "0d7c4b81-52ae-4f39-9c60-8b13e7a2f405" } } ], "extensionPointBindings": {}, "createdAt": "2026-07-20T16:45:02.881Z", "updatedAt": "2026-07-20T16:52:41.309Z" } } } }, "404": { "description": "No such install in your organization." } }, "summary": "Get an installed package", "tags": [ "Packages" ] } }, "/package-installs/{id}/refresh-checklist": { "post": { "description": "Looks at every outstanding \"set this environment variable\" item and marks the ones whose value has since been filled in. Safe to call repeatedly and it never un-completes anything, but it can write, which is why it is a POST rather than folded into the GET.", "operationId": "PackageInstallsController.refreshChecklist", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageInstallResponseDto" }, "example": { "id": "2a6e91f3-7c04-4bb5-83d2-9f10c5e78a46", "suid": "i9ck", "organizationId": "5c0a97e4-1b62-4d39-8f7a-3e5b21c60d84", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "packageId": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "packageVersionId": "c4d81e07-2b93-4a6f-9d15-7e0b83af5c62", "installedAt": "2026-07-20T16:45:02.881Z", "installedByUserId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "installedResources": [ { "kind": "workflow", "id": "e83b5f20-9d47-4a16-b2c8-6017fa39d5be", "name": "onboard-agent", "didCreate": true }, { "kind": "sub-workflow", "id": "4fc7a018-6b93-42de-85a1-7c02e9b34d67", "name": "assign-skills", "didCreate": true }, { "kind": "trigger", "id": "b1470ce9-3a28-4d75-90ef-58c2d6b3419a", "name": "nightly-roster-sync", "didCreate": true }, { "kind": "connection-shape", "id": "0d7c4b81-52ae-4f39-9c60-8b13e7a2f405", "name": "five9-admin", "didCreate": false } ], "setupChecklist": [ { "id": "7e2c0a94-1d38-4b6f-902a-5cb741e83d20", "kind": "authenticate-connection", "label": "Authenticate the five9-admin connection", "relatedResourceId": "0d7c4b81-52ae-4f39-9c60-8b13e7a2f405", "completedAt": "2026-07-20T16:52:41.309Z" } ], "createdEnvs": [], "aliases": [ { "kind": "connection", "source": { "name": "five9-admin" }, "target": { "connectionId": "0d7c4b81-52ae-4f39-9c60-8b13e7a2f405" } } ], "extensionPointBindings": {}, "createdAt": "2026-07-20T16:45:02.881Z", "updatedAt": "2026-07-20T16:52:41.309Z" } } } }, "404": { "description": "No such install in your organization." } }, "summary": "Re-check the setup checklist", "tags": [ "Packages" ] } }, "/package-installs/{id}/reinstall": { "post": { "description": "This one writes, and it overwrites. Package-owned workflows and dashboards are replaced in place, so any edits you made to them are lost: `POST /package-installs/{id}/reinstall/preview` lists exactly which ones first. Resources the new version dropped are deleted. Existing webhook URLs and secrets are preserved so callers keep working, and new triggers get fresh ones. The install keeps its id. `decisions` must carry the complete set of choices for the new version, not just the changes.", "operationId": "PackageInstallsController.commitReinstall", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReinstallCommitRequestDto" }, "examples": { "keepBindings": { "summary": "Upgrade, keeping the current wiring", "value": { "incomingPackageVersionId": "d15a92f8-6e30-4c47-b8a1-04f7c2e6910b", "decisions": { "aliases": [ { "kind": "connection", "source": { "name": "five9-admin" }, "target": { "connectionId": "0d7c4b81-52ae-4f39-9c60-8b13e7a2f405" } } ], "workflowAttachedEnvs": { "onboard-agent": { "environmentId": "f16d84b0-97c2-4e53-a08b-3d5169ce7241" } }, "sharedEnvValuesToCreate": {} } } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReinstallCommitResponseDto" }, "example": { "packageInstallId": "2a6e91f3-7c04-4bb5-83d2-9f10c5e78a46", "fromVersion": "1.4.0", "toVersion": "1.5.0", "resourceChanges": { "added": 1, "replaced": 2, "removed": 0 }, "installedResources": [ { "kind": "workflow", "id": "e83b5f20-9d47-4a16-b2c8-6017fa39d5be", "name": "onboard-agent", "didCreate": true }, { "kind": "sub-workflow", "id": "4fc7a018-6b93-42de-85a1-7c02e9b34d67", "name": "assign-skills", "didCreate": true }, { "kind": "trigger", "id": "b1470ce9-3a28-4d75-90ef-58c2d6b3419a", "name": "nightly-roster-sync", "didCreate": true }, { "kind": "connection-shape", "id": "0d7c4b81-52ae-4f39-9c60-8b13e7a2f405", "name": "five9-admin", "didCreate": false } ], "setupChecklist": [] } } } }, "404": { "description": "No such install in your organization, or no such target version." } }, "summary": "Reinstall onto another version", "tags": [ "Packages" ] } }, "/package-installs/{id}/reinstall/preview": { "post": { "description": "Dry run. Nothing is changed, so this is safe to call as often as you like. Shows what moving this install to another version would add, overwrite and remove, which of your earlier choices still apply, and which package-owned resources you have edited since installing (reinstall overwrites those). Any version can be named, including the one already installed. Apply it with `POST /package-installs/{id}/reinstall`.", "operationId": "PackageInstallsController.previewReinstall", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReinstallPreviewRequestDto" }, "examples": { "upgrade": { "summary": "Move to a newer version", "value": { "incomingPackageVersionId": "d15a92f8-6e30-4c47-b8a1-04f7c2e6910b" } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReinstallPreviewResponseDto" }, "example": { "packageSummary": { "slug": "@k4v9/agent-onboarding", "name": "Agent Onboarding", "version": "1.5.0", "summary": "Add the nightly roster sync trigger", "description": "Provisions a new contact-center agent.", "tags": [ "contact-center", "onboarding" ], "readme": "# Agent Onboarding\n\nRun this once per new hire. See the setup checklist after installing.", "releaseNotes": "## 1.4.0\n\n- Nightly roster sync keeps the agent list current.", "packageId": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "authorOrganizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "isVerified": true, "supportContactEmail": "support@acme.example", "documentationUrl": "https://docs.acme.example/agent-onboarding" }, "fromVersion": "1.4.0", "toVersion": "1.5.0", "diff": { "resourceChanges": [ { "kind": "workflow", "name": "onboard-agent", "change": "replaced" }, { "kind": "workflow", "name": "offboard-agent", "change": "added" }, { "kind": "sub-workflow", "name": "assign-skills", "change": "replaced" } ], "newPeerDeps": { "connections": [], "sharedEnvs": [ { "kind": "shared", "key": "OFFBOARD_APPROVER_EMAIL" } ], "flatEnvs": [], "dataStoreTables": [], "extensionPoints": [] }, "sharedDefaultChanges": [], "editedResourceWarnings": [ { "kind": "workflow", "name": "onboard-agent", "resourceId": "e83b5f20-9d47-4a16-b2c8-6017fa39d5be", "lastEditedAt": "2026-07-24T10:12:55.480Z" } ], "aliasReplay": { "applicable": [ { "kind": "connection", "source": { "name": "five9-admin" }, "target": { "connectionId": "0d7c4b81-52ae-4f39-9c60-8b13e7a2f405" } } ], "invalidated": [] }, "extensionPointBindingChanges": [] }, "resources": [ { "kind": "workflow", "name": "onboard-agent", "isRoot": true }, { "kind": "workflow", "name": "offboard-agent", "isRoot": true }, { "kind": "sub-workflow", "name": "assign-skills" } ], "peerDepDecisions": [ { "kind": "connection", "peerDep": { "name": "five9-admin", "type": "five9" }, "existingMatch": { "id": "0d7c4b81-52ae-4f39-9c60-8b13e7a2f405", "name": "five9-admin", "type": "five9" } } ], "sharedEnvKeys": [ "FIVE9_DOMAIN", "SUPPORT_QUEUE" ], "currentBindings": { "aliases": [ { "kind": "connection", "source": { "name": "five9-admin" }, "target": { "connectionId": "0d7c4b81-52ae-4f39-9c60-8b13e7a2f405" } } ], "workflowAttachedEnvs": { "onboard-agent": { "environmentId": "f16d84b0-97c2-4e53-a08b-3d5169ce7241" } }, "triggerEnvironments": { "nightly-roster-sync": { "environmentId": "f16d84b0-97c2-4e53-a08b-3d5169ce7241" } } } } } } }, "404": { "description": "No such install in your organization, or no such target version." } }, "summary": "Preview a reinstall", "tags": [ "Packages" ] } }, "/package-installs/{id}/todos/{todoId}/complete": { "post": { "description": "`todoId` is the `id` of an entry in the install’s `setupChecklist`. Completing an item that someone else already completed returns a 409 rather than quietly succeeding, so two people working the same list can tell what happened.", "operationId": "PackageInstallsController.completeChecklistItem", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "todoId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageInstallResponseDto" }, "example": { "id": "2a6e91f3-7c04-4bb5-83d2-9f10c5e78a46", "suid": "i9ck", "organizationId": "5c0a97e4-1b62-4d39-8f7a-3e5b21c60d84", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "packageId": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "packageVersionId": "c4d81e07-2b93-4a6f-9d15-7e0b83af5c62", "installedAt": "2026-07-20T16:45:02.881Z", "installedByUserId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "installedResources": [ { "kind": "workflow", "id": "e83b5f20-9d47-4a16-b2c8-6017fa39d5be", "name": "onboard-agent", "didCreate": true }, { "kind": "sub-workflow", "id": "4fc7a018-6b93-42de-85a1-7c02e9b34d67", "name": "assign-skills", "didCreate": true }, { "kind": "trigger", "id": "b1470ce9-3a28-4d75-90ef-58c2d6b3419a", "name": "nightly-roster-sync", "didCreate": true }, { "kind": "connection-shape", "id": "0d7c4b81-52ae-4f39-9c60-8b13e7a2f405", "name": "five9-admin", "didCreate": false } ], "setupChecklist": [ { "id": "7e2c0a94-1d38-4b6f-902a-5cb741e83d20", "kind": "authenticate-connection", "label": "Authenticate the five9-admin connection", "relatedResourceId": "0d7c4b81-52ae-4f39-9c60-8b13e7a2f405", "completedAt": "2026-07-20T16:52:41.309Z" } ], "createdEnvs": [], "aliases": [ { "kind": "connection", "source": { "name": "five9-admin" }, "target": { "connectionId": "0d7c4b81-52ae-4f39-9c60-8b13e7a2f405" } } ], "extensionPointBindings": {}, "createdAt": "2026-07-20T16:45:02.881Z", "updatedAt": "2026-07-20T16:52:41.309Z" } } } }, "404": { "description": "No such install in your organization, or no such checklist item." }, "409": { "description": "The item was already completed." } }, "summary": "Complete a setup checklist item", "tags": [ "Packages" ] } }, "/packages": { "get": { "description": "Packages your organization publishes. To search the public catalog instead, use `GET /packages/marketplace`. A cross-organization `where[organizationId]` filter is only accepted when paired with `where[visibility]=public`.", "operationId": "PackagesController.listPackages", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageListResponseDto" }, "example": { "total": 1, "data": [ { "id": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "suid": "p3wq", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "slug": "@k4v9/agent-onboarding", "name": "Agent Onboarding", "description": "Provisions a new contact-center agent: creates the profile, assigns skills, and files the welcome ticket.", "supportContactEmail": "support@acme.example", "documentationUrl": "https://docs.acme.example/agent-onboarding", "websiteUrl": "https://acme.example", "icon": "https://cdn.quickflo.app/packages/9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845/icon-4f1c9ab2e037.png", "readme": "# Agent Onboarding\n\nRun this once per new hire. See the setup checklist after installing.", "tags": [ "contact-center", "onboarding" ], "visibility": "public", "latestVersionId": "c4d81e07-2b93-4a6f-9d15-7e0b83af5c62", "installCount": 12, "isVerified": true, "hasAgentTools": false, "resourceCounts": { "workflows": 2, "subWorkflows": 1, "triggers": 1, "dashboards": 1 }, "createdAt": "2026-05-04T14:22:08.117Z", "updatedAt": "2026-07-19T09:31:44.902Z" } ] } } } }, "400": { "description": "Filtered on another organization without also filtering on public visibility." } }, "summary": "List packages", "tags": [ "Packages" ] }, "post": { "description": "Creates the package shell. Nothing is publishable until you publish a version into it with `POST /packages/{id}/versions`. Listing publicly requires a paid plan and the canonical `@/` slug; shareable install links require the Growth plan or higher. Private packages are available on every plan.", "operationId": "PackagesController.createPackage", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePackageDto" }, "examples": { "private": { "summary": "Private package", "value": { "slug": "agent-onboarding", "name": "Agent Onboarding", "description": "Provisions a new contact-center agent.", "visibility": "private" } }, "marketplace": { "summary": "Listed in the marketplace", "value": { "slug": "@k4v9/agent-onboarding", "name": "Agent Onboarding", "description": "Provisions a new contact-center agent.", "supportContactEmail": "support@acme.example", "tags": [ "contact-center", "onboarding" ], "visibility": "public" } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageResponseDto" }, "example": { "id": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "suid": "p3wq", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "slug": "@k4v9/agent-onboarding", "name": "Agent Onboarding", "description": "Provisions a new contact-center agent: creates the profile, assigns skills, and files the welcome ticket.", "supportContactEmail": "support@acme.example", "documentationUrl": "https://docs.acme.example/agent-onboarding", "websiteUrl": "https://acme.example", "icon": "https://cdn.quickflo.app/packages/9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845/icon-4f1c9ab2e037.png", "readme": "# Agent Onboarding\n\nRun this once per new hire. See the setup checklist after installing.", "tags": [ "contact-center", "onboarding" ], "visibility": "public", "latestVersionId": null, "installCount": 0, "isVerified": false, "hasAgentTools": false, "resourceCounts": {}, "createdAt": "2026-05-04T14:22:08.117Z", "updatedAt": "2026-07-19T09:31:44.902Z" } } } }, "400": { "description": "The plan does not allow this visibility, or a public package was given a slug that is not `@/`." } }, "summary": "Create a package", "tags": [ "Packages" ] } }, "/packages/install": { "post": { "description": "This one writes. Creates the workflows, triggers, dashboards and tables the package ships, into whichever organization the request is scoped to, and records an install you can later reinstall or uninstall. `decisions` carries your answers to the questions `POST /packages/install/preview` raised; send empty objects to take every default. The archive is fetched server-side, so nothing has to be uploaded.", "operationId": "PackagesInstallController.commitInstall", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallCommitRequestDto" }, "examples": { "defaults": { "summary": "Accept every default", "value": { "packageId": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "packageVersionId": "c4d81e07-2b93-4a6f-9d15-7e0b83af5c62", "decisions": { "aliases": [], "workflowAttachedEnvs": {}, "sharedEnvValuesToCreate": {} } } }, "mapped": { "summary": "Reuse an existing connection and set a shared value", "value": { "packageId": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "packageVersionId": "c4d81e07-2b93-4a6f-9d15-7e0b83af5c62", "decisions": { "aliases": [ { "kind": "connection", "source": { "name": "five9-admin" }, "target": { "connectionId": "0d7c4b81-52ae-4f39-9c60-8b13e7a2f405" } } ], "workflowAttachedEnvs": { "onboard-agent": { "environmentId": "f16d84b0-97c2-4e53-a08b-3d5169ce7241" } }, "sharedEnvValuesToCreate": { "AGENT_DEFAULT_SKILL_GROUP": "inbound-sales" } } } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallCommitResponseDto" }, "example": { "packageInstallId": "2a6e91f3-7c04-4bb5-83d2-9f10c5e78a46", "installedResources": [ { "kind": "workflow", "id": "e83b5f20-9d47-4a16-b2c8-6017fa39d5be", "name": "onboard-agent", "didCreate": true }, { "kind": "sub-workflow", "id": "4fc7a018-6b93-42de-85a1-7c02e9b34d67", "name": "assign-skills", "didCreate": true }, { "kind": "trigger", "id": "b1470ce9-3a28-4d75-90ef-58c2d6b3419a", "name": "nightly-roster-sync", "didCreate": true }, { "kind": "connection-shape", "id": "0d7c4b81-52ae-4f39-9c60-8b13e7a2f405", "name": "five9-admin", "didCreate": false } ], "setupChecklist": [ { "id": "7e2c0a94-1d38-4b6f-902a-5cb741e83d20", "kind": "authenticate-connection", "label": "Authenticate the five9-admin connection", "relatedResourceId": "0d7c4b81-52ae-4f39-9c60-8b13e7a2f405" } ] } } } }, "400": { "description": "The version has no archive on record, or the plan does not allow installing another organization’s non-public package through a link." }, "404": { "description": "No such package or version, or it is not visible to the caller." } }, "summary": "Install a package", "tags": [ "Packages" ] } }, "/packages/install/commit-from-artifact": { "post": { "description": "This one writes. Multipart upload with the `artifact` bytes plus `slug` and `version` text fields (copy them from the preview response) and an optional `decisions` field holding the same JSON object the link-based install takes. Holding the genuine file is itself the permission: the upload is checked against the published checksum, so this works on any plan even when the publisher is invisible to you. It is the deliberate escape hatch when share links are not available.", "operationId": "PackagesInstallController.commitInstallFromArtifact", "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "artifact", "slug", "version" ], "properties": { "artifact": { "type": "string", "format": "binary", "description": "The `.qfpkg` archive bytes." }, "slug": { "type": "string", "description": "Package slug from the preview response.", "example": "@k4v9/agent-onboarding" }, "version": { "type": "string", "description": "Version string from the preview response.", "example": "1.4.0" }, "decisions": { "type": "string", "description": "JSON-encoded install decisions. Omit to accept every default.", "example": "{\"aliases\":[],\"workflowAttachedEnvs\":{},\"sharedEnvValuesToCreate\":{}}" } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallCommitResponseDto" }, "example": { "packageInstallId": "2a6e91f3-7c04-4bb5-83d2-9f10c5e78a46", "installedResources": [ { "kind": "workflow", "id": "e83b5f20-9d47-4a16-b2c8-6017fa39d5be", "name": "onboard-agent", "didCreate": true }, { "kind": "sub-workflow", "id": "4fc7a018-6b93-42de-85a1-7c02e9b34d67", "name": "assign-skills", "didCreate": true }, { "kind": "trigger", "id": "b1470ce9-3a28-4d75-90ef-58c2d6b3419a", "name": "nightly-roster-sync", "didCreate": true }, { "kind": "connection-shape", "id": "0d7c4b81-52ae-4f39-9c60-8b13e7a2f405", "name": "five9-admin", "didCreate": false } ], "setupChecklist": [ { "id": "7e2c0a94-1d38-4b6f-902a-5cb741e83d20", "kind": "authenticate-connection", "label": "Authenticate the five9-admin connection", "relatedResourceId": "0d7c4b81-52ae-4f39-9c60-8b13e7a2f405" } ] } } } }, "400": { "description": "Missing file or fields, `decisions` was not valid JSON, or the uploaded file does not match the checksum published for that slug and version." }, "404": { "description": "The package or version is not visible to you and the uploaded file does not match any published archive." } }, "summary": "Install from an uploaded archive", "tags": [ "Packages" ] } }, "/packages/install/preview": { "post": { "description": "Dry run. Nothing is created and the organization is left untouched, so this is safe to call as often as you like. Returns what the package would create, every connection and environment variable you would have to supply, and what would still be waiting on the setup checklist afterwards. Pass `unlistedToken` when you arrived through a share link for a package you cannot otherwise see. Commit the install with `POST /packages/install`.", "operationId": "PackagesInstallController.previewInstall", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallPreviewRequestDto" }, "examples": { "registry": { "summary": "A package you can already see", "value": { "packageId": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "packageVersionId": "c4d81e07-2b93-4a6f-9d15-7e0b83af5c62" } }, "shareLink": { "summary": "Arrived through a share link", "value": { "packageId": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "packageVersionId": "c4d81e07-2b93-4a6f-9d15-7e0b83af5c62", "unlistedToken": "" } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallPreviewResponseDto" }, "example": { "packageSummary": { "slug": "@k4v9/agent-onboarding", "name": "Agent Onboarding", "version": "1.4.0", "summary": "Add the nightly roster sync trigger", "description": "Provisions a new contact-center agent.", "tags": [ "contact-center", "onboarding" ], "readme": "# Agent Onboarding\n\nRun this once per new hire. See the setup checklist after installing.", "releaseNotes": "## 1.4.0\n\n- Nightly roster sync keeps the agent list current.", "packageId": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "authorOrganizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "isVerified": true, "supportContactEmail": "support@acme.example", "documentationUrl": "https://docs.acme.example/agent-onboarding" }, "resources": [ { "kind": "workflow", "name": "onboard-agent", "isRoot": true }, { "kind": "sub-workflow", "name": "assign-skills" }, { "kind": "trigger", "name": "nightly-roster-sync", "triggerType": "schedule", "scheduleCron": "0 3 * * *" } ], "peerDepDecisions": [ { "kind": "connection", "peerDep": { "name": "five9-admin", "type": "five9", "description": "Admin credentials used to create the agent profile." }, "existingMatch": { "id": "0d7c4b81-52ae-4f39-9c60-8b13e7a2f405", "name": "five9-admin", "type": "five9" } }, { "kind": "env-shared", "peerDep": { "kind": "shared", "key": "AGENT_DEFAULT_SKILL_GROUP", "default": "inbound-sales" } }, { "kind": "data-store-table", "peerDep": { "name": "agent_roster", "description": "Source of truth for the nightly sync." } } ], "setupChecklistPreview": [ { "kind": "authenticate-connection", "label": "Authenticate the five9-admin connection", "relatedPeerDepKey": "connection:five9-admin" } ], "collisions": [], "sharedEnvKeys": [ "FIVE9_DOMAIN", "SUPPORT_QUEUE" ], "dependencies": [] } } } }, "400": { "description": "Installing another organization’s non-public package through a link or the registry requires the Growth plan or higher." }, "404": { "description": "No such package or version, or it is not visible to the caller." } }, "summary": "Preview an install", "tags": [ "Packages" ] } }, "/packages/install/preview-from-artifact": { "post": { "description": "Dry run for a `.qfpkg` you were handed directly, with no link and no marketplace listing. Nothing is created. Multipart upload with a single `artifact` field. Nothing is cached between this call and the commit: send the same file again to `POST /packages/install/commit-from-artifact`.", "operationId": "PackagesInstallController.previewInstallFromArtifact", "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "artifact" ], "properties": { "artifact": { "type": "string", "format": "binary", "description": "The `.qfpkg` archive bytes." } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallPreviewResponseDto" }, "example": { "packageSummary": { "slug": "@k4v9/agent-onboarding", "name": "Agent Onboarding", "version": "1.4.0", "summary": "Add the nightly roster sync trigger", "description": "Provisions a new contact-center agent.", "tags": [ "contact-center", "onboarding" ], "readme": "# Agent Onboarding\n\nRun this once per new hire. See the setup checklist after installing.", "releaseNotes": "## 1.4.0\n\n- Nightly roster sync keeps the agent list current.", "packageId": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "authorOrganizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "isVerified": true, "supportContactEmail": "support@acme.example", "documentationUrl": "https://docs.acme.example/agent-onboarding" }, "resources": [ { "kind": "workflow", "name": "onboard-agent", "isRoot": true }, { "kind": "sub-workflow", "name": "assign-skills" }, { "kind": "trigger", "name": "nightly-roster-sync", "triggerType": "schedule", "scheduleCron": "0 3 * * *" } ], "peerDepDecisions": [ { "kind": "connection", "peerDep": { "name": "five9-admin", "type": "five9", "description": "Admin credentials used to create the agent profile." }, "existingMatch": { "id": "0d7c4b81-52ae-4f39-9c60-8b13e7a2f405", "name": "five9-admin", "type": "five9" } }, { "kind": "env-shared", "peerDep": { "kind": "shared", "key": "AGENT_DEFAULT_SKILL_GROUP", "default": "inbound-sales" } }, { "kind": "data-store-table", "peerDep": { "name": "agent_roster", "description": "Source of truth for the nightly sync." } } ], "setupChecklistPreview": [ { "kind": "authenticate-connection", "label": "Authenticate the five9-admin connection", "relatedPeerDepKey": "connection:five9-admin" } ], "collisions": [], "sharedEnvKeys": [ "FIVE9_DOMAIN", "SUPPORT_QUEUE" ], "dependencies": [] } } } }, "400": { "description": "No file was sent, or the archive could not be read." } }, "summary": "Preview an install from an uploaded archive", "tags": [ "Packages" ] } }, "/packages/install/u/{token}": { "get": { "description": "Turns an install token into the package version it points at, so the install flow can start. Holding the token is the permission: it works across organizations even for packages you could not otherwise see, though for a `private` package it only works for members of the publishing organization. You still have to be signed in. Rotated, mistyped and expired tokens all return the same 404 on purpose, so nobody can use this endpoint to discover which tokens exist. The token is not echoed back in the response.", "operationId": "PackagesInstallController.resolveUnlistedToken", "parameters": [ { "name": "token", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageVersionResponseDto" }, "example": { "id": "c4d81e07-2b93-4a6f-9d15-7e0b83af5c62", "suid": "v7hn", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "packageId": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "version": "1.4.0", "manifest": { "schemaVersion": 1, "slug": "@k4v9/agent-onboarding", "version": "1.4.0", "name": "Agent Onboarding", "description": "Provisions a new contact-center agent.", "tags": [ "contact-center", "onboarding" ], "packageId": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "authorOrganizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "authorOrgSuid": "k4v9", "resources": [ { "kind": "workflow", "name": "onboard-agent", "isRoot": true }, { "kind": "sub-workflow", "name": "assign-skills" }, { "kind": "trigger", "name": "nightly-roster-sync", "triggerType": "schedule", "scheduleCron": "0 3 * * *" }, { "kind": "dashboard", "name": "onboarding-health" } ], "peerDeps": { "connections": [ { "name": "five9-admin", "type": "five9", "description": "Admin credentials used to create the agent profile." } ], "env": { "required": [ { "kind": "shared", "key": "AGENT_DEFAULT_SKILL_GROUP", "default": "inbound-sales" } ], "optional": [] }, "dataStoreTables": [ { "name": "agent_roster", "description": "Source of truth for the nightly sync." } ] }, "extensionPoints": [] }, "artifactUrl": "gs://quickflo-package-artifacts/packages/9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845/1.4.0/agent-onboarding.qfpkg", "artifactDigest": "7d0f3a1c9b48e25f6a0d7c31be94f28d5a637c0e18b4d92f5c73a0e6b184df29", "summary": "Add the nightly roster sync trigger", "releaseNotes": "## 1.4.0\n\n- Nightly roster sync keeps the agent list current.\n- Welcome ticket now includes the assigned skill group.", "publishedAt": "2026-07-19T09:31:44.902Z", "publishedByUserId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "createdAt": "2026-07-19T09:31:44.902Z", "updatedAt": "2026-07-19T09:31:44.902Z" } } } }, "404": { "description": "The link is invalid, has been rotated, or is not for you." } }, "summary": "Resolve a share link", "tags": [ "Packages" ] } }, "/packages/marketplace": { "get": { "description": "Every public package across every organization, newest and most-installed first. `q` matches name, slug and description. `filter` is a comma-separated list; `verified` and `agent-tools` are the recognized values and they narrow the results together. `limit` defaults to 50 and caps at 100.", "operationId": "PackagesController.listMarketplace", "parameters": [ { "name": "limit", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "offset", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "q", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "filter", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageListResponseDto" }, "example": { "total": 42, "data": [ { "id": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "suid": "p3wq", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "slug": "@k4v9/agent-onboarding", "name": "Agent Onboarding", "description": "Provisions a new contact-center agent: creates the profile, assigns skills, and files the welcome ticket.", "supportContactEmail": "support@acme.example", "documentationUrl": "https://docs.acme.example/agent-onboarding", "websiteUrl": "https://acme.example", "icon": "https://cdn.quickflo.app/packages/9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845/icon-4f1c9ab2e037.png", "readme": "# Agent Onboarding\n\nRun this once per new hire. See the setup checklist after installing.", "tags": [ "contact-center", "onboarding" ], "visibility": "public", "latestVersionId": "c4d81e07-2b93-4a6f-9d15-7e0b83af5c62", "installCount": 12, "isVerified": true, "hasAgentTools": false, "resourceCounts": { "workflows": 2, "subWorkflows": 1, "triggers": 1, "dashboards": 1 }, "createdAt": "2026-05-04T14:22:08.117Z", "updatedAt": "2026-07-19T09:31:44.902Z" } ] } } } } }, "summary": "Browse the public marketplace", "tags": [ "Packages" ] } }, "/packages/preview": { "post": { "description": "Dry run. Nothing is written and no version is created. Starts from the resources you name and follows every sub-workflow, connection, environment variable and data-store reference, so you can see the full contents before publishing. `issues` with severity `error` will block the actual publish.", "operationId": "PackagesController.previewPackage", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackagePreviewRequestDto" }, "examples": { "oneWorkflow": { "summary": "One workflow and its dependencies", "value": { "roots": [ { "kind": "workflow", "workflowTemplateId": "e83b5f20-9d47-4a16-b2c8-6017fa39d5be" } ] } }, "mixed": { "summary": "Workflow, trigger and dashboard", "value": { "roots": [ { "kind": "workflow", "workflowTemplateId": "e83b5f20-9d47-4a16-b2c8-6017fa39d5be" }, { "kind": "trigger", "triggerId": "b1470ce9-3a28-4d75-90ef-58c2d6b3419a" }, { "kind": "dashboard", "dashboardId": "6ae0f27c-4d18-4b93-8f52-1c07de93ba48" } ] } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageExportPreviewResponseDto" }, "example": { "graph": { "nodes": [ { "kind": "workflow", "name": "onboard-agent", "isRoot": true, "connections": [ { "name": "five9-admin" } ], "envRefs": [ { "kind": "shared", "key": "AGENT_DEFAULT_SKILL_GROUP" } ], "dataStoreTables": [ { "name": "agent_roster" } ], "subWorkflowRefs": [ { "workflowTemplateName": "assign-skills" } ], "dashboardDataSources": [], "toolPackRefs": [] }, { "kind": "sub-workflow", "name": "assign-skills", "isRoot": false, "connections": [ { "name": "five9-admin" } ], "envRefs": [], "dataStoreTables": [], "subWorkflowRefs": [], "dashboardDataSources": [], "toolPackRefs": [] } ], "aggregate": { "connections": [ { "name": "five9-admin" } ], "envRefs": [ { "kind": "shared", "key": "AGENT_DEFAULT_SKILL_GROUP" } ], "dataStoreTables": [ { "name": "agent_roster" } ], "dashboardDataSources": [], "toolPackRefs": [] }, "issues": [ { "severity": "warning", "code": "user-env-hardcoded", "message": "Step \"lookup-domain\" reads $env.prod.FIVE9_DOMAIN. Hardcoded environment names do not carry across organizations.", "resourceName": "onboard-agent", "stepId": "lookup-domain" } ] } } } } } }, "summary": "Preview what a publish would include", "tags": [ "Packages" ] } }, "/packages/resolve/@{orgSuid}/{localName}": { "get": { "description": "Looks a package up by `@/` instead of by id, and returns its latest visible version alongside it. Addresses that used an organization’s former short id keep working. The install token is stripped from the version here: fetch it from `GET /packages/{id}/versions/{version}/unlisted-token`.", "operationId": "PackagesController.resolveCanonicalSlug", "parameters": [ { "name": "orgSuid", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "localName", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageResolveResponseDto" }, "example": { "package": { "id": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "suid": "p3wq", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "slug": "@k4v9/agent-onboarding", "name": "Agent Onboarding", "description": "Provisions a new contact-center agent: creates the profile, assigns skills, and files the welcome ticket.", "supportContactEmail": "support@acme.example", "documentationUrl": "https://docs.acme.example/agent-onboarding", "websiteUrl": "https://acme.example", "icon": "https://cdn.quickflo.app/packages/9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845/icon-4f1c9ab2e037.png", "readme": "# Agent Onboarding\n\nRun this once per new hire. See the setup checklist after installing.", "tags": [ "contact-center", "onboarding" ], "visibility": "public", "latestVersionId": "c4d81e07-2b93-4a6f-9d15-7e0b83af5c62", "installCount": 12, "isVerified": true, "hasAgentTools": false, "resourceCounts": { "workflows": 2, "subWorkflows": 1, "triggers": 1, "dashboards": 1 }, "createdAt": "2026-05-04T14:22:08.117Z", "updatedAt": "2026-07-19T09:31:44.902Z" }, "latestVersion": { "id": "c4d81e07-2b93-4a6f-9d15-7e0b83af5c62", "suid": "v7hn", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "packageId": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "version": "1.4.0", "manifest": { "schemaVersion": 1, "slug": "@k4v9/agent-onboarding", "version": "1.4.0", "name": "Agent Onboarding", "description": "Provisions a new contact-center agent.", "tags": [ "contact-center", "onboarding" ], "packageId": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "authorOrganizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "authorOrgSuid": "k4v9", "resources": [ { "kind": "workflow", "name": "onboard-agent", "isRoot": true }, { "kind": "sub-workflow", "name": "assign-skills" }, { "kind": "trigger", "name": "nightly-roster-sync", "triggerType": "schedule", "scheduleCron": "0 3 * * *" }, { "kind": "dashboard", "name": "onboarding-health" } ], "peerDeps": { "connections": [ { "name": "five9-admin", "type": "five9", "description": "Admin credentials used to create the agent profile." } ], "env": { "required": [ { "kind": "shared", "key": "AGENT_DEFAULT_SKILL_GROUP", "default": "inbound-sales" } ], "optional": [] }, "dataStoreTables": [ { "name": "agent_roster", "description": "Source of truth for the nightly sync." } ] }, "extensionPoints": [] }, "artifactUrl": "gs://quickflo-package-artifacts/packages/9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845/1.4.0/agent-onboarding.qfpkg", "artifactDigest": "7d0f3a1c9b48e25f6a0d7c31be94f28d5a637c0e18b4d92f5c73a0e6b184df29", "summary": "Add the nightly roster sync trigger", "releaseNotes": "## 1.4.0\n\n- Nightly roster sync keeps the agent list current.\n- Welcome ticket now includes the assigned skill group.", "publishedAt": "2026-07-19T09:31:44.902Z", "publishedByUserId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "createdAt": "2026-07-19T09:31:44.902Z", "updatedAt": "2026-07-19T09:31:44.902Z" } } } } }, "404": { "description": "No such package, or it is not visible to the caller." } }, "summary": "Resolve a package by its canonical address", "tags": [ "Packages" ] } }, "/packages/{id}": { "delete": { "description": "Permanent, and refused while anyone still has it installed. Installers keep their copies either way, so deleting only costs you the ability to ship them updates.", "operationId": "PackagesController.deletePackage", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageDeletedResponseDto" }, "example": { "deleted": true } } } }, "404": { "description": "No such package in your organization." }, "409": { "description": "At least one organization still has this installed. The body carries `code: \"RESOURCE_IN_USE\"` and `details.installCount`." } }, "summary": "Delete a package", "tags": [ "Packages" ] }, "get": { "description": "Visible if your organization publishes it, if it is public, or if your organization already has it installed.", "operationId": "PackagesController.getPackage", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageResponseDto" }, "example": { "id": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "suid": "p3wq", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "slug": "@k4v9/agent-onboarding", "name": "Agent Onboarding", "description": "Provisions a new contact-center agent: creates the profile, assigns skills, and files the welcome ticket.", "supportContactEmail": "support@acme.example", "documentationUrl": "https://docs.acme.example/agent-onboarding", "websiteUrl": "https://acme.example", "icon": "https://cdn.quickflo.app/packages/9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845/icon-4f1c9ab2e037.png", "readme": "# Agent Onboarding\n\nRun this once per new hire. See the setup checklist after installing.", "tags": [ "contact-center", "onboarding" ], "visibility": "public", "latestVersionId": "c4d81e07-2b93-4a6f-9d15-7e0b83af5c62", "installCount": 12, "isVerified": true, "hasAgentTools": false, "resourceCounts": { "workflows": 2, "subWorkflows": 1, "triggers": 1, "dashboards": 1 }, "createdAt": "2026-05-04T14:22:08.117Z", "updatedAt": "2026-07-19T09:31:44.902Z" } } } }, "404": { "description": "No such package, or it is not visible to the caller." } }, "summary": "Get a package", "tags": [ "Packages" ] }, "patch": { "description": "Edits the shell, not any published version. `description` and `readme` are read live at install time, so changes here reach installers without republishing. `isVerified` cannot be set through this endpoint. Moving to `public` or `unlisted` runs the same plan and slug checks as create.", "operationId": "PackagesController.updatePackage", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePackageDto" }, "examples": { "editListing": { "summary": "Edit the listing", "value": { "description": "Provisions a new contact-center agent, end to end.", "supportContactEmail": "support@acme.example" } }, "publish": { "summary": "Move to the public marketplace", "value": { "slug": "@k4v9/agent-onboarding", "visibility": "public" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageResponseDto" }, "example": { "id": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "suid": "p3wq", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "slug": "@k4v9/agent-onboarding", "name": "Agent Onboarding", "description": "Provisions a new contact-center agent: creates the profile, assigns skills, and files the welcome ticket.", "supportContactEmail": "support@acme.example", "documentationUrl": "https://docs.acme.example/agent-onboarding", "websiteUrl": "https://acme.example", "icon": "https://cdn.quickflo.app/packages/9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845/icon-4f1c9ab2e037.png", "readme": "# Agent Onboarding\n\nRun this once per new hire. See the setup checklist after installing.", "tags": [ "contact-center", "onboarding" ], "visibility": "public", "latestVersionId": "c4d81e07-2b93-4a6f-9d15-7e0b83af5c62", "installCount": 12, "isVerified": true, "hasAgentTools": false, "resourceCounts": { "workflows": 2, "subWorkflows": 1, "triggers": 1, "dashboards": 1 }, "createdAt": "2026-05-04T14:22:08.117Z", "updatedAt": "2026-07-19T09:31:44.902Z" } } } }, "400": { "description": "The plan does not allow the requested visibility, or a public package was given a slug that is not `@/`." }, "404": { "description": "No such package in your organization." } }, "summary": "Update a package", "tags": [ "Packages" ] } }, "/packages/{id}/fleet": { "get": { "description": "Publisher-only. Lists the organizations that installed the package, the version each is on, and how their runs went over the last 30 days. Only available for packages your own organization publishes: anyone else gets a 404 even for a public package they can otherwise read. Customer names are read live, so a rename shows up on the next request. `q` matches organization name or short id; `versionId` narrows to organizations on one version. Both narrow the `rows` page only: `totals` and `byVersion` always cover the whole fleet.", "operationId": "PackagesController.getPackageFleet", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "limit", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "offset", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "q", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "versionId", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageFleetResponseDto" }, "example": { "totals": { "distinctOrgs": 12, "topLevelInstalls": 14, "totalInstalls": 19, "runs": { "success": 4820, "completedWithErrors": 61, "failed": 37, "cancelled": 4, "rejected": 0, "running": 2, "total": 4924 }, "windowDays": 30 }, "byVersion": [ { "versionId": "c4d81e07-2b93-4a6f-9d15-7e0b83af5c62", "version": "1.4.0", "orgCount": 9, "installCount": 10, "runs": { "success": 4102, "completedWithErrors": 41, "failed": 22, "cancelled": 3, "rejected": 0, "running": 2, "total": 4170 } }, { "versionId": "a07be3d2-5f14-4c88-9b60-2e73d1a4f905", "version": "1.3.1", "orgCount": 3, "installCount": 4, "runs": { "success": 718, "completedWithErrors": 20, "failed": 15, "cancelled": 1, "rejected": 0, "running": 0, "total": 754 } } ], "rows": [ { "organizationId": "5c0a97e4-1b62-4d39-8f7a-3e5b21c60d84", "organizationName": "Northwind Support", "organizationSuid": "n8tz", "installedVersionId": "c4d81e07-2b93-4a6f-9d15-7e0b83af5c62", "installedVersion": "1.4.0", "installCount": 1, "firstInstalledAt": "2026-06-02T11:07:19.004Z", "lastInstalledAt": "2026-07-20T16:45:02.881Z", "lastRunAt": "2026-07-27T03:00:11.620Z", "runs": { "success": 612, "completedWithErrors": 5, "failed": 3, "cancelled": 0, "rejected": 0, "running": 1, "total": 621 } } ], "total": 12, "latestVersionId": "c4d81e07-2b93-4a6f-9d15-7e0b83af5c62", "latestVersion": "1.4.0" } } } }, "404": { "description": "No such package, or your organization does not publish it." } }, "summary": "See who is running your package", "tags": [ "Packages" ] } }, "/packages/{id}/icon": { "delete": { "description": "Clears `icon` and deletes the hosted image. Marketplace cards fall back to the default glyph.", "operationId": "PackagesController.deletePackageIcon", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageResponseDto" }, "example": { "id": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "suid": "p3wq", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "slug": "@k4v9/agent-onboarding", "name": "Agent Onboarding", "description": "Provisions a new contact-center agent: creates the profile, assigns skills, and files the welcome ticket.", "supportContactEmail": "support@acme.example", "documentationUrl": "https://docs.acme.example/agent-onboarding", "websiteUrl": "https://acme.example", "icon": null, "readme": "# Agent Onboarding\n\nRun this once per new hire. See the setup checklist after installing.", "tags": [ "contact-center", "onboarding" ], "visibility": "public", "latestVersionId": "c4d81e07-2b93-4a6f-9d15-7e0b83af5c62", "installCount": 12, "isVerified": true, "hasAgentTools": false, "resourceCounts": { "workflows": 2, "subWorkflows": 1, "triggers": 1, "dashboards": 1 }, "createdAt": "2026-05-04T14:22:08.117Z", "updatedAt": "2026-07-19T09:31:44.902Z" } } } }, "404": { "description": "No such package in your organization." } }, "summary": "Remove a package icon", "tags": [ "Packages" ] }, "post": { "description": "Multipart upload with a single `file` field. Any common image format is accepted, up to 2 MB. The image is cropped from the center and re-encoded to a 512x512 PNG so every marketplace card lines up, then served from the CDN. The previous icon is removed. Returns the updated package with `icon` pointing at the new URL.", "operationId": "PackagesController.uploadPackageIcon", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Square image, 2 MB or smaller." } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageResponseDto" }, "example": { "id": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "suid": "p3wq", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "slug": "@k4v9/agent-onboarding", "name": "Agent Onboarding", "description": "Provisions a new contact-center agent: creates the profile, assigns skills, and files the welcome ticket.", "supportContactEmail": "support@acme.example", "documentationUrl": "https://docs.acme.example/agent-onboarding", "websiteUrl": "https://acme.example", "icon": "https://cdn.quickflo.app/packages/9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845/icon-4f1c9ab2e037.png", "readme": "# Agent Onboarding\n\nRun this once per new hire. See the setup checklist after installing.", "tags": [ "contact-center", "onboarding" ], "visibility": "public", "latestVersionId": "c4d81e07-2b93-4a6f-9d15-7e0b83af5c62", "installCount": 12, "isVerified": true, "hasAgentTools": false, "resourceCounts": { "workflows": 2, "subWorkflows": 1, "triggers": 1, "dashboards": 1 }, "createdAt": "2026-05-04T14:22:08.117Z", "updatedAt": "2026-07-19T09:31:44.902Z" } } } }, "400": { "description": "No file was sent, the file is not an image the server can read, or icon hosting is not configured." }, "404": { "description": "No such package in your organization." } }, "summary": "Upload a package icon", "tags": [ "Packages" ] } }, "/packages/{id}/versions": { "get": { "description": "Install tokens are stripped from these rows. Fetch one from `GET /packages/{id}/versions/{version}/unlisted-token`.", "operationId": "PackagesController.listVersions", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageVersionListResponseDto" }, "example": { "total": 1, "data": [ { "id": "c4d81e07-2b93-4a6f-9d15-7e0b83af5c62", "suid": "v7hn", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "packageId": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "version": "1.4.0", "manifest": { "schemaVersion": 1, "slug": "@k4v9/agent-onboarding", "version": "1.4.0", "name": "Agent Onboarding", "description": "Provisions a new contact-center agent.", "tags": [ "contact-center", "onboarding" ], "packageId": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "authorOrganizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "authorOrgSuid": "k4v9", "resources": [ { "kind": "workflow", "name": "onboard-agent", "isRoot": true }, { "kind": "sub-workflow", "name": "assign-skills" }, { "kind": "trigger", "name": "nightly-roster-sync", "triggerType": "schedule", "scheduleCron": "0 3 * * *" }, { "kind": "dashboard", "name": "onboarding-health" } ], "peerDeps": { "connections": [ { "name": "five9-admin", "type": "five9", "description": "Admin credentials used to create the agent profile." } ], "env": { "required": [ { "kind": "shared", "key": "AGENT_DEFAULT_SKILL_GROUP", "default": "inbound-sales" } ], "optional": [] }, "dataStoreTables": [ { "name": "agent_roster", "description": "Source of truth for the nightly sync." } ] }, "extensionPoints": [] }, "artifactUrl": "gs://quickflo-package-artifacts/packages/9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845/1.4.0/agent-onboarding.qfpkg", "artifactDigest": "7d0f3a1c9b48e25f6a0d7c31be94f28d5a637c0e18b4d92f5c73a0e6b184df29", "summary": "Add the nightly roster sync trigger", "releaseNotes": "## 1.4.0\n\n- Nightly roster sync keeps the agent list current.\n- Welcome ticket now includes the assigned skill group.", "publishedAt": "2026-07-19T09:31:44.902Z", "publishedByUserId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "createdAt": "2026-07-19T09:31:44.902Z", "updatedAt": "2026-07-19T09:31:44.902Z" } ] } } } }, "404": { "description": "No such package, or it is not visible to the caller." } }, "summary": "List versions of a package", "tags": [ "Packages" ] }, "post": { "description": "Writes a new immutable version: bundles the resources you name, uploads the archive, and records the manifest. Use `POST /packages/preview` first to see what would be included. Versions cannot be overwritten, so publishing an existing version number fails. `slug` and `name` always come from the package, not from this body. The response is the only place the install token is handed back in full.", "operationId": "PackagesController.publishVersion", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishPackageVersionDto" }, "examples": { "minimal": { "summary": "One workflow", "value": { "version": "1.0.0", "roots": [ { "kind": "workflow", "workflowTemplateId": "e83b5f20-9d47-4a16-b2c8-6017fa39d5be" } ] } }, "release": { "summary": "Release with notes and a scheduled trigger", "value": { "version": "1.4.0", "summary": "Add the nightly roster sync trigger", "changelog": "## 1.4.0\n\n- Nightly roster sync keeps the agent list current.", "tags": [ "contact-center", "onboarding" ], "roots": [ { "kind": "workflow", "workflowTemplateId": "e83b5f20-9d47-4a16-b2c8-6017fa39d5be" }, { "kind": "trigger", "triggerId": "b1470ce9-3a28-4d75-90ef-58c2d6b3419a" }, { "kind": "data-store-table", "tableName": "agent_roster", "includeSeedRows": true } ], "sharedEnvDefaults": { "include": [ "AGENT_DEFAULT_SKILL_GROUP" ] } } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishPackageVersionResponseDto" }, "example": { "packageVersion": { "id": "c4d81e07-2b93-4a6f-9d15-7e0b83af5c62", "suid": "v7hn", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "packageId": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "version": "1.4.0", "manifest": { "schemaVersion": 1, "slug": "@k4v9/agent-onboarding", "version": "1.4.0", "name": "Agent Onboarding", "description": "Provisions a new contact-center agent.", "tags": [ "contact-center", "onboarding" ], "packageId": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "authorOrganizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "authorOrgSuid": "k4v9", "resources": [ { "kind": "workflow", "name": "onboard-agent", "isRoot": true }, { "kind": "sub-workflow", "name": "assign-skills" }, { "kind": "trigger", "name": "nightly-roster-sync", "triggerType": "schedule", "scheduleCron": "0 3 * * *" }, { "kind": "dashboard", "name": "onboarding-health" } ], "peerDeps": { "connections": [ { "name": "five9-admin", "type": "five9", "description": "Admin credentials used to create the agent profile." } ], "env": { "required": [ { "kind": "shared", "key": "AGENT_DEFAULT_SKILL_GROUP", "default": "inbound-sales" } ], "optional": [] }, "dataStoreTables": [ { "name": "agent_roster", "description": "Source of truth for the nightly sync." } ] }, "extensionPoints": [] }, "artifactUrl": "gs://quickflo-package-artifacts/packages/9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845/1.4.0/agent-onboarding.qfpkg", "artifactDigest": "7d0f3a1c9b48e25f6a0d7c31be94f28d5a637c0e18b4d92f5c73a0e6b184df29", "summary": "Add the nightly roster sync trigger", "releaseNotes": "## 1.4.0\n\n- Nightly roster sync keeps the agent list current.\n- Welcome ticket now includes the assigned skill group.", "publishedAt": "2026-07-19T09:31:44.902Z", "publishedByUserId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "createdAt": "2026-07-19T09:31:44.902Z", "updatedAt": "2026-07-19T09:31:44.902Z", "unlistedInstallToken": "" }, "manifest": { "schemaVersion": 1, "slug": "@k4v9/agent-onboarding", "version": "1.4.0", "name": "Agent Onboarding", "description": "Provisions a new contact-center agent.", "tags": [ "contact-center", "onboarding" ], "packageId": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "authorOrganizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "authorOrgSuid": "k4v9", "resources": [ { "kind": "workflow", "name": "onboard-agent", "isRoot": true }, { "kind": "sub-workflow", "name": "assign-skills" }, { "kind": "trigger", "name": "nightly-roster-sync", "triggerType": "schedule", "scheduleCron": "0 3 * * *" }, { "kind": "dashboard", "name": "onboarding-health" } ], "peerDeps": { "connections": [ { "name": "five9-admin", "type": "five9", "description": "Admin credentials used to create the agent profile." } ], "env": { "required": [ { "kind": "shared", "key": "AGENT_DEFAULT_SKILL_GROUP", "default": "inbound-sales" } ], "optional": [] }, "dataStoreTables": [ { "name": "agent_roster", "description": "Source of truth for the nightly sync." } ] }, "extensionPoints": [] }, "artifactBytes": 48213, "artifactDigest": "7d0f3a1c9b48e25f6a0d7c31be94f28d5a637c0e18b4d92f5c73a0e6b184df29", "artifactUrl": "gs://quickflo-package-artifacts/packages/9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845/1.4.0/agent-onboarding.qfpkg" } } } }, "400": { "description": "The version is not valid semver, a listed resource could not be bundled, or the plan no longer allows publishing at this visibility." }, "404": { "description": "No such package in your organization." }, "409": { "description": "That version number is already published." } }, "summary": "Publish a version", "tags": [ "Packages" ] } }, "/packages/{id}/versions/{version}": { "get": { "description": "`version` is the semver string, for example `1.4.0`. The install token is stripped from the response.", "operationId": "PackagesController.getVersion", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "version", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageVersionResponseDto" }, "example": { "id": "c4d81e07-2b93-4a6f-9d15-7e0b83af5c62", "suid": "v7hn", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "packageId": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "version": "1.4.0", "manifest": { "schemaVersion": 1, "slug": "@k4v9/agent-onboarding", "version": "1.4.0", "name": "Agent Onboarding", "description": "Provisions a new contact-center agent.", "tags": [ "contact-center", "onboarding" ], "packageId": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "authorOrganizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "authorOrgSuid": "k4v9", "resources": [ { "kind": "workflow", "name": "onboard-agent", "isRoot": true }, { "kind": "sub-workflow", "name": "assign-skills" }, { "kind": "trigger", "name": "nightly-roster-sync", "triggerType": "schedule", "scheduleCron": "0 3 * * *" }, { "kind": "dashboard", "name": "onboarding-health" } ], "peerDeps": { "connections": [ { "name": "five9-admin", "type": "five9", "description": "Admin credentials used to create the agent profile." } ], "env": { "required": [ { "kind": "shared", "key": "AGENT_DEFAULT_SKILL_GROUP", "default": "inbound-sales" } ], "optional": [] }, "dataStoreTables": [ { "name": "agent_roster", "description": "Source of truth for the nightly sync." } ] }, "extensionPoints": [] }, "artifactUrl": "gs://quickflo-package-artifacts/packages/9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845/1.4.0/agent-onboarding.qfpkg", "artifactDigest": "7d0f3a1c9b48e25f6a0d7c31be94f28d5a637c0e18b4d92f5c73a0e6b184df29", "summary": "Add the nightly roster sync trigger", "releaseNotes": "## 1.4.0\n\n- Nightly roster sync keeps the agent list current.\n- Welcome ticket now includes the assigned skill group.", "publishedAt": "2026-07-19T09:31:44.902Z", "publishedByUserId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "createdAt": "2026-07-19T09:31:44.902Z", "updatedAt": "2026-07-19T09:31:44.902Z" } } } }, "404": { "description": "No such version, or it is not visible to the caller." } }, "summary": "Get one version", "tags": [ "Packages" ] } }, "/packages/{id}/versions/{version}/artifact": { "get": { "description": "Streams the `.qfpkg` bytes. This is a zip file, not JSON: it holds the manifest plus one file per bundled resource. Sent as an attachment named `-.qfpkg.zip`. The same bytes can be handed back to `POST /packages/install/preview-from-artifact` and `POST /packages/install/commit-from-artifact` to install without a link.", "operationId": "PackagesController.downloadVersionArtifact", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "version", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The archive bytes.", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "No such version, it is not visible to the caller, or it has no archive on record." }, "413": { "description": "The stored archive is larger than the configured download limit." } }, "summary": "Download the package archive", "tags": [ "Packages" ] } }, "/packages/{id}/versions/{version}/rotate-unlisted-token": { "post": { "description": "Replaces the token and returns the new one. Every install link you handed out for this version stops working the moment this returns, so plan to redistribute. Organizations that already installed the package keep what they have: rotation stops new installs, it does not take anything away. Also used to mint a first token for versions published before install tokens existed.", "operationId": "PackagesController.rotateUnlistedToken", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "version", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateUnlistedTokenResponseDto" }, "example": { "packageId": "9b2f4c61-8d5a-4e37-b0c9-1f7a63e2d845", "version": "1.4.0", "unlistedInstallToken": "", "rotatedAt": "2026-07-27T16:04:11.482Z", "rotatedByUserId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d" } } } }, "404": { "description": "No such version, or your organization does not publish it." } }, "summary": "Rotate the install token for a version", "tags": [ "Packages" ] } }, "/packages/{id}/versions/{version}/unlisted-token": { "get": { "description": "The token is a credential. Anyone signed in who holds it can install this exact version into their own organization, whatever the package visibility says, with one exception: for a `private` package it only works for members of the publishing organization. Treat it like a password and share it only with people you mean to give the package to. Publishing rights are required, so read-only members cannot pull it out of this endpoint, and it is stripped from every other read. Returns null for versions published before install tokens existed; rotate to mint one.", "operationId": "PackagesController.getUnlistedToken", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "version", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnlistedTokenResponseDto" }, "example": { "unlistedInstallToken": "" } } } }, "404": { "description": "No such version, or your organization does not publish it." } }, "summary": "Get the install token for a version", "tags": [ "Packages" ] } }, "/partner/managed-orgs": { "get": { "description": "Every child org billed to your partner org, with its plan, status, billing period and (when you set one) your own `externalRef`. This is the entitlement source of truth for partner-side automation: poll it to see which customers are live, trialing or suspended. Requires `partner:view`, since it is the customer roster you are paying for. Page with `limit` (max 500) and `offset`.", "operationId": "PartnerManagedOrgsController.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 500, "exclusiveMaximum": false, "exclusiveMinimum": false, "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "schema": { "minimum": 0, "exclusiveMinimum": false, "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedOrgResponseDto" } }, "example": [ { "organizationId": "9c4e2f61-7a35-4d8b-b012-5e7d3a9f1c46", "name": "Northwind Support", "plan": { "slug": "growth", "name": "Growth" }, "status": "active", "currentPeriodStart": "2026-07-01T00:00:00.000Z", "currentPeriodEnd": "2026-08-01T00:00:00.000Z", "createdAt": "2026-07-01T14:22:09.118Z", "externalRef": "crm-8842" } ] } } } }, "summary": "List child organizations", "tags": [ "Partners" ] }, "post": { "description": "Creates a customer organization underneath your partner org, on a plan you choose.\n\n**The child is billed to you, not to itself.** A child org has no payment method and never sees a checkout: its usage is invoiced to the partner org that created it, consolidated onto the partner's own monthly invoice alongside every other child. Creating a child is therefore a paying action, which is why it requires `partner:manage` on the partner org rather than plain membership. Members of the child work in it normally and are never asked to pay.\n\n`planSlug` must be one the partner is allowed to assign; call `GET /partner/managed-orgs/plans` for the current list. Pass `trialDays` to start the child TRIALING, which contributes no invoice lines until it is activated: use it for pilots you do not want to pay for yet. Omit it and the child is billable from birth.\n\nFor machine-driven provisioning, send your own customer key as `externalRef`: a repeat create with the same ref returns the existing child instead of provisioning (and billing for) a duplicate, so retries are safe. Bulk provisioners should also pass `autoJoin: false` to avoid seating the calling user in every child they create.", "operationId": "PartnerManagedOrgsController.create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateManagedOrgBody" }, "examples": { "minimal": { "summary": "Billable from birth", "value": { "name": "Northwind Support", "planSlug": "growth" } }, "pilot": { "summary": "30-day pilot, machine-provisioned", "value": { "name": "Northwind Support", "planSlug": "growth", "trialDays": 30, "externalRef": "crm-8842", "autoJoin": false } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedOrgResponseDto" }, "example": { "organizationId": "9c4e2f61-7a35-4d8b-b012-5e7d3a9f1c46", "name": "Northwind Support", "plan": { "slug": "growth", "name": "Growth" }, "status": "active", "currentPeriodStart": "2026-07-01T00:00:00.000Z", "currentPeriodEnd": "2026-08-01T00:00:00.000Z", "createdAt": "2026-07-01T14:22:09.118Z", "externalRef": "crm-8842" } } } } }, "summary": "Create a child organization", "tags": [ "Partners" ] } }, "/partner/managed-orgs/invoice-links": { "get": { "description": "Your most recent invoices with their CURRENT state in Stripe, newest first, and the invoice page link where one exists.\n\nThis is a live read rather than a stored link, because an invoice can change after we draft it: a draft that was released or deleted no longer exists, and a finalized one becomes payable and then paid. The newest entry with a `hostedUrl` is the invoice your customer can actually open — earlier voided or deleted attempts are reported with their real status instead of a dead link. A `draft` has no link yet: Stripe only creates the shareable page when the invoice is finalized.\n\nPass `invoiceId` to resolve one specific invoice, or `limit` to walk further back (default 5).", "operationId": "PartnerManagedOrgsController.listInvoiceLinks", "parameters": [ { "name": "invoiceId", "required": false, "in": "query", "description": "Resolve one specific invoice instead of the recent list.", "schema": { "minLength": 1, "maxLength": 255, "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 20, "exclusiveMaximum": false, "exclusiveMinimum": false, "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceLinkResponseDto" } }, "example": [ { "invoiceId": "in_1Tywi1KHNIcZi8w3pSD623uV", "issuedAt": "2026-07-01T02:00:00.000Z", "totalCents": 131630, "status": "open", "hostedUrl": "https://invoice.stripe.com/i/acct_1.../live_..." }, { "invoiceId": "in_1Tye8XKHNIcZi8w3fJcxG5LK", "issuedAt": "2026-06-01T02:00:00.000Z", "totalCents": 100200, "status": "paid", "hostedUrl": "https://invoice.stripe.com/i/acct_1.../live_..." } ] } } } }, "summary": "Get shareable links for your recent invoices", "tags": [ "Partners" ] } }, "/partner/managed-orgs/invoices": { "get": { "description": "Every consolidated invoice issued to you, newest first (up to 24), with the per-customer lines exactly as they were billed. The invoice id matches the Stripe invoice you receive by email.", "operationId": "PartnerManagedOrgsController.listInvoices", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerInvoiceResponseDto" } }, "example": [ { "invoiceId": "in_1Tye8XKHNIcZi8w3fJcxG5LK", "issuedAt": "2026-07-01T02:00:00.000Z", "totalCents": 131630, "lines": [ { "description": "Acme Contact Center — Growth (2026-05-29 → 2026-06-29) [wholesale -10%] [retail $449.00/mo]", "amountCents": 40410, "kind": "base-fee" } ] } ] } } } }, "summary": "List your consolidated invoices", "tags": [ "Partners" ] } }, "/partner/managed-orgs/plans": { "get": { "description": "The plans you are allowed to put a child on, which is what `planSlug` accepts when creating one.\n\nTwo prices come back per plan and they mean different things. `priceMonthly` is the public retail price in whole dollars. `yourPriceMonthlyCents` is what a new child on that plan actually costs YOU each month, in cents, after your wholesale discount is applied; `priceSource` says which of the two rules produced it and `discountPercent` reports the discount when one applied. Bill your own customer whatever you like: the margin between the two is yours.\n\nOne case is not visible here. A per-deal price negotiated for one specific child overrides both figures, and because it is set per child rather than per plan it cannot be reflected in a plan listing. Read a child's actual accrual from your consolidated invoice.", "operationId": "PartnerManagedOrgsController.listAssignablePlans", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AssignablePlanResponseDto" } }, "example": [ { "slug": "growth", "name": "Growth", "description": "For teams running production automations.", "family": "standard", "priceMonthly": 99, "yourPriceMonthlyCents": 8415, "priceSource": "wholesale-discount", "discountPercent": 15 } ] } } } }, "summary": "List assignable plans", "tags": [ "Partners" ] } }, "/partner/managed-orgs/solutions": { "get": { "description": "The operator’s inventory: every package installed in the customer orgs you pay for or operate — the version each runs, whether a newer published version exists, and how the installs have been running over the last 14 days. `origin` says whose package each row is: `yours` (published by your org), `theirs` (the customer’s own), or `marketplace`.", "operationId": "PartnerManagedOrgsController.listSolutions", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerSolutionResponseDto" } }, "example": [ { "organizationId": "9c4e2f61-7a35-4d8b-b012-5e7d3a9f1c46", "packageId": "2b8f4c19-6d07-4e53-9a1b-7c0e5f2d8a34", "packageName": "Lead Generation", "origin": "yours", "installedVersion": "1.2.0", "latestVersion": "1.3.0", "behindLatest": true, "lastRunAt": "2026-07-30T22:04:00.000Z", "runs": { "total": 148, "success": 141, "failed": 7 } } ] } } } }, "summary": "List installed packages across your customers", "tags": [ "Partners" ] } }, "/partner/managed-orgs/upcoming-invoice": { "get": { "description": "What you have accrued so far toward your next consolidated invoice: closed base-fee months awaiting billing plus unbilled overage, in cents. Months still in progress join once they close, so this number grows over the cycle and resets when an invoice is drafted.", "operationId": "PartnerManagedOrgsController.upcomingInvoice", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpcomingInvoiceResponseDto" }, "example": { "totalCents": 131630, "baseFeeCents": 129130, "overageCents": 2500, "chargeCount": 4, "snapshotCount": 1 } } } } }, "summary": "Preview your next consolidated invoice", "tags": [ "Partners" ] } }, "/partner/managed-orgs/usage": { "get": { "description": "Current-period metered usage (workflow executions, credits) against plan limits, per customer org — the same numbers each customer sees on their own billing page. Use it to spot customers close to their caps before overage accrues on your invoice.", "operationId": "PartnerManagedOrgsController.listUsage", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ChildUsageResponseDto" } }, "example": [ { "organizationId": "9c4e2f61-7a35-4d8b-b012-5e7d3a9f1c46", "factors": [ { "key": "step_executions", "name": "Step Executions", "used": 12300, "included": 50000, "isUnlimited": false } ] } ] } } } }, "summary": "List your customers' usage", "tags": [ "Partners" ] } }, "/partner/managed-orgs/{childOrgId}/activate": { "post": { "description": "Ends a trial or lifts a suspension and makes the child billable. Its billing period re-anchors to now, and from this point its usage appears on your consolidated invoice. Use this when a pilot converts into a paying customer.", "operationId": "PartnerManagedOrgsController.activate", "parameters": [ { "name": "childOrgId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedOrgResponseDto" }, "example": { "organizationId": "9c4e2f61-7a35-4d8b-b012-5e7d3a9f1c46", "name": "Northwind Support", "plan": { "slug": "growth", "name": "Growth" }, "status": "active", "currentPeriodStart": "2026-07-01T00:00:00.000Z", "currentPeriodEnd": "2026-08-01T00:00:00.000Z", "createdAt": "2026-07-01T14:22:09.118Z", "externalRef": "crm-8842" } } } } }, "summary": "Activate a child organization", "tags": [ "Partners" ] } }, "/partner/managed-orgs/{childOrgId}/deactivate": { "post": { "description": "Suspends a child whose customer has churned or paused. Its billing cycle freezes, so it stops adding new charges to your invoice; usage already accrued in the open period is still captured and billed. The org and its data are kept, and `activate` brings it back.", "operationId": "PartnerManagedOrgsController.deactivate", "parameters": [ { "name": "childOrgId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedOrgResponseDto" }, "example": { "organizationId": "9c4e2f61-7a35-4d8b-b012-5e7d3a9f1c46", "name": "Northwind Support", "plan": { "slug": "growth", "name": "Growth" }, "status": "suspended", "currentPeriodStart": "2026-07-01T00:00:00.000Z", "currentPeriodEnd": "2026-08-01T00:00:00.000Z", "createdAt": "2026-07-01T14:22:09.118Z", "externalRef": "crm-8842", "suspendedReason": "partner_deactivated" } } } } }, "summary": "Deactivate a child organization", "tags": [ "Partners" ] } }, "/partner/managed-orgs/{childOrgId}/detach": { "post": { "description": "Ends your relationship with a churned customer. Months already served are settled to you first — they appear on your next consolidated invoice — then the org is suspended and unlinked: your tokens are revoked, your seats removed, and the slot in your allowance frees immediately. The org and its data are kept (platform support can restore or purge it later), but this is not reversible from the partner surface. A trial child settles nothing — pilots bill zero.", "operationId": "PartnerManagedOrgsController.detach", "parameters": [ { "name": "childOrgId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetachResultResponseDto" }, "example": { "organizationId": "9c4e2f61-7a35-4d8b-b012-5e7d3a9f1c46", "detached": true, "capturedMonths": 2 } } } } }, "summary": "Detach a child organization", "tags": [ "Partners" ] } }, "/partner/managed-orgs/{childOrgId}/graduate": { "post": { "description": "Converts a customer from your consolidated invoice to paying the platform directly. Months already served are settled to you first, then the child gets a grace window (default 30 days, `graceDays` to change) to subscribe through the normal checkout; if they do not, the org suspends when the window closes. You remain the operator: your tokens, seats and this roster keep working — the org just shows as `direct-pay` and its billing is no longer your business.", "operationId": "PartnerManagedOrgsController.graduate", "parameters": [ { "name": "childOrgId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraduateManagedOrgBody" }, "examples": { "default": { "summary": "30-day window", "value": {} }, "short": { "summary": "Two-week window", "value": { "graceDays": 14 } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraduateResultResponseDto" }, "example": { "organizationId": "9c4e2f61-7a35-4d8b-b012-5e7d3a9f1c46", "graduated": true, "capturedMonths": 1, "checkoutBy": "2026-08-29T00:00:00.000Z" } } } } }, "summary": "Graduate a child organization to direct pay", "tags": [ "Partners" ] } }, "/partner/managed-orgs/{childOrgId}/members/self": { "delete": { "description": "Removes the calling user from the child along with every permission they held in it. The child org itself is untouched and stays billed to you: this only ends your hands-on access to it.", "operationId": "PartnerManagedOrgsController.unseatSelf", "parameters": [ { "name": "childOrgId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChildMembershipResponseDto" }, "example": { "organizationId": "9c4e2f61-7a35-4d8b-b012-5e7d3a9f1c46", "seated": false } } } } }, "summary": "Leave a child organization", "tags": [ "Partners" ] }, "post": { "description": "Seats the calling user as a real member of the child, so it shows up in their org switcher and can be worked in through the full UI. Use this when you need to build or support a customer setup hands-on. Membership goes to the caller, not to an arbitrary user.", "operationId": "PartnerManagedOrgsController.seatSelf", "parameters": [ { "name": "childOrgId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChildMembershipResponseDto" }, "example": { "organizationId": "9c4e2f61-7a35-4d8b-b012-5e7d3a9f1c46", "seated": true } } } } }, "summary": "Join a child organization", "tags": [ "Partners" ] } }, "/partner/managed-orgs/{childOrgId}/plan": { "post": { "description": "Moves a child onto another plan you are allowed to assign (see `GET /partner/managed-orgs/plans`).\n\n**The change lands at the next billing period, never mid-period.** The month in progress finishes and bills at the current plan; the new plan's price and limits start with the next period, so there is no proration and no partial-month math on your invoice. Until then the child carries a `pendingPlan` in list/create responses. Requesting the child's CURRENT plan cancels a pending change; requesting a different one replaces it.\n\nA TRIALING child switches immediately instead — nothing has been billed yet, so picking the right plan for a pilot costs nothing. Suspended children are rejected: reactivate first.", "operationId": "PartnerManagedOrgsController.changePlan", "parameters": [ { "name": "childOrgId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeManagedOrgPlanBody" }, "examples": { "upgrade": { "summary": "Upgrade at next period", "value": { "planSlug": "scale" } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedOrgResponseDto" }, "example": { "organizationId": "9c4e2f61-7a35-4d8b-b012-5e7d3a9f1c46", "name": "Northwind Support", "plan": { "slug": "growth", "name": "Growth" }, "status": "active", "currentPeriodStart": "2026-07-01T00:00:00.000Z", "currentPeriodEnd": "2026-08-01T00:00:00.000Z", "createdAt": "2026-07-01T14:22:09.118Z", "externalRef": "crm-8842", "pendingPlan": { "slug": "scale", "name": "Scale", "effectiveAt": "2026-08-01T00:00:00.000Z" } } } } } }, "summary": "Change a child organization's plan", "tags": [ "Partners" ] } }, "/partner/managed-orgs/{childOrgId}/tokens": { "get": { "description": "Every token you minted for this child, including revoked ones — so outstanding keys are visible. Secrets are never returned (they are shown exactly once, at mint time). Tokens the customer created themselves are not listed and are never touched by rotation.", "operationId": "PartnerManagedOrgsController.listTokens", "parameters": [ { "name": "childOrgId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ChildTokenResponseDto" } }, "example": [ { "tokenId": "2b8f4c19-6d07-4e53-9a1b-7c0e5f2d8a34", "name": "provisioning", "revoked": false, "createdAt": "2026-07-30T14:22:09.118Z", "expiresAt": "2026-10-28T14:22:09.118Z" } ] } } } }, "summary": "List your tokens in a child organization", "tags": [ "Partners" ] }, "post": { "description": "Issues an access token scoped to one child org, so your systems can act inside a customer org without a user account in it. The secret is returned exactly once and cannot be recovered afterwards: store it when you receive it.\n\nTokens expire in 90 days unless `expiresInDays` says otherwise. Pass `rotate: true` to revoke every token you previously minted for this child in the same call, which is the safe way to roll a credential without a window where both work.", "operationId": "PartnerManagedOrgsController.mintToken", "parameters": [ { "name": "childOrgId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MintChildTokenBody" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MintedChildTokenResponseDto" }, "example": { "tokenId": "2b8f4c19-6d07-4e53-9a1b-7c0e5f2d8a34", "secret": "qf_pat_9f3c7a1e5b2d4086ac91e7d3b5f0", "name": "provisioning", "expiresAt": "2026-10-28T14:22:09.118Z", "revokedCount": 0 } } } } }, "summary": "Mint a token for a child organization", "tags": [ "Partners" ] } }, "/triggers": { "get": { "description": "Every trigger in the organization, across all workflows. Includes triggers whose workflow has since been deleted.", "operationId": "TriggersController.list", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowTriggerListResponseDto" }, "example": { "total": 2, "data": [ { "id": "9c2f1b40-7e83-4a51-b0d7-2f1c6e94a8d3", "suid": "p3rq", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "workflowId": "5b8d0f27-91c4-4e6a-8f3b-7d2a1c05e9b6", "type": "webhook", "name": "lead-intake", "orgSuid": "k4v9", "enabled": true, "config": { "webhook": { "path": "w_1a2b3c4d5e6f", "method": "POST", "authType": "token", "secret": "whs_example_placeholder_not_a_real_secret", "timeout": 30000 } }, "webhookUrl": "https://run.quickflo.app/w/@k4v9/lead-intake", "lastTriggeredAt": "2026-07-27T15:58:02.104Z", "lastTriggerExecutionId": "d41f8b6c-3a92-4c17-9e58-6b0d2f7a1c34", "triggerCount": 148, "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "metadata": {}, "createdAt": "2026-06-14T09:12:44.771Z", "updatedAt": "2026-07-27T15:58:02.104Z" }, { "id": "e07a5d61-4b28-4f9c-a3d5-8c19b7e02f4a", "suid": "z8ta", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "workflowId": "2c6e9a13-5f47-4d8b-b1e0-9a3f7c25d804", "type": "schedule", "name": "nightly-sync", "orgSuid": "k4v9", "enabled": true, "config": { "schedule": { "cron": "0 9 * * *", "timezone": "America/New_York", "environment": "production", "qstashScheduleId": "scd_example_1a2b3c", "initialData": { "reportType": "daily" } } }, "lastTriggeredAt": "2026-07-27T13:00:01.006Z", "lastTriggerExecutionId": "7f3c1e08-2b64-4a95-8d17-5e0a9c3b6f21", "triggerCount": 43, "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "metadata": {}, "createdAt": "2026-06-14T09:20:03.512Z", "updatedAt": "2026-07-27T13:00:01.006Z" } ] } } } } }, "summary": "List triggers", "tags": [ "Triggers" ] } }, "/triggers/bulk/delete": { "post": { "description": "Deletes each id independently: one failure does not abort the rest, so the response is a tally. Ids that do not resolve to a trigger in this organization are skipped and counted in neither total. Requires the `workflows:admin` permission.", "operationId": "TriggersController.bulkDelete", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeleteTriggersDto" }, "examples": { "twoTriggers": { "summary": "Delete two triggers", "value": { "ids": [ "9c2f1b40-7e83-4a51-b0d7-2f1c6e94a8d3", "e07a5d61-4b28-4f9c-a3d5-8c19b7e02f4a" ] } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeleteTriggersResponseDto" }, "example": { "deleted": 2, "failed": 0 } } } } }, "summary": "Delete triggers in bulk", "tags": [ "Triggers" ] } }, "/triggers/bulk/enabled": { "post": { "description": "Sets every listed trigger to the requested state. Triggers already in that state count as updated, so the tally matches what the caller asked for. Per-trigger failures do not abort the batch. Requires the `workflows:admin` permission.", "operationId": "TriggersController.bulkUpdateEnabled", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkUpdateTriggersEnabledDto" }, "examples": { "disable": { "summary": "Disable two triggers", "value": { "ids": [ "9c2f1b40-7e83-4a51-b0d7-2f1c6e94a8d3", "e07a5d61-4b28-4f9c-a3d5-8c19b7e02f4a" ], "enabled": false } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkUpdateTriggersEnabledResponseDto" }, "example": { "updated": 2, "failed": 0 } } } } }, "summary": "Enable or disable triggers in bulk", "tags": [ "Triggers" ] } }, "/triggers/types/list": { "get": { "description": "The trigger types available when creating a trigger. Several ids map to the same stored `type`: every event provider is stored as `event`.", "operationId": "TriggersController.getTriggerTypes", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerTypeListResponseDto" }, "example": { "types": [ { "id": "webhook", "type": "webhook", "provider": null, "label": "Webhook", "icon": "webhook", "description": "Trigger workflow via HTTP request" }, { "id": "schedule", "type": "schedule", "provider": null, "label": "Schedule", "icon": "schedule", "description": "Trigger workflow on a schedule (cron)" }, { "id": "form", "type": "form", "provider": null, "label": "Form", "icon": "dynamic_form", "description": "Create a public form or chat interface that triggers this workflow" } ] } } } } }, "summary": "List trigger types", "tags": [ "Triggers" ] } }, "/triggers/types/{typeId}/schema": { "get": { "description": "JSON Schema for one trigger type’s configuration, plus the defaults to start from. `typeId` is an `id` from the trigger-types list, not the stored `type`.", "operationId": "TriggersController.getTriggerTypeSchema", "parameters": [ { "name": "typeId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerTypeSchemaResponseDto" }, "example": { "id": "schedule", "type": "schedule", "provider": null, "label": "Schedule", "icon": "schedule", "description": "Trigger workflow on a schedule (cron)", "schema": { "type": "object", "properties": { "cron": { "type": "string", "minLength": 1, "title": "Cron Expression", "description": "When to run this workflow", "x-hint": "e.g., \"0 9 * * *\" for daily at 9am UTC" }, "timezone": { "type": "string", "default": "UTC", "title": "Timezone", "description": "Timezone for the schedule" } }, "required": [ "cron" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "defaultConfig": { "cron": "0 9 * * *", "timezone": "UTC" } } } } }, "404": { "description": "Unknown trigger type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerErrorResponseDto" } } } } }, "summary": "Get the config schema for a trigger type", "tags": [ "Triggers" ] } }, "/triggers/{id}": { "delete": { "description": "Removes the trigger and, for schedule triggers, the schedule behind it. Requires the `workflows:admin` permission.", "operationId": "TriggersController.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteTriggerResponseDto" }, "example": { "id": "9c2f1b40-7e83-4a51-b0d7-2f1c6e94a8d3", "message": "Trigger deleted successfully" } } } }, "404": { "description": "No such trigger in this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerErrorResponseDto" } } } } }, "summary": "Delete a trigger", "tags": [ "Triggers" ] }, "get": { "description": "Returns the trigger with its secrets decrypted, so a webhook secret issued earlier can be read back instead of regenerated.", "operationId": "TriggersController.get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowTriggerResponseDto" }, "example": { "id": "9c2f1b40-7e83-4a51-b0d7-2f1c6e94a8d3", "suid": "p3rq", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "workflowId": "5b8d0f27-91c4-4e6a-8f3b-7d2a1c05e9b6", "type": "webhook", "name": "lead-intake", "orgSuid": "k4v9", "enabled": true, "config": { "webhook": { "path": "w_1a2b3c4d5e6f", "method": "POST", "authType": "token", "secret": "whs_example_placeholder_not_a_real_secret", "timeout": 30000 } }, "webhookUrl": "https://run.quickflo.app/w/@k4v9/lead-intake", "lastTriggeredAt": "2026-07-27T15:58:02.104Z", "lastTriggerExecutionId": "d41f8b6c-3a92-4c17-9e58-6b0d2f7a1c34", "triggerCount": 148, "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "metadata": {}, "createdAt": "2026-06-14T09:12:44.771Z", "updatedAt": "2026-07-27T15:58:02.104Z" } } } }, "404": { "description": "No such trigger in this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerErrorResponseDto" } } } } }, "summary": "Get a trigger", "tags": [ "Triggers" ] }, "patch": { "description": "Partial update: only the fields you send are touched. Toggling `enabled` or editing the config of a schedule trigger re-syncs the underlying schedule, so a disabled schedule really does stop firing. Requires the `workflows:admin` permission.", "operationId": "TriggersController.update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTriggerDto" }, "examples": { "disable": { "summary": "Disable a trigger", "value": { "enabled": false } }, "rename": { "summary": "Rename", "value": { "name": "lead-intake-v2" } }, "reschedule": { "summary": "Change a schedule", "value": { "config": { "schedule": { "cron": "30 6 * * 1-5", "timezone": "America/New_York" } } } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowTriggerResponseDto" }, "example": { "id": "9c2f1b40-7e83-4a51-b0d7-2f1c6e94a8d3", "suid": "p3rq", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "workflowId": "5b8d0f27-91c4-4e6a-8f3b-7d2a1c05e9b6", "type": "webhook", "name": "lead-intake", "orgSuid": "k4v9", "enabled": false, "config": { "webhook": { "path": "w_1a2b3c4d5e6f", "method": "POST", "authType": "token", "secret": "whs_example_placeholder_not_a_real_secret", "timeout": 30000 } }, "webhookUrl": "https://run.quickflo.app/w/@k4v9/lead-intake", "lastTriggeredAt": "2026-07-27T15:58:02.104Z", "lastTriggerExecutionId": "d41f8b6c-3a92-4c17-9e58-6b0d2f7a1c34", "triggerCount": 148, "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "metadata": {}, "createdAt": "2026-06-14T09:12:44.771Z", "updatedAt": "2026-07-27T15:58:02.104Z" } } } }, "400": { "description": "Another trigger in the organization already uses that name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerErrorResponseDto" } } } }, "404": { "description": "No such trigger in this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerErrorResponseDto" } } } } }, "summary": "Update a trigger", "tags": [ "Triggers" ] } }, "/workflows": { "get": { "description": "Workflows in the active organization. Sub-workflows pulled in as a dependency of a package you installed are hidden from the browse list: fetch one by id or name to see it.", "operationId": "WorkflowTemplateController.list", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowListResponseDto" }, "example": { "total": 1, "data": [ { "id": "8b2e5c17-9a44-4d6f-b0c3-71e5a9d28f60", "suid": "w7q2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Nightly order sync", "description": "Pulls yesterday’s orders and writes them to the data store.", "definition": { "name": "Nightly order sync", "initial": { "since": "2026-07-26T00:00:00.000Z" }, "steps": [ { "stepId": "fetch-orders", "stepType": "core.http", "input": { "method": "GET", "url": "https://api.example.com/orders?since={{ initial.since }}" } } ], "options": { "stopOnError": true, "executionMode": "auto" } }, "isTemplate": false, "tags": [ "orders", "nightly" ], "usedActionTypes": [ "core.http" ], "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } ] } } } } }, "summary": "List workflows", "tags": [ "Workflows" ] }, "post": { "description": "Saves a workflow definition. The definition is validated first: errors reject the save, warnings come back on the saved workflow under `validationWarnings`. The top-level `name` wins over any name inside the definition.", "operationId": "WorkflowTemplateController.create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkflowTemplateBodyDto" }, "examples": { "oneStep": { "summary": "One HTTP step", "value": { "name": "Nightly order sync", "description": "Pulls yesterday’s orders into the data store.", "tags": [ "orders" ], "definition": { "name": "Nightly order sync", "steps": [ { "stepId": "fetch-orders", "stepType": "core.http", "input": { "method": "GET", "url": "https://api.example.com/orders" } } ] } } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowSaveResponseDto" }, "example": { "id": "8b2e5c17-9a44-4d6f-b0c3-71e5a9d28f60", "suid": "w7q2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Nightly order sync", "description": "Pulls yesterday’s orders and writes them to the data store.", "definition": { "name": "Nightly order sync", "initial": { "since": "2026-07-26T00:00:00.000Z" }, "steps": [ { "stepId": "fetch-orders", "stepType": "core.http", "input": { "method": "GET", "url": "https://api.example.com/orders?since={{ initial.since }}" } } ], "options": { "stopOnError": true, "executionMode": "auto" } }, "isTemplate": false, "tags": [ "orders", "nightly" ], "usedActionTypes": [ "core.http" ], "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z", "validationWarnings": [ { "ruleId": "connection-ref", "severity": "warning", "stepId": "fetch-orders", "message": "Connection \"orders-api\" does not exist in this organization. The step will fail at run time unless it is created first." } ] } } } }, "400": { "description": "Validation failed, or a plan limit was hit. The body carries a `validationErrors` array alongside the message so a client can highlight the offending steps without parsing prose." }, "403": { "description": "The definition contains a step that writes to a QuickFlo entity the caller has no permission for." } }, "summary": "Create a workflow", "tags": [ "Workflows" ] } }, "/workflows/bulk/delete": { "post": { "description": "Deletes each workflow you can reach and removes its triggers. Ids you cannot reach are skipped rather than rejected, so compare `deleted` against the number of ids you sent.", "operationId": "WorkflowTemplateController.bulkDelete", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeleteWorkflowsDto" }, "examples": { "two": { "summary": "Two workflows", "value": { "ids": [ "8b2e5c17-9a44-4d6f-b0c3-71e5a9d28f60", "d4a01f83-2c69-4e57-8b1a-5f3c7e90a2d1" ] } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDeleteResponseDto" }, "example": { "deleted": 2 } } } } }, "summary": "Delete workflows in bulk", "tags": [ "Workflows" ] } }, "/workflows/bulk/tags": { "post": { "description": "`set` replaces the tag list, `add` merges without duplicating, `remove` subtracts. Ids you cannot reach are skipped.", "operationId": "WorkflowTemplateController.bulkUpdateTags", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkUpdateTagsDto" }, "examples": { "add": { "summary": "Add a tag without disturbing existing ones", "value": { "ids": [ "8b2e5c17-9a44-4d6f-b0c3-71e5a9d28f60" ], "tags": [ "nightly" ], "mode": "add" } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkUpdateTagsResponseDto" }, "example": { "updated": 1 } } } } }, "summary": "Retag workflows in bulk", "tags": [ "Workflows" ] } }, "/workflows/steps/info": { "get": { "description": "The step catalog available to your organization: gated steps are omitted unless the organization has them enabled. Narrow the payload with `?fields=stepType,description` or `?types=core.http,core.if`. `exampleInput` is omitted unless you ask for it by name: use `GET /workflows/steps/info/{type}` for one step with its example.", "operationId": "WorkflowsController.listSteps", "parameters": [ { "name": "fields", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "types", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StepCatalogResponseDto" }, "example": { "total": 1, "filters": { "types": "core.http" }, "steps": [ { "stepType": "core.http", "description": "Make an HTTP request and return the status, headers and body.", "usageHint": "Use for any REST call that has no dedicated step. Prefer the vendor-specific step when one exists: it handles auth and paging.", "inputSchema": { "type": "object", "required": [ "url" ], "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "DELETE" ] }, "url": { "type": "string" }, "body": { "type": "object" } } }, "outputSchema": { "type": "object", "properties": { "status": { "type": "number" }, "headers": { "type": "object" }, "body": {} } }, "ui": { "icon": "http", "category": "Core" } } ] } } } } }, "summary": "List step types", "tags": [ "Workflows" ] } }, "/workflows/steps/info/{type}": { "get": { "description": "One step with its input and output schemas and a generated `exampleInput`. `?fields=` projects the response down to the keys you name, in which case everything else is absent.", "operationId": "WorkflowsController.getStep", "parameters": [ { "name": "type", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "fields", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StepInfoResponseDto" }, "example": { "stepType": "core.http", "description": "Make an HTTP request and return the status, headers and body.", "usageHint": "Use for any REST call that has no dedicated step. Prefer the vendor-specific step when one exists: it handles auth and paging.", "inputSchema": { "type": "object", "required": [ "url" ], "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "DELETE" ] }, "url": { "type": "string" }, "body": { "type": "object" } } }, "outputSchema": { "type": "object", "properties": { "status": { "type": "number" }, "headers": { "type": "object" }, "body": {} } }, "ui": { "icon": "http", "category": "Core" }, "exampleInput": { "method": "GET", "url": "https://api.example.com/orders" } } } } }, "400": { "description": "No step type by that name is registered." } }, "summary": "Get a step type", "tags": [ "Workflows" ] } }, "/workflows/tags": { "get": { "description": "Every distinct tag in the organization with the number of workflows carrying it, plus a count of workflows with no tags. Backs the tag filter without listing the workflows themselves.", "operationId": "WorkflowTemplateController.getTags", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowTagsResponseDto" }, "example": { "tags": [ { "name": "orders", "count": 12 }, { "name": "nightly", "count": 4 } ], "untaggedCount": 7 } } } } }, "summary": "List workflow tags", "tags": [ "Workflows" ] } }, "/workflows/validate": { "post": { "description": "Checks a definition without running or saving it. Always answers 200 with the same shape, valid or not, so there is one payload to parse. Errors block a save; warnings do not.", "operationId": "WorkflowsController.validateWorkflow", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishedWorkflowDefinitionDto" }, "examples": { "singleStep": { "summary": "One HTTP step", "value": { "name": "Nightly order sync", "initial": { "since": "2026-07-26T00:00:00.000Z" }, "steps": [ { "stepId": "fetch-orders", "stepType": "core.http", "input": { "method": "GET", "url": "https://api.example.com/orders?since={{ initial.since }}" } } ] } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowValidationResponseDto" }, "examples": { "invalid": { "summary": "A step references a name that does not exist", "value": { "ok": false, "errors": [ { "ruleId": "reference-resolution", "severity": "error", "stepId": "store-orders", "message": "Step \"store-orders\" references \"{{ fetch-order.body }}\", which is not a step in this workflow. Did you mean \"fetch-orders\"?" } ], "warnings": [] } }, "valid": { "summary": "Valid, with an advisory warning", "value": { "ok": true, "errors": [], "warnings": [ { "ruleId": "connection-ref", "severity": "warning", "stepId": "fetch-orders", "message": "Connection \"orders-api\" does not exist in this organization. The step will fail at run time unless it is created first." } ] } } } } } } }, "summary": "Validate a workflow definition", "tags": [ "Workflows" ] } }, "/workflows/{id}": { "delete": { "description": "Deletes the workflow and its triggers, and returns the workflow as it was. Permanent: there is no undelete, so export the definition first if you may want it back.", "operationId": "WorkflowTemplateController.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowResponseDto" }, "example": { "id": "8b2e5c17-9a44-4d6f-b0c3-71e5a9d28f60", "suid": "w7q2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Nightly order sync", "description": "Pulls yesterday’s orders and writes them to the data store.", "definition": { "name": "Nightly order sync", "initial": { "since": "2026-07-26T00:00:00.000Z" }, "steps": [ { "stepId": "fetch-orders", "stepType": "core.http", "input": { "method": "GET", "url": "https://api.example.com/orders?since={{ initial.since }}" } } ], "options": { "stopOnError": true, "executionMode": "auto" } }, "isTemplate": false, "tags": [ "orders", "nightly" ], "usedActionTypes": [ "core.http" ], "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } } } }, "404": { "description": "No such workflow, or it belongs to another organization." } }, "summary": "Delete a workflow", "tags": [ "Workflows" ] }, "get": { "operationId": "WorkflowTemplateController.get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowResponseDto" }, "example": { "id": "8b2e5c17-9a44-4d6f-b0c3-71e5a9d28f60", "suid": "w7q2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Nightly order sync", "description": "Pulls yesterday’s orders and writes them to the data store.", "definition": { "name": "Nightly order sync", "initial": { "since": "2026-07-26T00:00:00.000Z" }, "steps": [ { "stepId": "fetch-orders", "stepType": "core.http", "input": { "method": "GET", "url": "https://api.example.com/orders?since={{ initial.since }}" } } ], "options": { "stopOnError": true, "executionMode": "auto" } }, "isTemplate": false, "tags": [ "orders", "nightly" ], "usedActionTypes": [ "core.http" ], "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z" } } } }, "404": { "description": "No such workflow, or it belongs to another organization." } }, "summary": "Get a workflow", "tags": [ "Workflows" ] }, "patch": { "description": "Partial update. Omitting `definition` keeps the stored one intact, so a rename does not require resending every step. Same validation as create: errors reject the save, warnings ride back on the response.", "operationId": "WorkflowTemplateController.update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWorkflowTemplateBodyDto" }, "examples": { "rename": { "summary": "Rename", "value": { "name": "Hourly order sync" } }, "retag": { "summary": "Replace the tag list", "value": { "tags": [ "orders", "hourly" ] } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowSaveResponseDto" }, "example": { "id": "8b2e5c17-9a44-4d6f-b0c3-71e5a9d28f60", "suid": "w7q2", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Hourly order sync", "description": "Pulls yesterday’s orders and writes them to the data store.", "definition": { "name": "Nightly order sync", "initial": { "since": "2026-07-26T00:00:00.000Z" }, "steps": [ { "stepId": "fetch-orders", "stepType": "core.http", "input": { "method": "GET", "url": "https://api.example.com/orders?since={{ initial.since }}" } } ], "options": { "stopOnError": true, "executionMode": "auto" } }, "isTemplate": false, "tags": [ "orders", "nightly" ], "usedActionTypes": [ "core.http" ], "createdAt": "2026-07-27T16:04:11.482Z", "updatedAt": "2026-07-27T16:04:11.482Z", "validationWarnings": [ { "ruleId": "connection-ref", "severity": "warning", "stepId": "fetch-orders", "message": "Connection \"orders-api\" does not exist in this organization. The step will fail at run time unless it is created first." } ] } } } }, "400": { "description": "Validation failed, or a plan limit was hit. The body carries a `validationErrors` array alongside the message." }, "403": { "description": "The definition contains a step that writes to a QuickFlo entity the caller has no permission for." }, "404": { "description": "No such workflow, or it belongs to another organization." } }, "summary": "Update a workflow", "tags": [ "Workflows" ] } }, "/workflows/{id}/execute": { "post": { "description": "Queued for background execution by default: pass `?mode=sync` to wait for the result. Step output is omitted unless `show` names the steps you want back, so a run over a large dataset does not return the dataset. `environment` overrides the environment for this run only, without changing the saved workflow.", "operationId": "WorkflowTemplateController.execute", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "mode", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "show", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "hide", "required": true, "in": "query", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "initial": { "type": "object", "additionalProperties": true, "description": "Values for the workflow's initial data, readable in steps as `{{ initial.field }}`. Replaces the saved defaults." }, "environment": { "type": "string", "description": "Environment whose variables `{{ $env.* }}` resolve against, for this run only." } } }, "examples": { "withInitial": { "summary": "Supply initial data", "value": { "initial": { "since": "2026-07-26T00:00:00.000Z" } } }, "againstStaging": { "summary": "Run against a different environment", "value": { "initial": {}, "environment": "staging" } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRunResponseDto" }, "examples": { "queued": { "summary": "Queued (default)", "value": { "status": "queued", "executionId": "c1d9f3a4-6b27-4f80-9e15-2a7d40b8c613" } }, "completed": { "summary": "Completed (?mode=sync&show=fetch-orders)", "value": { "output": { "fetch-orders": { "$meta": { "success": true, "skipped": false, "stepType": "core.http", "durationMilliseconds": 412, "error": null }, "status": 200, "body": { "orders": [ { "id": "ord_1042", "total": 89.5 } ] } } }, "success": true, "metadata": { "executionId": "c1d9f3a4-6b27-4f80-9e15-2a7d40b8c613", "workflowName": "Nightly order sync", "workflowId": "8b2e5c17-9a44-4d6f-b0c3-71e5a9d28f60", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "startedAt": "2026-07-27T16:04:11.482Z", "completedSteps": [ "fetch-orders" ], "warnings": [], "errors": [] }, "error": null, "metrics": { "totalDurationMilliseconds": 604, "totalSteps": 1, "stepsExecuted": 1, "stepsFailed": 0, "stepsSkipped": 0 } } } } } } }, "404": { "description": "No such workflow, or it belongs to another organization." } }, "summary": "Run a saved workflow", "tags": [ "Workflows" ] } }, "/workflows/{workflowId}/triggers": { "get": { "description": "Every trigger attached to this workflow. `total` counts the triggers in this response, so a paged request reports the page size rather than the full match count.", "operationId": "WorkflowTriggersController.list", "parameters": [ { "name": "workflowId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowTriggerListResponseDto" }, "example": { "total": 2, "data": [ { "id": "9c2f1b40-7e83-4a51-b0d7-2f1c6e94a8d3", "suid": "p3rq", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "workflowId": "5b8d0f27-91c4-4e6a-8f3b-7d2a1c05e9b6", "type": "webhook", "name": "lead-intake", "orgSuid": "k4v9", "enabled": true, "config": { "webhook": { "path": "w_1a2b3c4d5e6f", "method": "POST", "authType": "token", "secret": "whs_example_placeholder_not_a_real_secret", "timeout": 30000 } }, "webhookUrl": "https://run.quickflo.app/w/@k4v9/lead-intake", "lastTriggeredAt": "2026-07-27T15:58:02.104Z", "lastTriggerExecutionId": "d41f8b6c-3a92-4c17-9e58-6b0d2f7a1c34", "triggerCount": 148, "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "metadata": {}, "createdAt": "2026-06-14T09:12:44.771Z", "updatedAt": "2026-07-27T15:58:02.104Z" }, { "id": "e07a5d61-4b28-4f9c-a3d5-8c19b7e02f4a", "suid": "z8ta", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "workflowId": "2c6e9a13-5f47-4d8b-b1e0-9a3f7c25d804", "type": "schedule", "name": "nightly-sync", "orgSuid": "k4v9", "enabled": true, "config": { "schedule": { "cron": "0 9 * * *", "timezone": "America/New_York", "environment": "production", "qstashScheduleId": "scd_example_1a2b3c", "initialData": { "reportType": "daily" } } }, "lastTriggeredAt": "2026-07-27T13:00:01.006Z", "lastTriggerExecutionId": "7f3c1e08-2b64-4a95-8d17-5e0a9c3b6f21", "triggerCount": 43, "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "metadata": {}, "createdAt": "2026-06-14T09:20:03.512Z", "updatedAt": "2026-07-27T13:00:01.006Z" } ] } } } } }, "summary": "List a workflow’s triggers", "tags": [ "Triggers" ] }, "post": { "description": "Attaches a trigger to a workflow. `config` must carry the block that matches `type`. Token-authenticated webhooks are issued a secret when you do not supply one, and schedule triggers register their schedule as part of creation. Requires the `workflows:admin` permission.", "operationId": "WorkflowTriggersController.create", "parameters": [ { "name": "workflowId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTriggerDto" }, "examples": { "webhook": { "summary": "Token-authenticated webhook", "value": { "type": "webhook", "name": "lead-intake", "config": { "webhook": { "method": "POST", "authType": "token" } } } }, "schedule": { "summary": "Weekday morning schedule", "value": { "type": "schedule", "name": "nightly-sync", "config": { "schedule": { "cron": "0 9 * * *", "timezone": "America/New_York", "initialData": { "reportType": "daily" } } } } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowTriggerResponseDto" }, "example": { "id": "9c2f1b40-7e83-4a51-b0d7-2f1c6e94a8d3", "suid": "p3rq", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "workflowId": "5b8d0f27-91c4-4e6a-8f3b-7d2a1c05e9b6", "type": "webhook", "name": "lead-intake", "orgSuid": "k4v9", "enabled": true, "config": { "webhook": { "path": "w_1a2b3c4d5e6f", "method": "POST", "authType": "token", "secret": "whs_example_placeholder_not_a_real_secret", "timeout": 30000 } }, "webhookUrl": "https://run.quickflo.app/w/@k4v9/lead-intake", "lastTriggeredAt": "2026-07-27T15:58:02.104Z", "lastTriggerExecutionId": "d41f8b6c-3a92-4c17-9e58-6b0d2f7a1c34", "triggerCount": 148, "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "metadata": {}, "createdAt": "2026-06-14T09:12:44.771Z", "updatedAt": "2026-07-27T15:58:02.104Z" } } } }, "400": { "description": "Config does not match the trigger type, or the name is already taken in this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerErrorResponseDto" } } } } }, "summary": "Create a trigger", "tags": [ "Triggers" ] } }, "/workflows/{workflowId}/triggers/{id}": { "delete": { "description": "Removes the trigger and, for schedule triggers, the schedule behind it. Requires the `workflows:admin` permission.", "operationId": "WorkflowTriggersController.delete", "parameters": [ { "name": "workflowId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteTriggerResponseDto" }, "example": { "id": "9c2f1b40-7e83-4a51-b0d7-2f1c6e94a8d3", "message": "Trigger deleted successfully" } } } }, "404": { "description": "No such trigger on this workflow.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerErrorResponseDto" } } } } }, "summary": "Delete a trigger", "tags": [ "Triggers" ] }, "get": { "description": "Returns the trigger with its secrets decrypted. 404s if the trigger exists but belongs to a different workflow.", "operationId": "WorkflowTriggersController.get", "parameters": [ { "name": "workflowId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowTriggerResponseDto" }, "example": { "id": "9c2f1b40-7e83-4a51-b0d7-2f1c6e94a8d3", "suid": "p3rq", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "workflowId": "5b8d0f27-91c4-4e6a-8f3b-7d2a1c05e9b6", "type": "webhook", "name": "lead-intake", "orgSuid": "k4v9", "enabled": true, "config": { "webhook": { "path": "w_1a2b3c4d5e6f", "method": "POST", "authType": "token", "secret": "whs_example_placeholder_not_a_real_secret", "timeout": 30000 } }, "webhookUrl": "https://run.quickflo.app/w/@k4v9/lead-intake", "lastTriggeredAt": "2026-07-27T15:58:02.104Z", "lastTriggerExecutionId": "d41f8b6c-3a92-4c17-9e58-6b0d2f7a1c34", "triggerCount": 148, "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "metadata": {}, "createdAt": "2026-06-14T09:12:44.771Z", "updatedAt": "2026-07-27T15:58:02.104Z" } } } }, "404": { "description": "No such trigger on this workflow.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerErrorResponseDto" } } } } }, "summary": "Get a trigger", "tags": [ "Triggers" ] }, "patch": { "description": "Partial update: only the fields you send are touched. Toggling `enabled` or editing the config of a schedule trigger re-syncs the underlying schedule, so a disabled schedule really does stop firing. Requires the `workflows:admin` permission.", "operationId": "WorkflowTriggersController.update", "parameters": [ { "name": "workflowId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTriggerDto" }, "examples": { "disable": { "summary": "Disable a trigger", "value": { "enabled": false } }, "rename": { "summary": "Rename", "value": { "name": "lead-intake-v2" } }, "reschedule": { "summary": "Change a schedule", "value": { "config": { "schedule": { "cron": "30 6 * * 1-5", "timezone": "America/New_York" } } } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowTriggerResponseDto" }, "example": { "id": "9c2f1b40-7e83-4a51-b0d7-2f1c6e94a8d3", "suid": "p3rq", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "workflowId": "5b8d0f27-91c4-4e6a-8f3b-7d2a1c05e9b6", "type": "webhook", "name": "lead-intake", "orgSuid": "k4v9", "enabled": false, "config": { "webhook": { "path": "w_1a2b3c4d5e6f", "method": "POST", "authType": "token", "secret": "whs_example_placeholder_not_a_real_secret", "timeout": 30000 } }, "webhookUrl": "https://run.quickflo.app/w/@k4v9/lead-intake", "lastTriggeredAt": "2026-07-27T15:58:02.104Z", "lastTriggerExecutionId": "d41f8b6c-3a92-4c17-9e58-6b0d2f7a1c34", "triggerCount": 148, "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "metadata": {}, "createdAt": "2026-06-14T09:12:44.771Z", "updatedAt": "2026-07-27T15:58:02.104Z" } } } }, "400": { "description": "Another trigger in the organization already uses that name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerErrorResponseDto" } } } }, "404": { "description": "No such trigger on this workflow.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerErrorResponseDto" } } } } }, "summary": "Update a trigger", "tags": [ "Triggers" ] } }, "/workflows/{workflowId}/triggers/{id}/duplicate": { "post": { "description": "Copies the trigger to `targetWorkflowId`. Credentials are not copied: the duplicate gets its own webhook path and secret, and a schedule trigger gets its own schedule. Requires the `workflows:admin` permission.", "operationId": "WorkflowTriggersController.duplicate", "parameters": [ { "name": "workflowId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicateTriggerBodyDto" }, "examples": { "withName": { "summary": "Copy to another workflow under a new name", "value": { "targetWorkflowId": "2c6e9a13-5f47-4d8b-b1e0-9a3f7c25d804", "name": "lead-intake-staging" } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowTriggerResponseDto" }, "example": { "id": "b56d3e19-08c7-4f2a-9d61-4a7e0c38b512", "suid": "h2wn", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "workflowId": "2c6e9a13-5f47-4d8b-b1e0-9a3f7c25d804", "type": "webhook", "name": "lead-intake-staging", "orgSuid": "k4v9", "enabled": true, "config": { "webhook": { "path": "w_9z8y7x6w5v4u", "method": "POST", "authType": "token", "secret": "whs_example_duplicate_placeholder_secret", "timeout": 30000 } }, "webhookUrl": "https://run.quickflo.app/w/@k4v9/lead-intake-staging", "lastTriggeredAt": null, "triggerCount": 0, "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "metadata": {}, "createdAt": "2026-07-27T16:41:19.883Z", "updatedAt": "2026-07-27T16:41:19.883Z" } } } }, "404": { "description": "No such trigger on this workflow.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerErrorResponseDto" } } } } }, "summary": "Duplicate a trigger onto another workflow", "tags": [ "Triggers" ] } }, "/workflows/{workflowId}/triggers/{id}/pause": { "post": { "description": "Pauses the schedule and disables the trigger, so it stops firing without losing its configuration. Requires the `workflows:admin` permission.", "operationId": "WorkflowTriggersController.pause", "parameters": [ { "name": "workflowId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowTriggerResponseDto" }, "example": { "id": "e07a5d61-4b28-4f9c-a3d5-8c19b7e02f4a", "suid": "z8ta", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "workflowId": "2c6e9a13-5f47-4d8b-b1e0-9a3f7c25d804", "type": "schedule", "name": "nightly-sync", "orgSuid": "k4v9", "enabled": false, "config": { "schedule": { "cron": "0 9 * * *", "timezone": "America/New_York", "environment": "production", "qstashScheduleId": "scd_example_1a2b3c", "initialData": { "reportType": "daily" } } }, "lastTriggeredAt": "2026-07-27T13:00:01.006Z", "lastTriggerExecutionId": "7f3c1e08-2b64-4a95-8d17-5e0a9c3b6f21", "triggerCount": 43, "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "metadata": {}, "createdAt": "2026-06-14T09:20:03.512Z", "updatedAt": "2026-07-27T13:00:01.006Z" } } } }, "404": { "description": "No such trigger on this workflow.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerErrorResponseDto" } } } } }, "summary": "Pause a schedule trigger", "tags": [ "Triggers" ] } }, "/workflows/{workflowId}/triggers/{id}/regenerate-secret": { "post": { "description": "Issues a new signing secret for a webhook trigger and returns the trigger with the new secret in `config.webhook.secret`. The old secret stops working immediately, so update callers before rotating. Requires the `workflows:admin` permission.", "operationId": "WorkflowTriggersController.regenerateSecret", "parameters": [ { "name": "workflowId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegenerateTriggerSecretResponseDto" }, "example": { "id": "9c2f1b40-7e83-4a51-b0d7-2f1c6e94a8d3", "suid": "p3rq", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "workflowId": "5b8d0f27-91c4-4e6a-8f3b-7d2a1c05e9b6", "type": "webhook", "name": "lead-intake", "orgSuid": "k4v9", "enabled": true, "config": { "webhook": { "path": "w_1a2b3c4d5e6f", "method": "POST", "authType": "token", "secret": "whs_example_rotated_placeholder_secret", "timeout": 30000 } }, "webhookUrl": "https://run.quickflo.app/w/@k4v9/lead-intake", "lastTriggeredAt": "2026-07-27T15:58:02.104Z", "lastTriggerExecutionId": "d41f8b6c-3a92-4c17-9e58-6b0d2f7a1c34", "triggerCount": 148, "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "metadata": {}, "createdAt": "2026-06-14T09:12:44.771Z", "updatedAt": "2026-07-27T15:58:02.104Z", "message": "Secret regenerated successfully. Save this secret now - it will be encrypted after this response." } } } }, "404": { "description": "No such trigger on this workflow.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerErrorResponseDto" } } } } }, "summary": "Regenerate a webhook secret", "tags": [ "Triggers" ] } }, "/workflows/{workflowId}/triggers/{id}/resume": { "post": { "description": "Resumes a paused schedule and re-enables the trigger. Requires the `workflows:admin` permission.", "operationId": "WorkflowTriggersController.resume", "parameters": [ { "name": "workflowId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowTriggerResponseDto" }, "example": { "id": "e07a5d61-4b28-4f9c-a3d5-8c19b7e02f4a", "suid": "z8ta", "organizationId": "3f7c1a92-5d3e-4b18-9f21-0c6a8e2d4471", "workflowId": "2c6e9a13-5f47-4d8b-b1e0-9a3f7c25d804", "type": "schedule", "name": "nightly-sync", "orgSuid": "k4v9", "enabled": true, "config": { "schedule": { "cron": "0 9 * * *", "timezone": "America/New_York", "environment": "production", "qstashScheduleId": "scd_example_1a2b3c", "initialData": { "reportType": "daily" } } }, "lastTriggeredAt": "2026-07-27T13:00:01.006Z", "lastTriggerExecutionId": "7f3c1e08-2b64-4a95-8d17-5e0a9c3b6f21", "triggerCount": 43, "userId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "metadata": {}, "createdAt": "2026-06-14T09:20:03.512Z", "updatedAt": "2026-07-27T13:00:01.006Z" } } } }, "404": { "description": "No such trigger on this workflow.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerErrorResponseDto" } } } } }, "summary": "Resume a schedule trigger", "tags": [ "Triggers" ] } } }, "info": { "title": "QuickFlo API", "description": "The QuickFlo REST API. Every endpoint here is reachable with a personal\naccess token, so anything the product does can be driven from a script,\na CI job, or an agent.\n\n### Creating a token\n\n1. Switch to the organization you want the token to act on. A token is\n scoped to whichever organization is active when you create it, and\n cannot be moved afterwards.\n2. Go to **Account Settings → Access Tokens**.\n3. Choose **New token**.\n\nThen send it as a bearer token on every request:\n\n```\nAuthorization: Bearer \n```\n\nA token carries the permissions of the user who created it, limited to that\none organization — so it can only ever see the organization it belongs to.\nTo work across several organizations, create a token in each.\n\nEvery endpoint in this reference is callable with a token. Actions that\nrequire a signed-in human instead — deleting an organization, for one — are\ndeliberately not listed here.", "version": "1.116.1", "contact": {} }, "tags": [ { "name": "Workflows", "description": "Create, read, update and delete workflows, and run them on demand." }, { "name": "Triggers", "description": "Start workflows from webhooks, schedules, forms, chat and platform events." }, { "name": "Executions", "description": "Inspect workflow runs: status, step-by-step output, cancellation and trace downloads." }, { "name": "Logs", "description": "Search execution logs across workflows." }, { "name": "Connections", "description": "Credentials and endpoints workflow steps authenticate against." }, { "name": "Environments", "description": "Named variable sets a workflow reads at run time, so one definition can run against dev and prod." }, { "name": "Data Stores", "description": "Tabular storage workflows read and write, queryable from dashboards." }, { "name": "Knowledge Bases", "description": "Document collections AI steps retrieve against." }, { "name": "Dashboards", "description": "Dashboards, their widgets, the data sources behind them, and the analytics query surface." }, { "name": "Packages", "description": "Publish, version and share bundles of workflows, connections and dashboards." }, { "name": "Organizations", "description": "Create and manage organizations. Deleting one requires a signed-in owner, not a token." }, { "name": "Partners", "description": "Provision and manage the child organizations a partner bills for: create them, assign plans, activate or deactivate them, mint tokens that act on their behalf, and take or release a seat in one." } ], "servers": [ { "url": "https://go.quickflo.app/api", "description": "Production" } ], "components": { "securitySchemes": { "accessToken": { "scheme": "bearer", "bearerFormat": "JWT", "type": "http", "description": "Personal access token, created per organization in Settings." } }, "schemas": { "EnvironmentListResponseDto": { "type": "object", "properties": { "total": { "description": "Total records matching the filter, ignoring paging.", "type": "number" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Owning organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "name": { "description": "Unique per organization, and the stable way to target an environment: a workflow exported from one organization finds `production` in the next one, but never finds the source organization’s id.", "type": "string" }, "userId": { "description": "User who created the environment.", "type": "string", "nullable": true }, "metadata": { "description": "Unused by the platform; empty by default.", "type": "object", "additionalProperties": {} }, "variables": { "description": "Every variable in the environment, with values still encrypted.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Owning organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "key": { "description": "Variable name. Workflows read it as `{{ $env.KEY }}`.", "type": "string" }, "encryptedValue": { "description": "Stored ciphertext, not the value: an AES-256-GCM envelope serialized as JSON (`version`, `iv`, `data`, `tag`). Opaque to callers — read the plaintext from `GET /environments/{id}/variables`.", "type": "string" }, "environment": { "description": "Id of the environment this variable belongs to.", "type": "string" }, "userId": { "description": "User who created the variable.", "type": "string", "nullable": true }, "metadata": { "description": "Unused by the platform; empty by default.", "type": "object", "additionalProperties": {} } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "key", "encryptedValue", "environment", "userId", "metadata" ] } } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "name", "userId", "metadata", "variables" ] } } }, "required": [ "total", "data" ] }, "CreateEnvironmentDto": { "type": "object", "properties": { "organizationId": { "type": "string", "format": "uuid" }, "userId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {} }, "updatedAt": {}, "createdAt": {}, "name": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[a-zA-Z_][a-zA-Z0-9_-]*$" }, "variables": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 255 }, "value": { "type": "string", "maxLength": 10000 } }, "required": [ "key", "value" ] }, "default": [] } }, "required": [ "name" ] }, "EnvironmentResponseDto": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Owning organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "name": { "description": "Unique per organization, and the stable way to target an environment: a workflow exported from one organization finds `production` in the next one, but never finds the source organization’s id.", "type": "string" }, "userId": { "description": "User who created the environment.", "type": "string", "nullable": true }, "metadata": { "description": "Unused by the platform; empty by default.", "type": "object", "additionalProperties": {} }, "variables": { "description": "Every variable in the environment, with values still encrypted.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Owning organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "key": { "description": "Variable name. Workflows read it as `{{ $env.KEY }}`.", "type": "string" }, "encryptedValue": { "description": "Stored ciphertext, not the value: an AES-256-GCM envelope serialized as JSON (`version`, `iv`, `data`, `tag`). Opaque to callers — read the plaintext from `GET /environments/{id}/variables`.", "type": "string" }, "environment": { "description": "Id of the environment this variable belongs to.", "type": "string" }, "userId": { "description": "User who created the variable.", "type": "string", "nullable": true }, "metadata": { "description": "Unused by the platform; empty by default.", "type": "object", "additionalProperties": {} } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "key", "encryptedValue", "environment", "userId", "metadata" ] } } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "name", "userId", "metadata", "variables" ] }, "UpsertVariableBodyDto": { "type": "object", "properties": { "value": { "description": "Plaintext value. Encrypted at rest on write.", "type": "string", "maxLength": 10000 } }, "required": [ "value" ] }, "BulkDeleteVariablesBodyDto": { "type": "object", "properties": { "keys": { "description": "Variable names to remove. Names that do not exist are ignored.", "type": "array", "items": { "type": "string" } } }, "required": [ "keys" ] }, "BulkUpsertVariablesBodyDto": { "type": "object", "properties": { "variables": { "description": "Variables to create or overwrite. Keys not listed are left alone.", "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "maxLength": 255 }, "value": { "type": "string", "maxLength": 10000 } }, "required": [ "key", "value" ] } } }, "required": [ "variables" ] }, "UpdateEnvironmentDto": { "type": "object", "properties": { "userId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {} }, "updatedAt": {}, "createdAt": {}, "name": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[a-zA-Z_][a-zA-Z0-9_-]*$" }, "variables": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 255 }, "value": { "type": "string", "maxLength": 10000 } }, "required": [ "key", "value" ] }, "default": [] } } }, "DataStoreTablesListResponseDto": { "type": "object", "properties": { "tables": { "type": "array", "items": { "type": "object", "properties": { "tableName": { "type": "string" }, "keyCount": { "description": "Records in the table, excluding the reserved `__meta__` marker. Read live from analytics storage for tables whose records have been shipped there.", "type": "number" }, "analyticsTag": { "description": "Label that groups the table for dashboards. Absent when untagged.", "type": "string" } }, "required": [ "tableName", "keyCount" ] } }, "total": { "description": "Total tables in the organization, ignoring paging.", "type": "number" }, "hasMore": { "description": "Whether a further page exists past this one.", "type": "boolean" } }, "required": [ "tables", "total", "hasMore" ] }, "CreateDataStoreTableBodyDto": { "type": "object", "properties": { "tableName": { "description": "Name of the table to create. Reused verbatim in read and write paths.", "type": "string" } }, "required": [ "tableName" ] }, "DataStoreCreateTableResponseDto": { "type": "object", "properties": { "tableName": { "type": "string" }, "created": { "description": "False when the table already existed. The call is idempotent, not an error.", "type": "boolean" } }, "required": [ "tableName", "created" ] }, "DataStoreEntriesListResponseDto": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Row id. Records served from analytics storage carry their `key` here instead of a row uuid.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Owning organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "tableName": { "description": "Table the record belongs to.", "type": "string" }, "key": { "description": "Unique key within the table.", "type": "string" }, "value": { "description": "The stored value. Caller-defined: an object, an array, or a primitive. The platform imposes no columns.", "oneOf": [ { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} }, { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "expiresAt": { "description": "ISO 8601 timestamp.", "type": "string", "nullable": true }, "recordTimestamp": { "description": "ISO 8601 timestamp.", "type": "string", "nullable": true } }, "required": [ "id", "organizationId", "createdAt", "updatedAt", "tableName", "key", "value" ] } }, "total": { "description": "Total records matching the filter, ignoring paging.", "type": "number" }, "hasMore": { "description": "Whether a further page exists past this one.", "type": "boolean" }, "source": { "description": "Which storage served the page. `clickhouse` means the table ships its records to analytics storage and the operational copy has been swept; the records are the same either way.", "type": "string", "enum": [ "postgres", "clickhouse" ] } }, "required": [ "entries", "total", "hasMore" ] }, "DataStoreEntryResponseDto": { "type": "object", "properties": { "id": { "description": "Row id. Records served from analytics storage carry their `key` here instead of a row uuid.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Owning organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "tableName": { "description": "Table the record belongs to.", "type": "string" }, "key": { "description": "Unique key within the table.", "type": "string" }, "value": { "description": "The stored value. Caller-defined: an object, an array, or a primitive. The platform imposes no columns.", "oneOf": [ { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} }, { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "expiresAt": { "description": "ISO 8601 timestamp.", "type": "string", "nullable": true }, "recordTimestamp": { "description": "ISO 8601 timestamp.", "type": "string", "nullable": true } }, "required": [ "id", "organizationId", "createdAt", "updatedAt", "tableName", "key", "value" ] }, "BulkImportDto": { "type": "object", "properties": { "entries": { "type": "array", "minItems": 1, "maxItems": 50000, "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 1024 }, "value": { "oneOf": [ { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} }, { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "required": [ "key", "value" ] } } }, "required": [ "entries" ] }, "DataStoreImportResponseDto": { "type": "object", "properties": { "total": { "description": "Entries submitted, before deduplication.", "type": "number" }, "created": { "description": "Keys that did not exist and were inserted.", "type": "number" }, "updated": { "description": "Keys that existed and were overwritten.", "type": "number" }, "errors": { "description": "Entries that were skipped. The rest of the import still applied.", "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "error": { "description": "Why this key was skipped, e.g. `Reserved key: __meta__`.", "type": "string" } }, "required": [ "key", "error" ] } } }, "required": [ "total", "created", "updated", "errors" ] }, "BulkDeleteEntriesDto": { "type": "object", "properties": { "keys": { "type": "array", "minItems": 1, "maxItems": 50000, "items": { "type": "string", "minLength": 1, "maxLength": 1024 } } }, "required": [ "keys" ] }, "DataStoreBulkDeleteResponseDto": { "type": "object", "properties": { "deleted": { "description": "Records actually removed.", "type": "number" }, "notFound": { "description": "Keys that matched no record. Not an error: the end state is the one you asked for.", "type": "array", "items": { "type": "string" } }, "errors": { "description": "Keys that were refused, e.g. the reserved `__meta__` marker.", "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "error": { "description": "Why this key was skipped, e.g. `Reserved key: __meta__`.", "type": "string" } }, "required": [ "key", "error" ] } } }, "required": [ "deleted", "notFound", "errors" ] }, "CreateDataStoreEntryDto": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 1024 }, "value": { "oneOf": [ { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} }, { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "ttlSeconds": { "type": "integer", "minimum": 60, "exclusiveMinimum": false, "maximum": 31536000, "exclusiveMaximum": false } }, "required": [ "key", "value" ] }, "UpdateDataStoreAnalyticsTagBodyDto": { "type": "object", "properties": { "analyticsTag": { "description": "Tag to apply. Omit it, or send an empty string, to clear the tag.", "type": "string" } } }, "DataStoreAnalyticsTagResponseDto": { "type": "object", "properties": { "tableName": { "type": "string" }, "analyticsTag": { "description": "The tag now on the table. Absent when the tag was cleared.", "type": "string" } }, "required": [ "tableName" ] }, "UpdateDataStoreEntryDto": { "type": "object", "properties": { "value": { "oneOf": [ { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} }, { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "ttlSeconds": { "type": "integer", "minimum": 60, "exclusiveMinimum": false, "maximum": 31536000, "exclusiveMaximum": false, "nullable": true } }, "required": [ "value" ] }, "DataStoreDeletedCountResponseDto": { "type": "object", "properties": { "deleted": { "description": "Rows removed. Counts the reserved `__meta__` marker alongside the records, so a table holding N records reports N + 1.", "type": "number" } }, "required": [ "deleted" ] }, "DataStoreDeletedFlagResponseDto": { "type": "object", "properties": { "deleted": { "description": "False when no such record existed.", "type": "boolean" } }, "required": [ "deleted" ] }, "DataStoreForgottenFlagResponseDto": { "type": "object", "properties": { "forgotten": { "description": "False when nothing was left to forget. Repeating the call is safe.", "type": "boolean" } }, "required": [ "forgotten" ] }, "DataStoreListResponseDto": { "type": "object", "properties": { "total": { "description": "Total records matching the filter, ignoring paging.", "type": "number" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Row id. Records served from analytics storage carry their `key` here instead of a row uuid.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Owning organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "tableName": { "description": "Table the record belongs to.", "type": "string" }, "key": { "description": "Unique key within the table.", "type": "string" }, "value": { "description": "The stored value. Caller-defined: an object, an array, or a primitive. The platform imposes no columns.", "oneOf": [ { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} }, { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "expiresAt": { "description": "ISO 8601 timestamp.", "type": "string", "nullable": true }, "recordTimestamp": { "description": "ISO 8601 timestamp.", "type": "string", "nullable": true } }, "required": [ "id", "organizationId", "createdAt", "updatedAt", "tableName", "key", "value" ] } } }, "required": [ "total", "data" ] }, "CreateDataStoreDto": { "type": "object", "properties": { "tableName": { "type": "string", "minLength": 1, "maxLength": 255 }, "key": { "type": "string", "minLength": 1, "maxLength": 1024 }, "value": { "oneOf": [ { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} }, { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "required": [ "tableName", "key", "value" ] }, "UpdateDataStoreDto": { "type": "object", "properties": { "value": { "oneOf": [ { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} }, { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "required": [ "value" ] }, "PackageListResponseDto": { "type": "object", "properties": { "total": { "description": "Total records matching the filter, ignoring paging.", "type": "number" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Author organization: the org that publishes this package.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "userId": { "description": "User who created the package.", "type": "string" }, "slug": { "description": "Install address. Public packages must use the canonical `@/` form; private and unlisted packages are addressed by id or install token instead.", "type": "string" }, "name": { "description": "Display name shown in the marketplace.", "type": "string" }, "description": { "type": "string", "nullable": true }, "supportContactEmail": { "description": "Publisher support address shown on the install trust screen.", "type": "string", "nullable": true }, "documentationUrl": { "type": "string", "nullable": true }, "websiteUrl": { "type": "string", "nullable": true }, "icon": { "description": "Either a Material Design icon name (`mdi-package-variant-closed`) or an image URL. Uploading through `POST /packages/{id}/icon` replaces this with a CDN URL.", "type": "string", "nullable": true }, "readme": { "description": "Markdown rendered on the install trust screen. Read live on every preview, so edits reach installers without republishing.", "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "visibility": { "description": "`public` lists the package in the marketplace. `unlisted` hides it but keeps per-version install links working. `private` restricts it to the author organization.", "type": "string", "enum": [ "public", "unlisted", "private" ] }, "latestVersionId": { "description": "Most recently published version, or null before the first publish.", "type": "string", "nullable": true }, "installCount": { "description": "Every install row keyed to this package, including copies pulled in as a dependency of another package. Popularity, not distinct customers.", "type": "number" }, "isVerified": { "description": "Set by QuickFlo staff after review. Not settable by the publisher.", "type": "boolean" }, "hasAgentTools": { "description": "Whether the latest version exposes any workflow as an agent tool.", "type": "boolean" }, "resourceCounts": { "description": "What the latest version ships, by kind. Only non-zero kinds are present.", "type": "object", "properties": { "workflows": { "type": "number" }, "subWorkflows": { "type": "number" }, "triggers": { "type": "number" }, "dataStoreTables": { "type": "number" }, "dashboards": { "type": "number" }, "connectionShapes": { "type": "number" }, "tools": { "type": "number" } } } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "slug", "name", "tags", "visibility", "installCount", "isVerified", "hasAgentTools", "resourceCounts" ] } } }, "required": [ "total", "data" ] }, "CreatePackageDto": { "type": "object", "properties": { "userId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {} }, "slug": { "type": "string", "minLength": 1, "maxLength": 255 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "nullable": true }, "supportContactEmail": { "type": "string", "format": "email", "maxLength": 320, "nullable": true }, "documentationUrl": { "type": "string", "format": "uri", "maxLength": 2048, "nullable": true }, "websiteUrl": { "type": "string", "format": "uri", "maxLength": 2048, "nullable": true }, "icon": { "type": "string", "maxLength": 255, "nullable": true }, "readme": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" }, "default": [] }, "visibility": { "type": "string", "enum": [ "public", "unlisted", "private" ], "default": "private" } }, "required": [ "slug", "name" ] }, "PackageResponseDto": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Author organization: the org that publishes this package.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "userId": { "description": "User who created the package.", "type": "string" }, "slug": { "description": "Install address. Public packages must use the canonical `@/` form; private and unlisted packages are addressed by id or install token instead.", "type": "string" }, "name": { "description": "Display name shown in the marketplace.", "type": "string" }, "description": { "type": "string", "nullable": true }, "supportContactEmail": { "description": "Publisher support address shown on the install trust screen.", "type": "string", "nullable": true }, "documentationUrl": { "type": "string", "nullable": true }, "websiteUrl": { "type": "string", "nullable": true }, "icon": { "description": "Either a Material Design icon name (`mdi-package-variant-closed`) or an image URL. Uploading through `POST /packages/{id}/icon` replaces this with a CDN URL.", "type": "string", "nullable": true }, "readme": { "description": "Markdown rendered on the install trust screen. Read live on every preview, so edits reach installers without republishing.", "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "visibility": { "description": "`public` lists the package in the marketplace. `unlisted` hides it but keeps per-version install links working. `private` restricts it to the author organization.", "type": "string", "enum": [ "public", "unlisted", "private" ] }, "latestVersionId": { "description": "Most recently published version, or null before the first publish.", "type": "string", "nullable": true }, "installCount": { "description": "Every install row keyed to this package, including copies pulled in as a dependency of another package. Popularity, not distinct customers.", "type": "number" }, "isVerified": { "description": "Set by QuickFlo staff after review. Not settable by the publisher.", "type": "boolean" }, "hasAgentTools": { "description": "Whether the latest version exposes any workflow as an agent tool.", "type": "boolean" }, "resourceCounts": { "description": "What the latest version ships, by kind. Only non-zero kinds are present.", "type": "object", "properties": { "workflows": { "type": "number" }, "subWorkflows": { "type": "number" }, "triggers": { "type": "number" }, "dataStoreTables": { "type": "number" }, "dashboards": { "type": "number" }, "connectionShapes": { "type": "number" }, "tools": { "type": "number" } } } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "slug", "name", "tags", "visibility", "installCount", "isVerified", "hasAgentTools", "resourceCounts" ] }, "PackagePreviewRequestDto": { "type": "object", "properties": { "roots": { "type": "array", "minItems": 1, "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "workflow" ] }, "workflowTemplateId": { "type": "string", "minLength": 1 } }, "required": [ "kind", "workflowTemplateId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "sub-workflow" ] }, "workflowTemplateId": { "type": "string", "minLength": 1 } }, "required": [ "kind", "workflowTemplateId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "trigger" ] }, "triggerId": { "type": "string", "minLength": 1 } }, "required": [ "kind", "triggerId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "data-store-table" ] }, "tableName": { "type": "string", "minLength": 1 }, "includeSeedRows": { "type": "boolean" }, "seedRowLimit": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 10000, "exclusiveMaximum": false } }, "required": [ "kind", "tableName" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "dashboard" ] }, "dashboardId": { "type": "string", "minLength": 1 } }, "required": [ "kind", "dashboardId" ] } ] } } }, "required": [ "roots" ] }, "PackageExportPreviewResponseDto": { "type": "object", "properties": { "graph": { "type": "object", "properties": { "nodes": { "description": "Every resource reached from the roots, roots included.", "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "workflow", "sub-workflow", "trigger", "data-store-table", "dashboard" ] }, "name": { "type": "string" }, "isRoot": { "description": "Whether the author selected this resource directly.", "type": "boolean" }, "connections": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "envRefs": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "flat" ] }, "key": { "type": "string" } }, "required": [ "kind", "key" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shared" ] }, "key": { "type": "string" } }, "required": [ "kind", "key" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "user-env" ] }, "envName": { "type": "string" }, "key": { "type": "string" } }, "required": [ "kind", "envName", "key" ] } ] } }, "dataStoreTables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "subWorkflowRefs": { "type": "array", "items": { "type": "object", "properties": { "workflowTemplateId": { "type": "string" }, "workflowTemplateName": { "type": "string" }, "namespace": { "type": "string", "enum": [ "common", "org", "cross-package" ] }, "namespacedSlug": { "type": "string" }, "orgSuid": { "type": "string" }, "packageSlug": { "type": "string" }, "resourceSlug": { "type": "string" } } } }, "dashboardDataSources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } }, "toolPackRefs": { "type": "array", "items": { "type": "object", "properties": { "packageInstallId": { "type": "string" } }, "required": [ "packageInstallId" ] } }, "isAgentTool": { "type": "boolean" } }, "required": [ "kind", "name", "isRoot", "connections", "envRefs", "dataStoreTables", "subWorkflowRefs", "dashboardDataSources", "toolPackRefs" ] } }, "aggregate": { "description": "Deduplicated peer dependencies across every node.", "type": "object", "properties": { "connections": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "envRefs": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "flat" ] }, "key": { "type": "string" } }, "required": [ "kind", "key" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shared" ] }, "key": { "type": "string" } }, "required": [ "kind", "key" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "user-env" ] }, "envName": { "type": "string" }, "key": { "type": "string" } }, "required": [ "kind", "envName", "key" ] } ] } }, "dataStoreTables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] } }, "dashboardDataSources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } }, "toolPackRefs": { "type": "array", "items": { "type": "object", "properties": { "packageInstallId": { "type": "string" } }, "required": [ "packageInstallId" ] } } }, "required": [ "connections", "envRefs", "dataStoreTables", "dashboardDataSources", "toolPackRefs" ] }, "issues": { "type": "array", "items": { "type": "object", "properties": { "severity": { "description": "`error` blocks publish. `warning` needs author review. `info` is handled automatically and needs no action.", "type": "string", "enum": [ "error", "warning", "info" ] }, "code": { "type": "string", "enum": [ "unresolved-sub-workflow", "cross-org-sub-workflow-ref", "platform-sub-workflow-ref", "user-env-hardcoded", "cross-package-ref", "unknown-data-store-table" ] }, "message": { "type": "string" }, "resourceName": { "type": "string" }, "stepId": { "type": "string" }, "detail": { "type": "object", "additionalProperties": {} } }, "required": [ "severity", "code", "message" ] } } }, "required": [ "nodes", "aggregate", "issues" ] } }, "required": [ "graph" ] }, "PackageResolveResponseDto": { "type": "object", "properties": { "package": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Author organization: the org that publishes this package.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "userId": { "description": "User who created the package.", "type": "string" }, "slug": { "description": "Install address. Public packages must use the canonical `@/` form; private and unlisted packages are addressed by id or install token instead.", "type": "string" }, "name": { "description": "Display name shown in the marketplace.", "type": "string" }, "description": { "type": "string", "nullable": true }, "supportContactEmail": { "description": "Publisher support address shown on the install trust screen.", "type": "string", "nullable": true }, "documentationUrl": { "type": "string", "nullable": true }, "websiteUrl": { "type": "string", "nullable": true }, "icon": { "description": "Either a Material Design icon name (`mdi-package-variant-closed`) or an image URL. Uploading through `POST /packages/{id}/icon` replaces this with a CDN URL.", "type": "string", "nullable": true }, "readme": { "description": "Markdown rendered on the install trust screen. Read live on every preview, so edits reach installers without republishing.", "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "visibility": { "description": "`public` lists the package in the marketplace. `unlisted` hides it but keeps per-version install links working. `private` restricts it to the author organization.", "type": "string", "enum": [ "public", "unlisted", "private" ] }, "latestVersionId": { "description": "Most recently published version, or null before the first publish.", "type": "string", "nullable": true }, "installCount": { "description": "Every install row keyed to this package, including copies pulled in as a dependency of another package. Popularity, not distinct customers.", "type": "number" }, "isVerified": { "description": "Set by QuickFlo staff after review. Not settable by the publisher.", "type": "boolean" }, "hasAgentTools": { "description": "Whether the latest version exposes any workflow as an agent tool.", "type": "boolean" }, "resourceCounts": { "description": "What the latest version ships, by kind. Only non-zero kinds are present.", "type": "object", "properties": { "workflows": { "type": "number" }, "subWorkflows": { "type": "number" }, "triggers": { "type": "number" }, "dataStoreTables": { "type": "number" }, "dashboards": { "type": "number" }, "connectionShapes": { "type": "number" }, "tools": { "type": "number" } } } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "slug", "name", "tags", "visibility", "installCount", "isVerified", "hasAgentTools", "resourceCounts" ] }, "latestVersion": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Author organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "userId": { "description": "User who created the row.", "type": "string" }, "packageId": { "description": "Parent package.", "type": "string" }, "version": { "description": "Semver, for example `1.4.0` or `2.0.0-beta.1`.", "type": "string" }, "manifest": { "description": "Full author-time spec: resources shipped, peer dependencies the installer must satisfy, and extension points.", "type": "object", "properties": { "schemaVersion": { "type": "number", "minimum": 1, "maximum": 1 }, "slug": { "type": "string", "minLength": 1 }, "version": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "icon": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "packageId": { "type": "string", "minLength": 1 }, "authorOrganizationId": { "type": "string", "minLength": 1 }, "authorOrgSuid": { "type": "string", "minLength": 1 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "workflow", "sub-workflow", "trigger", "data-store-table", "connection-shape", "dashboard", "dashboard-data-source" ] }, "name": { "type": "string", "minLength": 1 }, "isRoot": { "type": "boolean" }, "triggerType": { "type": "string", "enum": [ "webhook", "schedule", "manual", "event", "form" ] }, "scheduleCron": { "type": "string" } }, "required": [ "kind", "name" ] } }, "peerDeps": { "type": "object", "properties": { "connections": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "name", "type" ] } }, "env": { "type": "object", "properties": { "required": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "flat" ] }, "key": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "kind", "key" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shared" ] }, "key": { "type": "string", "minLength": 1 }, "default": { "type": "string" }, "description": { "type": "string" } }, "required": [ "kind", "key" ] } ] } }, "optional": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "flat" ] }, "key": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "kind", "key" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shared" ] }, "key": { "type": "string", "minLength": 1 }, "default": { "type": "string" }, "description": { "type": "string" } }, "required": [ "kind", "key" ] } ] } } }, "required": [ "required", "optional" ] }, "dataStoreTables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "shipsSeedData": { "type": "boolean" } }, "required": [ "name" ] } }, "toolPacks": { "type": "array", "items": { "type": "object", "properties": { "alias": { "type": "string", "minLength": 1 }, "packageId": { "type": "string", "minLength": 1 }, "versionRange": { "type": "string" }, "description": { "type": "string" } }, "required": [ "alias", "packageId" ] } } }, "required": [ "connections", "env", "dataStoreTables" ] }, "dependencies": { "type": "array", "items": { "type": "object", "properties": { "packageId": { "type": "string", "minLength": 1 }, "version": { "type": "string", "minLength": 1 } }, "required": [ "packageId", "version" ] } }, "extensionPoints": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "starterSubworkflowRef": { "type": "string", "minLength": 1 }, "required": { "type": "boolean" }, "inputSchema": { "type": "object", "additionalProperties": {} }, "outputSchema": { "type": "object", "additionalProperties": {} } }, "required": [ "name", "label", "starterSubworkflowRef", "required" ] } }, "exports": { "type": "object", "properties": { "tools": { "type": "array", "items": { "type": "object", "properties": { "workflowName": { "type": "string", "minLength": 1 } }, "required": [ "workflowName" ] } } }, "required": [ "tools" ] } }, "required": [ "schemaVersion", "slug", "version", "name", "resources", "peerDeps", "extensionPoints" ] }, "artifactUrl": { "description": "Storage location of the `.qfpkg` archive. Download it through `GET /packages/{id}/versions/{version}/artifact` rather than reading this directly.", "type": "string" }, "artifactDigest": { "description": "SHA-256 of the archive. File-drop installs are verified against it.", "type": "string" }, "summary": { "description": "One-line release title.", "type": "string" }, "releaseNotes": { "description": "Markdown release notes.", "type": "string" }, "publishedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "publishedByUserId": { "type": "string" } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "packageId", "version", "manifest", "publishedAt" ], "nullable": true } }, "required": [ "package", "latestVersion" ] }, "PackageFleetResponseDto": { "type": "object", "properties": { "totals": { "type": "object", "properties": { "distinctOrgs": { "description": "Customer organizations holding at least one direct install.", "type": "number" }, "topLevelInstalls": { "description": "Installs a customer made directly, excluding dependency copies.", "type": "number" }, "totalInstalls": { "description": "Every install row, dependency copies included.", "type": "number" }, "runs": { "description": "Raw execution counts. Rates are left to the caller because the right denominator is a presentation decision.", "type": "object", "properties": { "success": { "type": "number" }, "completedWithErrors": { "type": "number" }, "failed": { "type": "number" }, "cancelled": { "type": "number" }, "rejected": { "type": "number" }, "running": { "type": "number" }, "total": { "description": "Sum of every status.", "type": "number" } }, "required": [ "success", "completedWithErrors", "failed", "cancelled", "rejected", "running", "total" ] }, "windowDays": { "description": "Length of the execution window, in days.", "type": "number" } }, "required": [ "distinctOrgs", "topLevelInstalls", "totalInstalls", "runs", "windowDays" ] }, "byVersion": { "description": "Version adoption across the whole fleet. Never narrowed by the filters.", "type": "array", "items": { "type": "object", "properties": { "versionId": { "type": "string" }, "version": { "type": "string" }, "orgCount": { "description": "Organizations whose most recent install is on this version.", "type": "number" }, "installCount": { "type": "number" }, "runs": { "description": "Raw execution counts. Rates are left to the caller because the right denominator is a presentation decision.", "type": "object", "properties": { "success": { "type": "number" }, "completedWithErrors": { "type": "number" }, "failed": { "type": "number" }, "cancelled": { "type": "number" }, "rejected": { "type": "number" }, "running": { "type": "number" }, "total": { "description": "Sum of every status.", "type": "number" } }, "required": [ "success", "completedWithErrors", "failed", "cancelled", "rejected", "running", "total" ] } }, "required": [ "versionId", "version", "orgCount", "installCount", "runs" ] } }, "rows": { "description": "One row per customer organization, for the requested page.", "type": "array", "items": { "type": "object", "properties": { "organizationId": { "type": "string" }, "organizationName": { "description": "Resolved live. Null when the customer organization was deleted.", "type": "string", "nullable": true }, "organizationSuid": { "type": "string", "nullable": true }, "installedVersionId": { "type": "string" }, "installedVersion": { "type": "string" }, "installCount": { "type": "number" }, "firstInstalledAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "lastInstalledAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "lastRunAt": { "description": "ISO 8601 timestamp, or null when nothing ran in the window.", "type": "string", "nullable": true }, "runs": { "description": "Raw execution counts. Rates are left to the caller because the right denominator is a presentation decision.", "type": "object", "properties": { "success": { "type": "number" }, "completedWithErrors": { "type": "number" }, "failed": { "type": "number" }, "cancelled": { "type": "number" }, "rejected": { "type": "number" }, "running": { "type": "number" }, "total": { "description": "Sum of every status.", "type": "number" } }, "required": [ "success", "completedWithErrors", "failed", "cancelled", "rejected", "running", "total" ] } }, "required": [ "organizationId", "organizationName", "organizationSuid", "installedVersionId", "installedVersion", "installCount", "firstInstalledAt", "lastInstalledAt", "lastRunAt", "runs" ] } }, "total": { "description": "Organizations matching the current filters.", "type": "number" }, "latestVersionId": { "type": "string", "nullable": true }, "latestVersion": { "description": "Semver of the latest version, for comparing against each row.", "type": "string", "nullable": true } }, "required": [ "totals", "byVersion", "rows", "total", "latestVersionId", "latestVersion" ] }, "UpdatePackageDto": { "type": "object", "properties": { "userId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {} }, "updatedAt": {}, "createdAt": {}, "slug": { "type": "string", "minLength": 1, "maxLength": 255 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "nullable": true }, "supportContactEmail": { "type": "string", "format": "email", "maxLength": 320, "nullable": true }, "documentationUrl": { "type": "string", "format": "uri", "maxLength": 2048, "nullable": true }, "websiteUrl": { "type": "string", "format": "uri", "maxLength": 2048, "nullable": true }, "icon": { "type": "string", "maxLength": 255, "nullable": true }, "readme": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" }, "default": [] }, "visibility": { "type": "string", "enum": [ "public", "unlisted", "private" ], "default": "private" }, "latestVersionId": { "type": "string" } } }, "PackageDeletedResponseDto": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ] }, "PublishPackageVersionDto": { "type": "object", "properties": { "version": { "type": "string", "maxLength": 64 }, "summary": { "type": "string", "maxLength": 256 }, "description": { "type": "string" }, "icon": { "type": "string", "maxLength": 255 }, "tags": { "type": "array", "items": { "type": "string" } }, "roots": { "type": "array", "minItems": 1, "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "workflow" ] }, "workflowTemplateId": { "type": "string", "minLength": 1 } }, "required": [ "kind", "workflowTemplateId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "sub-workflow" ] }, "workflowTemplateId": { "type": "string", "minLength": 1 } }, "required": [ "kind", "workflowTemplateId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "trigger" ] }, "triggerId": { "type": "string", "minLength": 1 } }, "required": [ "kind", "triggerId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "data-store-table" ] }, "tableName": { "type": "string", "minLength": 1 }, "includeSeedRows": { "type": "boolean" }, "seedRowLimit": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 10000, "exclusiveMaximum": false } }, "required": [ "kind", "tableName" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "dashboard" ] }, "dashboardId": { "type": "string", "minLength": 1 } }, "required": [ "kind", "dashboardId" ] } ] } }, "extensionPoints": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "starterSubworkflowRef": { "type": "string", "minLength": 1 }, "required": { "type": "boolean" } }, "required": [ "name", "label", "starterSubworkflowRef", "required" ] } }, "sharedEnvDefaults": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } } }, "required": [ "include" ] }, "descriptions": { "type": "object", "properties": { "connections": { "type": "object", "additionalProperties": { "type": "string" } }, "envs": { "type": "object", "additionalProperties": { "type": "string" } }, "dataStoreTables": { "type": "object", "additionalProperties": { "type": "string" } } } }, "optionalEnvKeys": { "type": "array", "items": { "type": "string" } }, "exports": { "type": "object", "properties": { "tools": { "type": "array", "items": { "type": "object", "properties": { "workflowName": { "type": "string", "minLength": 1 } }, "required": [ "workflowName" ] } } }, "required": [ "tools" ] }, "changelog": { "type": "string" } }, "required": [ "version", "roots" ] }, "PublishPackageVersionResponseDto": { "type": "object", "properties": { "packageVersion": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Author organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "userId": { "description": "User who created the row.", "type": "string" }, "packageId": { "description": "Parent package.", "type": "string" }, "version": { "description": "Semver, for example `1.4.0` or `2.0.0-beta.1`.", "type": "string" }, "manifest": { "description": "Full author-time spec: resources shipped, peer dependencies the installer must satisfy, and extension points.", "type": "object", "properties": { "schemaVersion": { "type": "number", "minimum": 1, "maximum": 1 }, "slug": { "type": "string", "minLength": 1 }, "version": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "icon": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "packageId": { "type": "string", "minLength": 1 }, "authorOrganizationId": { "type": "string", "minLength": 1 }, "authorOrgSuid": { "type": "string", "minLength": 1 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "workflow", "sub-workflow", "trigger", "data-store-table", "connection-shape", "dashboard", "dashboard-data-source" ] }, "name": { "type": "string", "minLength": 1 }, "isRoot": { "type": "boolean" }, "triggerType": { "type": "string", "enum": [ "webhook", "schedule", "manual", "event", "form" ] }, "scheduleCron": { "type": "string" } }, "required": [ "kind", "name" ] } }, "peerDeps": { "type": "object", "properties": { "connections": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "name", "type" ] } }, "env": { "type": "object", "properties": { "required": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "flat" ] }, "key": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "kind", "key" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shared" ] }, "key": { "type": "string", "minLength": 1 }, "default": { "type": "string" }, "description": { "type": "string" } }, "required": [ "kind", "key" ] } ] } }, "optional": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "flat" ] }, "key": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "kind", "key" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shared" ] }, "key": { "type": "string", "minLength": 1 }, "default": { "type": "string" }, "description": { "type": "string" } }, "required": [ "kind", "key" ] } ] } } }, "required": [ "required", "optional" ] }, "dataStoreTables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "shipsSeedData": { "type": "boolean" } }, "required": [ "name" ] } }, "toolPacks": { "type": "array", "items": { "type": "object", "properties": { "alias": { "type": "string", "minLength": 1 }, "packageId": { "type": "string", "minLength": 1 }, "versionRange": { "type": "string" }, "description": { "type": "string" } }, "required": [ "alias", "packageId" ] } } }, "required": [ "connections", "env", "dataStoreTables" ] }, "dependencies": { "type": "array", "items": { "type": "object", "properties": { "packageId": { "type": "string", "minLength": 1 }, "version": { "type": "string", "minLength": 1 } }, "required": [ "packageId", "version" ] } }, "extensionPoints": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "starterSubworkflowRef": { "type": "string", "minLength": 1 }, "required": { "type": "boolean" }, "inputSchema": { "type": "object", "additionalProperties": {} }, "outputSchema": { "type": "object", "additionalProperties": {} } }, "required": [ "name", "label", "starterSubworkflowRef", "required" ] } }, "exports": { "type": "object", "properties": { "tools": { "type": "array", "items": { "type": "object", "properties": { "workflowName": { "type": "string", "minLength": 1 } }, "required": [ "workflowName" ] } } }, "required": [ "tools" ] } }, "required": [ "schemaVersion", "slug", "version", "name", "resources", "peerDeps", "extensionPoints" ] }, "artifactUrl": { "description": "Storage location of the `.qfpkg` archive. Download it through `GET /packages/{id}/versions/{version}/artifact` rather than reading this directly.", "type": "string" }, "artifactDigest": { "description": "SHA-256 of the archive. File-drop installs are verified against it.", "type": "string" }, "summary": { "description": "One-line release title.", "type": "string" }, "releaseNotes": { "description": "Markdown release notes.", "type": "string" }, "publishedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "publishedByUserId": { "type": "string" }, "unlistedInstallToken": { "description": "Install token minted for this version. Anyone holding it can install the version regardless of visibility, so treat it as a credential.", "type": "string" } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "packageId", "version", "manifest", "publishedAt" ] }, "manifest": { "description": "The manifest that was written into the archive.", "type": "object", "properties": { "schemaVersion": { "type": "number", "minimum": 1, "maximum": 1 }, "slug": { "type": "string", "minLength": 1 }, "version": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "icon": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "packageId": { "type": "string", "minLength": 1 }, "authorOrganizationId": { "type": "string", "minLength": 1 }, "authorOrgSuid": { "type": "string", "minLength": 1 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "workflow", "sub-workflow", "trigger", "data-store-table", "connection-shape", "dashboard", "dashboard-data-source" ] }, "name": { "type": "string", "minLength": 1 }, "isRoot": { "type": "boolean" }, "triggerType": { "type": "string", "enum": [ "webhook", "schedule", "manual", "event", "form" ] }, "scheduleCron": { "type": "string" } }, "required": [ "kind", "name" ] } }, "peerDeps": { "type": "object", "properties": { "connections": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "name", "type" ] } }, "env": { "type": "object", "properties": { "required": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "flat" ] }, "key": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "kind", "key" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shared" ] }, "key": { "type": "string", "minLength": 1 }, "default": { "type": "string" }, "description": { "type": "string" } }, "required": [ "kind", "key" ] } ] } }, "optional": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "flat" ] }, "key": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "kind", "key" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shared" ] }, "key": { "type": "string", "minLength": 1 }, "default": { "type": "string" }, "description": { "type": "string" } }, "required": [ "kind", "key" ] } ] } } }, "required": [ "required", "optional" ] }, "dataStoreTables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "shipsSeedData": { "type": "boolean" } }, "required": [ "name" ] } }, "toolPacks": { "type": "array", "items": { "type": "object", "properties": { "alias": { "type": "string", "minLength": 1 }, "packageId": { "type": "string", "minLength": 1 }, "versionRange": { "type": "string" }, "description": { "type": "string" } }, "required": [ "alias", "packageId" ] } } }, "required": [ "connections", "env", "dataStoreTables" ] }, "dependencies": { "type": "array", "items": { "type": "object", "properties": { "packageId": { "type": "string", "minLength": 1 }, "version": { "type": "string", "minLength": 1 } }, "required": [ "packageId", "version" ] } }, "extensionPoints": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "starterSubworkflowRef": { "type": "string", "minLength": 1 }, "required": { "type": "boolean" }, "inputSchema": { "type": "object", "additionalProperties": {} }, "outputSchema": { "type": "object", "additionalProperties": {} } }, "required": [ "name", "label", "starterSubworkflowRef", "required" ] } }, "exports": { "type": "object", "properties": { "tools": { "type": "array", "items": { "type": "object", "properties": { "workflowName": { "type": "string", "minLength": 1 } }, "required": [ "workflowName" ] } } }, "required": [ "tools" ] } }, "required": [ "schemaVersion", "slug", "version", "name", "resources", "peerDeps", "extensionPoints" ] }, "artifactBytes": { "description": "Size of the archive in bytes.", "type": "number" }, "artifactDigest": { "description": "SHA-256 of the archive.", "type": "string" }, "artifactUrl": { "description": "Storage location of the archive.", "type": "string" } }, "required": [ "packageVersion", "manifest", "artifactBytes", "artifactDigest", "artifactUrl" ] }, "PackageVersionListResponseDto": { "type": "object", "properties": { "total": { "description": "Total records matching the filter, ignoring paging.", "type": "number" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Author organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "userId": { "description": "User who created the row.", "type": "string" }, "packageId": { "description": "Parent package.", "type": "string" }, "version": { "description": "Semver, for example `1.4.0` or `2.0.0-beta.1`.", "type": "string" }, "manifest": { "description": "Full author-time spec: resources shipped, peer dependencies the installer must satisfy, and extension points.", "type": "object", "properties": { "schemaVersion": { "type": "number", "minimum": 1, "maximum": 1 }, "slug": { "type": "string", "minLength": 1 }, "version": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "icon": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "packageId": { "type": "string", "minLength": 1 }, "authorOrganizationId": { "type": "string", "minLength": 1 }, "authorOrgSuid": { "type": "string", "minLength": 1 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "workflow", "sub-workflow", "trigger", "data-store-table", "connection-shape", "dashboard", "dashboard-data-source" ] }, "name": { "type": "string", "minLength": 1 }, "isRoot": { "type": "boolean" }, "triggerType": { "type": "string", "enum": [ "webhook", "schedule", "manual", "event", "form" ] }, "scheduleCron": { "type": "string" } }, "required": [ "kind", "name" ] } }, "peerDeps": { "type": "object", "properties": { "connections": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "name", "type" ] } }, "env": { "type": "object", "properties": { "required": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "flat" ] }, "key": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "kind", "key" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shared" ] }, "key": { "type": "string", "minLength": 1 }, "default": { "type": "string" }, "description": { "type": "string" } }, "required": [ "kind", "key" ] } ] } }, "optional": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "flat" ] }, "key": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "kind", "key" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shared" ] }, "key": { "type": "string", "minLength": 1 }, "default": { "type": "string" }, "description": { "type": "string" } }, "required": [ "kind", "key" ] } ] } } }, "required": [ "required", "optional" ] }, "dataStoreTables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "shipsSeedData": { "type": "boolean" } }, "required": [ "name" ] } }, "toolPacks": { "type": "array", "items": { "type": "object", "properties": { "alias": { "type": "string", "minLength": 1 }, "packageId": { "type": "string", "minLength": 1 }, "versionRange": { "type": "string" }, "description": { "type": "string" } }, "required": [ "alias", "packageId" ] } } }, "required": [ "connections", "env", "dataStoreTables" ] }, "dependencies": { "type": "array", "items": { "type": "object", "properties": { "packageId": { "type": "string", "minLength": 1 }, "version": { "type": "string", "minLength": 1 } }, "required": [ "packageId", "version" ] } }, "extensionPoints": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "starterSubworkflowRef": { "type": "string", "minLength": 1 }, "required": { "type": "boolean" }, "inputSchema": { "type": "object", "additionalProperties": {} }, "outputSchema": { "type": "object", "additionalProperties": {} } }, "required": [ "name", "label", "starterSubworkflowRef", "required" ] } }, "exports": { "type": "object", "properties": { "tools": { "type": "array", "items": { "type": "object", "properties": { "workflowName": { "type": "string", "minLength": 1 } }, "required": [ "workflowName" ] } } }, "required": [ "tools" ] } }, "required": [ "schemaVersion", "slug", "version", "name", "resources", "peerDeps", "extensionPoints" ] }, "artifactUrl": { "description": "Storage location of the `.qfpkg` archive. Download it through `GET /packages/{id}/versions/{version}/artifact` rather than reading this directly.", "type": "string" }, "artifactDigest": { "description": "SHA-256 of the archive. File-drop installs are verified against it.", "type": "string" }, "summary": { "description": "One-line release title.", "type": "string" }, "releaseNotes": { "description": "Markdown release notes.", "type": "string" }, "publishedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "publishedByUserId": { "type": "string" } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "packageId", "version", "manifest", "publishedAt" ] } } }, "required": [ "total", "data" ] }, "PackageVersionResponseDto": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Author organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "userId": { "description": "User who created the row.", "type": "string" }, "packageId": { "description": "Parent package.", "type": "string" }, "version": { "description": "Semver, for example `1.4.0` or `2.0.0-beta.1`.", "type": "string" }, "manifest": { "description": "Full author-time spec: resources shipped, peer dependencies the installer must satisfy, and extension points.", "type": "object", "properties": { "schemaVersion": { "type": "number", "minimum": 1, "maximum": 1 }, "slug": { "type": "string", "minLength": 1 }, "version": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "icon": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "packageId": { "type": "string", "minLength": 1 }, "authorOrganizationId": { "type": "string", "minLength": 1 }, "authorOrgSuid": { "type": "string", "minLength": 1 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "workflow", "sub-workflow", "trigger", "data-store-table", "connection-shape", "dashboard", "dashboard-data-source" ] }, "name": { "type": "string", "minLength": 1 }, "isRoot": { "type": "boolean" }, "triggerType": { "type": "string", "enum": [ "webhook", "schedule", "manual", "event", "form" ] }, "scheduleCron": { "type": "string" } }, "required": [ "kind", "name" ] } }, "peerDeps": { "type": "object", "properties": { "connections": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "name", "type" ] } }, "env": { "type": "object", "properties": { "required": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "flat" ] }, "key": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "kind", "key" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shared" ] }, "key": { "type": "string", "minLength": 1 }, "default": { "type": "string" }, "description": { "type": "string" } }, "required": [ "kind", "key" ] } ] } }, "optional": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "flat" ] }, "key": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "kind", "key" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shared" ] }, "key": { "type": "string", "minLength": 1 }, "default": { "type": "string" }, "description": { "type": "string" } }, "required": [ "kind", "key" ] } ] } } }, "required": [ "required", "optional" ] }, "dataStoreTables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "shipsSeedData": { "type": "boolean" } }, "required": [ "name" ] } }, "toolPacks": { "type": "array", "items": { "type": "object", "properties": { "alias": { "type": "string", "minLength": 1 }, "packageId": { "type": "string", "minLength": 1 }, "versionRange": { "type": "string" }, "description": { "type": "string" } }, "required": [ "alias", "packageId" ] } } }, "required": [ "connections", "env", "dataStoreTables" ] }, "dependencies": { "type": "array", "items": { "type": "object", "properties": { "packageId": { "type": "string", "minLength": 1 }, "version": { "type": "string", "minLength": 1 } }, "required": [ "packageId", "version" ] } }, "extensionPoints": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "starterSubworkflowRef": { "type": "string", "minLength": 1 }, "required": { "type": "boolean" }, "inputSchema": { "type": "object", "additionalProperties": {} }, "outputSchema": { "type": "object", "additionalProperties": {} } }, "required": [ "name", "label", "starterSubworkflowRef", "required" ] } }, "exports": { "type": "object", "properties": { "tools": { "type": "array", "items": { "type": "object", "properties": { "workflowName": { "type": "string", "minLength": 1 } }, "required": [ "workflowName" ] } } }, "required": [ "tools" ] } }, "required": [ "schemaVersion", "slug", "version", "name", "resources", "peerDeps", "extensionPoints" ] }, "artifactUrl": { "description": "Storage location of the `.qfpkg` archive. Download it through `GET /packages/{id}/versions/{version}/artifact` rather than reading this directly.", "type": "string" }, "artifactDigest": { "description": "SHA-256 of the archive. File-drop installs are verified against it.", "type": "string" }, "summary": { "description": "One-line release title.", "type": "string" }, "releaseNotes": { "description": "Markdown release notes.", "type": "string" }, "publishedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "publishedByUserId": { "type": "string" } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "packageId", "version", "manifest", "publishedAt" ] }, "UnlistedTokenResponseDto": { "type": "object", "properties": { "unlistedInstallToken": { "description": "Null when the version predates install tokens. Rotate the version to mint one.", "type": "string", "nullable": true } }, "required": [ "unlistedInstallToken" ] }, "RotateUnlistedTokenResponseDto": { "type": "object", "properties": { "packageId": { "type": "string" }, "version": { "type": "string" }, "unlistedInstallToken": { "description": "The new token. The previous one is dead.", "type": "string" }, "rotatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "rotatedByUserId": { "type": "string" } }, "required": [ "packageId", "version", "unlistedInstallToken", "rotatedAt", "rotatedByUserId" ] }, "InstallPreviewRequestDto": { "type": "object", "properties": { "packageId": { "type": "string", "minLength": 1 }, "packageVersionId": { "type": "string", "minLength": 1 }, "unlistedToken": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "packageId", "packageVersionId" ] }, "InstallPreviewResponseDto": { "type": "object", "properties": { "packageSummary": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "summary": { "description": "One-line release title.", "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "readme": { "description": "Markdown shown on the trust screen.", "type": "string" }, "releaseNotes": { "type": "string" }, "packageId": { "description": "Absent on archives published before the field existed.", "type": "string" }, "authorOrganizationId": { "type": "string" }, "isVerified": { "description": "Absent when the publisher record could not be read, which happens on file uploads from an organization you cannot see.", "type": "boolean" }, "supportContactEmail": { "type": "string" }, "documentationUrl": { "type": "string" }, "websiteUrl": { "type": "string" }, "toolWorkflowNames": { "description": "Workflows this package exposes as agent tools. Absent for plain packages.", "type": "array", "items": { "type": "string" } } }, "required": [ "slug", "name", "version" ] }, "resources": { "description": "What the install will create in the target organization.", "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "workflow", "sub-workflow", "trigger", "data-store-table", "connection-shape", "dashboard", "dashboard-data-source" ] }, "name": { "type": "string", "minLength": 1 }, "isRoot": { "type": "boolean" }, "triggerType": { "type": "string", "enum": [ "webhook", "schedule", "manual", "event", "form" ] }, "scheduleCron": { "type": "string" } }, "required": [ "kind", "name" ] } }, "peerDepDecisions": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "connection" ] }, "peerDep": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "name", "type" ] }, "existingMatch": { "description": "A connection in the target organization with the same name.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "name", "type" ] } }, "required": [ "kind", "peerDep" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "env-shared" ] }, "peerDep": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shared" ] }, "key": { "type": "string" }, "default": { "type": "string" }, "description": { "type": "string" } }, "required": [ "kind", "key" ] }, "existingMatch": { "description": "The key already exists in the shared environment.", "type": "object", "properties": { "environmentId": { "type": "string" }, "key": { "type": "string" } }, "required": [ "environmentId", "key" ] } }, "required": [ "kind", "peerDep" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "env-flat" ] }, "peerDep": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "flat" ] }, "key": { "type": "string" }, "description": { "type": "string" } }, "required": [ "kind", "key" ] } }, "required": [ "kind", "peerDep" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "data-store-table" ] }, "peerDep": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "shipsSeedData": { "type": "boolean" } }, "required": [ "name" ] }, "existingMatch": { "description": "A table with this name already exists and would be reused.", "type": "object", "properties": { "name": { "type": "string" }, "rowCount": { "type": "number" } }, "required": [ "name", "rowCount" ] } }, "required": [ "kind", "peerDep" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "extension-point" ] }, "extensionPoint": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "starterSubworkflowRef": { "type": "string", "minLength": 1 }, "required": { "type": "boolean" }, "inputSchema": { "type": "object", "additionalProperties": {} }, "outputSchema": { "type": "object", "additionalProperties": {} } }, "required": [ "name", "label", "starterSubworkflowRef", "required" ] }, "candidates": { "description": "Workflows that can fill the slot. Empty on a first install: a copy of the starter is made automatically.", "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "workflow" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "compat": { "type": "string", "enum": [ "compatible", "partial", "incompatible" ] }, "prior": { "description": "This is what the slot is currently bound to.", "type": "boolean" } }, "required": [ "kind", "id", "name", "compat" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "fresh-starter-copy" ] }, "starterName": { "description": "Name of the copy that would be made of the publisher's starter.", "type": "string" } }, "required": [ "kind", "starterName" ] } ] } } }, "required": [ "kind", "extensionPoint", "candidates" ] } ] } }, "setupChecklistPreview": { "description": "Work that will still be waiting after the install finishes.", "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "authenticate-connection", "set-env-var", "configure-trigger", "other" ] }, "label": { "type": "string" }, "description": { "type": "string" }, "relatedPeerDepKey": { "description": "The peer dependency this item resolves, so it can be hidden once answered.", "type": "string" } }, "required": [ "kind", "label", "relatedPeerDepKey" ] } }, "collisions": { "description": "Name clashes with resources the customer owns. Normally empty: package-owned rows occupy their own naming space.", "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "workflow", "trigger", "dashboard" ] }, "name": { "type": "string" }, "existingResourceId": { "type": "string" } }, "required": [ "kind", "name", "existingResourceId" ] } }, "sharedEnvKeys": { "description": "Keys already present in the target organization's shared environment, offered as remap targets.", "type": "array", "items": { "type": "string" } }, "dependencies": { "description": "Other packages that will be installed alongside this one.", "type": "array", "items": { "type": "object", "properties": { "packageId": { "type": "string" }, "version": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "icon": { "type": "string" }, "description": { "type": "string" }, "unresolved": { "description": "True when the dependency could not be read, for example it was deleted.", "type": "boolean" }, "peerDepCounts": { "description": "Setup work the dependency will add to the checklist after installing.", "type": "object", "properties": { "connections": { "type": "number" }, "envRequired": { "type": "number" }, "envOptional": { "type": "number" }, "dataStoreTables": { "type": "number" } }, "required": [ "connections", "envRequired", "envOptional", "dataStoreTables" ] } }, "required": [ "packageId", "version" ] } } }, "required": [ "packageSummary", "resources", "peerDepDecisions", "setupChecklistPreview", "collisions", "sharedEnvKeys", "dependencies" ] }, "InstallCommitRequestDto": { "type": "object", "properties": { "packageId": { "type": "string", "minLength": 1 }, "packageVersionId": { "type": "string", "minLength": 1 }, "decisions": { "type": "object", "properties": { "aliases": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "env" ] }, "source": { "type": "object", "properties": { "env": { "oneOf": [ { "type": "string", "enum": [ "shared" ] }, {} ] }, "key": { "type": "string", "minLength": 1 } }, "required": [ "env", "key" ] }, "target": { "type": "object", "properties": { "env": { "type": "string", "minLength": 1 }, "key": { "type": "string", "minLength": 1 } }, "required": [ "env", "key" ] } }, "required": [ "kind", "source", "target" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "extension-point" ] }, "source": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] }, "target": { "type": "object", "properties": { "subworkflowId": { "type": "string", "minLength": 1 } }, "required": [ "subworkflowId" ] } }, "required": [ "kind", "source", "target" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "extension-point-fresh-copy" ] }, "source": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] } }, "required": [ "kind", "source" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "connection" ] }, "source": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] }, "target": { "type": "object", "properties": { "connectionId": { "type": "string", "minLength": 1 } }, "required": [ "connectionId" ] } }, "required": [ "kind", "source", "target" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "data-store-table" ] }, "source": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] }, "target": { "type": "object", "properties": { "tableName": { "type": "string", "minLength": 1 } }, "required": [ "tableName" ] } }, "required": [ "kind", "source", "target" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "tool-pack" ] }, "source": { "type": "object", "properties": { "alias": { "type": "string", "minLength": 1 } }, "required": [ "alias" ] }, "target": { "type": "object", "properties": { "packageInstallId": { "type": "string", "minLength": 1 } }, "required": [ "packageInstallId" ] } }, "required": [ "kind", "source", "target" ] } ] }, "default": [] }, "workflowAttachedEnvs": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "object", "properties": { "environmentId": { "type": "string", "minLength": 1 } }, "required": [ "environmentId" ] }, {} ] }, "default": {} }, "sharedEnvValuesToCreate": { "type": "object", "additionalProperties": { "type": "string" }, "default": {} }, "seedDataStoreRowsFor": { "type": "object", "additionalProperties": { "type": "boolean" } }, "triggerEnvironments": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "object", "properties": { "environmentId": { "type": "string", "minLength": 1 } }, "required": [ "environmentId" ] }, {} ] }, "default": {} } } }, "unlistedToken": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "packageId", "packageVersionId", "decisions" ] }, "InstallCommitResponseDto": { "type": "object", "properties": { "packageInstallId": { "description": "The install record this created.", "type": "string" }, "installedResources": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "workflow", "sub-workflow", "trigger", "dashboard", "dashboard-data-source", "data-store-table", "connection-shape", "environment" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "didCreate": { "description": "False when the install bound to something that already existed.", "type": "boolean" } }, "required": [ "kind", "id", "name", "didCreate" ] } }, "setupChecklist": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "authenticate-connection", "set-env-var", "configure-trigger", "other" ] }, "label": { "type": "string" }, "description": { "type": "string" }, "relatedResourceId": { "type": "string" }, "envScope": { "description": "For `set-env-var` items: whether the value belongs in the shared environment or in whichever environment the workflow is attached to.", "type": "string", "enum": [ "flat", "shared" ] } }, "required": [ "id", "kind", "label" ] } }, "shipThroughNotices": { "description": "Present when the package activated a data source whose working copies are discarded after syncing to analytics storage.", "type": "array", "items": { "type": "object", "properties": { "tableName": { "type": "string" }, "message": { "type": "string" } }, "required": [ "tableName", "message" ] } } }, "required": [ "packageInstallId", "installedResources", "setupChecklist" ] }, "PackageInstallListResponseDto": { "type": "object", "properties": { "total": { "description": "Total records matching the filter, ignoring paging.", "type": "number" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Organization the package was installed into.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "userId": { "type": "string" }, "packageId": { "type": "string" }, "packageVersionId": { "description": "The exact version installed.", "type": "string" }, "parentPackageInstallId": { "description": "Set when this install exists only because another package depends on it. It is removed with its parent.", "type": "string" }, "appId": { "description": "Set when the install came from launching a productized app.", "type": "string" }, "installedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "installedByUserId": { "type": "string" }, "installedResources": { "description": "Everything the install created or bound to.", "type": "array", "items": { "type": "object", "properties": { "kind": { "oneOf": [ { "type": "string", "enum": [ "workflow", "sub-workflow", "trigger", "data-store-table", "connection-shape", "dashboard", "dashboard-data-source" ] }, { "type": "string", "enum": [ "environment" ] } ] }, "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "didCreate": { "type": "boolean" } }, "required": [ "kind", "id", "name", "didCreate" ] } }, "setupChecklist": { "description": "Outstanding setup work. Items carry `completedAt` once done.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "kind": { "type": "string", "enum": [ "authenticate-connection", "set-env-var", "configure-trigger", "other" ] }, "relatedResourceId": { "type": "string" }, "envScope": { "type": "string", "enum": [ "shared", "flat" ] }, "completedAt": { "type": "string" } }, "required": [ "id", "label", "kind" ] } }, "createdEnvs": { "type": "array", "items": { "type": "object", "properties": { "environmentId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 } }, "required": [ "environmentId", "name" ] } }, "aliases": { "description": "Choices made at install time, replayed on reinstall where still valid.", "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "env" ] }, "source": { "type": "object", "properties": { "env": { "oneOf": [ { "type": "string", "enum": [ "shared" ] }, {} ] }, "key": { "type": "string", "minLength": 1 } }, "required": [ "env", "key" ] }, "target": { "type": "object", "properties": { "env": { "type": "string", "minLength": 1 }, "key": { "type": "string", "minLength": 1 } }, "required": [ "env", "key" ] } }, "required": [ "kind", "source", "target" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "extension-point" ] }, "source": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] }, "target": { "type": "object", "properties": { "subworkflowId": { "type": "string", "minLength": 1 } }, "required": [ "subworkflowId" ] } }, "required": [ "kind", "source", "target" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "extension-point-fresh-copy" ] }, "source": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] } }, "required": [ "kind", "source" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "connection" ] }, "source": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] }, "target": { "type": "object", "properties": { "connectionId": { "type": "string", "minLength": 1 } }, "required": [ "connectionId" ] } }, "required": [ "kind", "source", "target" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "data-store-table" ] }, "source": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] }, "target": { "type": "object", "properties": { "tableName": { "type": "string", "minLength": 1 } }, "required": [ "tableName" ] } }, "required": [ "kind", "source", "target" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "tool-pack" ] }, "source": { "type": "object", "properties": { "alias": { "type": "string", "minLength": 1 } }, "required": [ "alias" ] }, "target": { "type": "object", "properties": { "packageInstallId": { "type": "string", "minLength": 1 } }, "required": [ "packageInstallId" ] } }, "required": [ "kind", "source", "target" ] } ] } }, "extensionPointBindings": { "description": "Extension point name to the workflow currently filling it. The workflow is customer-owned and is not overwritten by reinstall.", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "packageId", "packageVersionId", "installedAt", "installedResources", "setupChecklist", "createdEnvs", "aliases", "extensionPointBindings" ] } }, "packages": { "description": "Packages referenced by the rows above.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Author organization: the org that publishes this package.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "userId": { "description": "User who created the package.", "type": "string" }, "slug": { "description": "Install address. Public packages must use the canonical `@/` form; private and unlisted packages are addressed by id or install token instead.", "type": "string" }, "name": { "description": "Display name shown in the marketplace.", "type": "string" }, "description": { "type": "string", "nullable": true }, "supportContactEmail": { "description": "Publisher support address shown on the install trust screen.", "type": "string", "nullable": true }, "documentationUrl": { "type": "string", "nullable": true }, "websiteUrl": { "type": "string", "nullable": true }, "icon": { "description": "Either a Material Design icon name (`mdi-package-variant-closed`) or an image URL. Uploading through `POST /packages/{id}/icon` replaces this with a CDN URL.", "type": "string", "nullable": true }, "readme": { "description": "Markdown rendered on the install trust screen. Read live on every preview, so edits reach installers without republishing.", "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "visibility": { "description": "`public` lists the package in the marketplace. `unlisted` hides it but keeps per-version install links working. `private` restricts it to the author organization.", "type": "string", "enum": [ "public", "unlisted", "private" ] }, "latestVersionId": { "description": "Most recently published version, or null before the first publish.", "type": "string", "nullable": true }, "installCount": { "description": "Every install row keyed to this package, including copies pulled in as a dependency of another package. Popularity, not distinct customers.", "type": "number" }, "isVerified": { "description": "Set by QuickFlo staff after review. Not settable by the publisher.", "type": "boolean" }, "hasAgentTools": { "description": "Whether the latest version exposes any workflow as an agent tool.", "type": "boolean" }, "resourceCounts": { "description": "What the latest version ships, by kind. Only non-zero kinds are present.", "type": "object", "properties": { "workflows": { "type": "number" }, "subWorkflows": { "type": "number" }, "triggers": { "type": "number" }, "dataStoreTables": { "type": "number" }, "dashboards": { "type": "number" }, "connectionShapes": { "type": "number" }, "tools": { "type": "number" } } } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "slug", "name", "tags", "visibility", "installCount", "isVerified", "hasAgentTools", "resourceCounts" ] } }, "versions": { "description": "Versions referenced by the rows above.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Author organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "userId": { "description": "User who created the row.", "type": "string" }, "packageId": { "description": "Parent package.", "type": "string" }, "version": { "description": "Semver, for example `1.4.0` or `2.0.0-beta.1`.", "type": "string" }, "manifest": { "description": "Full author-time spec: resources shipped, peer dependencies the installer must satisfy, and extension points.", "type": "object", "properties": { "schemaVersion": { "type": "number", "minimum": 1, "maximum": 1 }, "slug": { "type": "string", "minLength": 1 }, "version": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "icon": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "packageId": { "type": "string", "minLength": 1 }, "authorOrganizationId": { "type": "string", "minLength": 1 }, "authorOrgSuid": { "type": "string", "minLength": 1 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "workflow", "sub-workflow", "trigger", "data-store-table", "connection-shape", "dashboard", "dashboard-data-source" ] }, "name": { "type": "string", "minLength": 1 }, "isRoot": { "type": "boolean" }, "triggerType": { "type": "string", "enum": [ "webhook", "schedule", "manual", "event", "form" ] }, "scheduleCron": { "type": "string" } }, "required": [ "kind", "name" ] } }, "peerDeps": { "type": "object", "properties": { "connections": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "name", "type" ] } }, "env": { "type": "object", "properties": { "required": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "flat" ] }, "key": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "kind", "key" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shared" ] }, "key": { "type": "string", "minLength": 1 }, "default": { "type": "string" }, "description": { "type": "string" } }, "required": [ "kind", "key" ] } ] } }, "optional": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "flat" ] }, "key": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "kind", "key" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shared" ] }, "key": { "type": "string", "minLength": 1 }, "default": { "type": "string" }, "description": { "type": "string" } }, "required": [ "kind", "key" ] } ] } } }, "required": [ "required", "optional" ] }, "dataStoreTables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "shipsSeedData": { "type": "boolean" } }, "required": [ "name" ] } }, "toolPacks": { "type": "array", "items": { "type": "object", "properties": { "alias": { "type": "string", "minLength": 1 }, "packageId": { "type": "string", "minLength": 1 }, "versionRange": { "type": "string" }, "description": { "type": "string" } }, "required": [ "alias", "packageId" ] } } }, "required": [ "connections", "env", "dataStoreTables" ] }, "dependencies": { "type": "array", "items": { "type": "object", "properties": { "packageId": { "type": "string", "minLength": 1 }, "version": { "type": "string", "minLength": 1 } }, "required": [ "packageId", "version" ] } }, "extensionPoints": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "starterSubworkflowRef": { "type": "string", "minLength": 1 }, "required": { "type": "boolean" }, "inputSchema": { "type": "object", "additionalProperties": {} }, "outputSchema": { "type": "object", "additionalProperties": {} } }, "required": [ "name", "label", "starterSubworkflowRef", "required" ] } }, "exports": { "type": "object", "properties": { "tools": { "type": "array", "items": { "type": "object", "properties": { "workflowName": { "type": "string", "minLength": 1 } }, "required": [ "workflowName" ] } } }, "required": [ "tools" ] } }, "required": [ "schemaVersion", "slug", "version", "name", "resources", "peerDeps", "extensionPoints" ] }, "artifactUrl": { "description": "Storage location of the `.qfpkg` archive. Download it through `GET /packages/{id}/versions/{version}/artifact` rather than reading this directly.", "type": "string" }, "artifactDigest": { "description": "SHA-256 of the archive. File-drop installs are verified against it.", "type": "string" }, "summary": { "description": "One-line release title.", "type": "string" }, "releaseNotes": { "description": "Markdown release notes.", "type": "string" }, "publishedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "publishedByUserId": { "type": "string" }, "unlistedInstallToken": { "description": "Present here, unlike on the version read endpoints: you already used some capability to install this version, so the token is nothing you did not have. It is still a credential. Do not forward it.", "type": "string" } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "packageId", "version", "manifest", "publishedAt" ] } } }, "required": [ "total", "data", "packages", "versions" ] }, "PackageInstallResponseDto": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Organization the package was installed into.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "userId": { "type": "string" }, "packageId": { "type": "string" }, "packageVersionId": { "description": "The exact version installed.", "type": "string" }, "parentPackageInstallId": { "description": "Set when this install exists only because another package depends on it. It is removed with its parent.", "type": "string" }, "appId": { "description": "Set when the install came from launching a productized app.", "type": "string" }, "installedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "installedByUserId": { "type": "string" }, "installedResources": { "description": "Everything the install created or bound to.", "type": "array", "items": { "type": "object", "properties": { "kind": { "oneOf": [ { "type": "string", "enum": [ "workflow", "sub-workflow", "trigger", "data-store-table", "connection-shape", "dashboard", "dashboard-data-source" ] }, { "type": "string", "enum": [ "environment" ] } ] }, "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "didCreate": { "type": "boolean" } }, "required": [ "kind", "id", "name", "didCreate" ] } }, "setupChecklist": { "description": "Outstanding setup work. Items carry `completedAt` once done.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "kind": { "type": "string", "enum": [ "authenticate-connection", "set-env-var", "configure-trigger", "other" ] }, "relatedResourceId": { "type": "string" }, "envScope": { "type": "string", "enum": [ "shared", "flat" ] }, "completedAt": { "type": "string" } }, "required": [ "id", "label", "kind" ] } }, "createdEnvs": { "type": "array", "items": { "type": "object", "properties": { "environmentId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 } }, "required": [ "environmentId", "name" ] } }, "aliases": { "description": "Choices made at install time, replayed on reinstall where still valid.", "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "env" ] }, "source": { "type": "object", "properties": { "env": { "oneOf": [ { "type": "string", "enum": [ "shared" ] }, {} ] }, "key": { "type": "string", "minLength": 1 } }, "required": [ "env", "key" ] }, "target": { "type": "object", "properties": { "env": { "type": "string", "minLength": 1 }, "key": { "type": "string", "minLength": 1 } }, "required": [ "env", "key" ] } }, "required": [ "kind", "source", "target" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "extension-point" ] }, "source": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] }, "target": { "type": "object", "properties": { "subworkflowId": { "type": "string", "minLength": 1 } }, "required": [ "subworkflowId" ] } }, "required": [ "kind", "source", "target" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "extension-point-fresh-copy" ] }, "source": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] } }, "required": [ "kind", "source" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "connection" ] }, "source": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] }, "target": { "type": "object", "properties": { "connectionId": { "type": "string", "minLength": 1 } }, "required": [ "connectionId" ] } }, "required": [ "kind", "source", "target" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "data-store-table" ] }, "source": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] }, "target": { "type": "object", "properties": { "tableName": { "type": "string", "minLength": 1 } }, "required": [ "tableName" ] } }, "required": [ "kind", "source", "target" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "tool-pack" ] }, "source": { "type": "object", "properties": { "alias": { "type": "string", "minLength": 1 } }, "required": [ "alias" ] }, "target": { "type": "object", "properties": { "packageInstallId": { "type": "string", "minLength": 1 } }, "required": [ "packageInstallId" ] } }, "required": [ "kind", "source", "target" ] } ] } }, "extensionPointBindings": { "description": "Extension point name to the workflow currently filling it. The workflow is customer-owned and is not overwritten by reinstall.", "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "packageId", "packageVersionId", "installedAt", "installedResources", "setupChecklist", "createdEnvs", "aliases", "extensionPointBindings" ] }, "ReinstallPreviewRequestDto": { "type": "object", "properties": { "incomingPackageVersionId": { "type": "string", "minLength": 1 } }, "required": [ "incomingPackageVersionId" ] }, "ReinstallPreviewResponseDto": { "type": "object", "properties": { "packageSummary": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "summary": { "description": "One-line release title.", "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "readme": { "description": "Markdown shown on the trust screen.", "type": "string" }, "releaseNotes": { "type": "string" }, "packageId": { "description": "Absent on archives published before the field existed.", "type": "string" }, "authorOrganizationId": { "type": "string" }, "isVerified": { "description": "Absent when the publisher record could not be read, which happens on file uploads from an organization you cannot see.", "type": "boolean" }, "supportContactEmail": { "type": "string" }, "documentationUrl": { "type": "string" }, "websiteUrl": { "type": "string" }, "toolWorkflowNames": { "description": "Workflows this package exposes as agent tools. Absent for plain packages.", "type": "array", "items": { "type": "string" } } }, "required": [ "slug", "name", "version" ] }, "fromVersion": { "description": "Version currently installed.", "type": "string" }, "toVersion": { "description": "Version being previewed.", "type": "string" }, "diff": { "type": "object", "properties": { "resourceChanges": { "description": "What the reinstall will do to each package-owned resource.", "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "workflow", "sub-workflow", "trigger", "data-store-table", "connection-shape", "dashboard", "dashboard-data-source" ] }, "name": { "type": "string" }, "change": { "description": "`replaced` means overwritten: package-owned resources are managed, so local edits do not survive.", "type": "string", "enum": [ "added", "replaced", "removed" ] } }, "required": [ "kind", "name", "change" ] } }, "newPeerDeps": { "description": "Dependencies that did not exist in the installed version.", "type": "object", "properties": { "connections": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "name", "type" ] } }, "sharedEnvs": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shared" ] }, "key": { "type": "string" }, "default": { "type": "string" }, "description": { "type": "string" } }, "required": [ "kind", "key" ] } }, "flatEnvs": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "flat" ] }, "key": { "type": "string" }, "description": { "type": "string" } }, "required": [ "kind", "key" ] } }, "dataStoreTables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "shipsSeedData": { "type": "boolean" } }, "required": [ "name" ] } }, "extensionPoints": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "starterSubworkflowRef": { "type": "string", "minLength": 1 }, "required": { "type": "boolean" }, "inputSchema": { "type": "object", "additionalProperties": {} }, "outputSchema": { "type": "object", "additionalProperties": {} } }, "required": [ "name", "label", "starterSubworkflowRef", "required" ] } } }, "required": [ "connections", "sharedEnvs", "flatEnvs", "dataStoreTables", "extensionPoints" ] }, "sharedDefaultChanges": { "description": "Shared environment defaults the publisher changed. These always re-prompt, because a silently shifted value is the supply-chain risk.", "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "oldDefault": { "type": "string" }, "newDefault": { "type": "string" } }, "required": [ "key" ] } }, "editedResourceWarnings": { "description": "Package-owned resources edited since the install. Reinstall overwrites them.", "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "workflow", "trigger", "dashboard" ] }, "name": { "type": "string" }, "resourceId": { "type": "string" }, "lastEditedAt": { "description": "ISO 8601 timestamp.", "type": "string" } }, "required": [ "kind", "name", "resourceId", "lastEditedAt" ] } }, "aliasReplay": { "description": "How install-time choices fare against the incoming version.", "type": "object", "properties": { "applicable": { "description": "Existing choices that carry over unchanged.", "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "env" ] }, "source": { "type": "object", "properties": { "env": { "oneOf": [ { "type": "string", "enum": [ "shared" ] }, {} ] }, "key": { "type": "string", "minLength": 1 } }, "required": [ "env", "key" ] }, "target": { "type": "object", "properties": { "env": { "type": "string", "minLength": 1 }, "key": { "type": "string", "minLength": 1 } }, "required": [ "env", "key" ] } }, "required": [ "kind", "source", "target" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "extension-point" ] }, "source": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] }, "target": { "type": "object", "properties": { "subworkflowId": { "type": "string", "minLength": 1 } }, "required": [ "subworkflowId" ] } }, "required": [ "kind", "source", "target" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "extension-point-fresh-copy" ] }, "source": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] } }, "required": [ "kind", "source" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "connection" ] }, "source": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] }, "target": { "type": "object", "properties": { "connectionId": { "type": "string", "minLength": 1 } }, "required": [ "connectionId" ] } }, "required": [ "kind", "source", "target" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "data-store-table" ] }, "source": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] }, "target": { "type": "object", "properties": { "tableName": { "type": "string", "minLength": 1 } }, "required": [ "tableName" ] } }, "required": [ "kind", "source", "target" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "tool-pack" ] }, "source": { "type": "object", "properties": { "alias": { "type": "string", "minLength": 1 } }, "required": [ "alias" ] }, "target": { "type": "object", "properties": { "packageInstallId": { "type": "string", "minLength": 1 } }, "required": [ "packageInstallId" ] } }, "required": [ "kind", "source", "target" ] } ] } }, "invalidated": { "type": "array", "items": { "type": "object", "properties": { "alias": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "env" ] }, "source": { "type": "object", "properties": { "env": { "oneOf": [ { "type": "string", "enum": [ "shared" ] }, {} ] }, "key": { "type": "string", "minLength": 1 } }, "required": [ "env", "key" ] }, "target": { "type": "object", "properties": { "env": { "type": "string", "minLength": 1 }, "key": { "type": "string", "minLength": 1 } }, "required": [ "env", "key" ] } }, "required": [ "kind", "source", "target" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "extension-point" ] }, "source": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] }, "target": { "type": "object", "properties": { "subworkflowId": { "type": "string", "minLength": 1 } }, "required": [ "subworkflowId" ] } }, "required": [ "kind", "source", "target" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "extension-point-fresh-copy" ] }, "source": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] } }, "required": [ "kind", "source" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "connection" ] }, "source": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] }, "target": { "type": "object", "properties": { "connectionId": { "type": "string", "minLength": 1 } }, "required": [ "connectionId" ] } }, "required": [ "kind", "source", "target" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "data-store-table" ] }, "source": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] }, "target": { "type": "object", "properties": { "tableName": { "type": "string", "minLength": 1 } }, "required": [ "tableName" ] } }, "required": [ "kind", "source", "target" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "tool-pack" ] }, "source": { "type": "object", "properties": { "alias": { "type": "string", "minLength": 1 } }, "required": [ "alias" ] }, "target": { "type": "object", "properties": { "packageInstallId": { "type": "string", "minLength": 1 } }, "required": [ "packageInstallId" ] } }, "required": [ "kind", "source", "target" ] } ] }, "reason": { "description": "Why the choice cannot carry over and has to be made again.", "type": "string", "enum": [ "source-removed", "source-shape-changed" ] } }, "required": [ "alias", "reason" ] } } }, "required": [ "applicable", "invalidated" ] }, "extensionPointBindingChanges": { "description": "Slot-level changes only. The workflows filling the slots are customer-owned and are never rewritten.", "type": "array", "items": { "type": "object", "properties": { "extensionPointName": { "type": "string" }, "change": { "type": "string", "enum": [ "added", "removed", "carried" ] }, "priorWorkflowId": { "description": "What the slot is bound to now, when it is bound to anything.", "type": "string" } }, "required": [ "extensionPointName", "change" ] } } }, "required": [ "resourceChanges", "newPeerDeps", "sharedDefaultChanges", "editedResourceWarnings", "aliasReplay", "extensionPointBindingChanges" ] }, "resources": { "description": "Resource list of the incoming version.", "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "workflow", "sub-workflow", "trigger", "data-store-table", "connection-shape", "dashboard", "dashboard-data-source" ] }, "name": { "type": "string", "minLength": 1 }, "isRoot": { "type": "boolean" }, "triggerType": { "type": "string", "enum": [ "webhook", "schedule", "manual", "event", "form" ] }, "scheduleCron": { "type": "string" } }, "required": [ "kind", "name" ] } }, "peerDepDecisions": { "description": "Every dependency of the incoming version, new or carried over, so the same picker can be rendered as on a first install.", "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "connection" ] }, "peerDep": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "name", "type" ] }, "existingMatch": { "description": "A connection in the target organization with the same name.", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" } }, "required": [ "id", "name", "type" ] } }, "required": [ "kind", "peerDep" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "env-shared" ] }, "peerDep": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shared" ] }, "key": { "type": "string" }, "default": { "type": "string" }, "description": { "type": "string" } }, "required": [ "kind", "key" ] }, "existingMatch": { "description": "The key already exists in the shared environment.", "type": "object", "properties": { "environmentId": { "type": "string" }, "key": { "type": "string" } }, "required": [ "environmentId", "key" ] } }, "required": [ "kind", "peerDep" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "env-flat" ] }, "peerDep": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "flat" ] }, "key": { "type": "string" }, "description": { "type": "string" } }, "required": [ "kind", "key" ] } }, "required": [ "kind", "peerDep" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "data-store-table" ] }, "peerDep": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "shipsSeedData": { "type": "boolean" } }, "required": [ "name" ] }, "existingMatch": { "description": "A table with this name already exists and would be reused.", "type": "object", "properties": { "name": { "type": "string" }, "rowCount": { "type": "number" } }, "required": [ "name", "rowCount" ] } }, "required": [ "kind", "peerDep" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "extension-point" ] }, "extensionPoint": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "starterSubworkflowRef": { "type": "string", "minLength": 1 }, "required": { "type": "boolean" }, "inputSchema": { "type": "object", "additionalProperties": {} }, "outputSchema": { "type": "object", "additionalProperties": {} } }, "required": [ "name", "label", "starterSubworkflowRef", "required" ] }, "candidates": { "description": "Workflows that can fill the slot. Empty on a first install: a copy of the starter is made automatically.", "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "workflow" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "compat": { "type": "string", "enum": [ "compatible", "partial", "incompatible" ] }, "prior": { "description": "This is what the slot is currently bound to.", "type": "boolean" } }, "required": [ "kind", "id", "name", "compat" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "fresh-starter-copy" ] }, "starterName": { "description": "Name of the copy that would be made of the publisher's starter.", "type": "string" } }, "required": [ "kind", "starterName" ] } ] } } }, "required": [ "kind", "extensionPoint", "candidates" ] } ] } }, "sharedEnvKeys": { "type": "array", "items": { "type": "string" } }, "currentBindings": { "description": "What the install is wired to right now. Send these back unchanged to keep the existing wiring. A null value means nothing resolves and the binding has to be picked again.", "type": "object", "properties": { "aliases": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "env" ] }, "source": { "type": "object", "properties": { "env": { "oneOf": [ { "type": "string", "enum": [ "shared" ] }, {} ] }, "key": { "type": "string", "minLength": 1 } }, "required": [ "env", "key" ] }, "target": { "type": "object", "properties": { "env": { "type": "string", "minLength": 1 }, "key": { "type": "string", "minLength": 1 } }, "required": [ "env", "key" ] } }, "required": [ "kind", "source", "target" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "extension-point" ] }, "source": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] }, "target": { "type": "object", "properties": { "subworkflowId": { "type": "string", "minLength": 1 } }, "required": [ "subworkflowId" ] } }, "required": [ "kind", "source", "target" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "extension-point-fresh-copy" ] }, "source": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] } }, "required": [ "kind", "source" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "connection" ] }, "source": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] }, "target": { "type": "object", "properties": { "connectionId": { "type": "string", "minLength": 1 } }, "required": [ "connectionId" ] } }, "required": [ "kind", "source", "target" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "data-store-table" ] }, "source": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] }, "target": { "type": "object", "properties": { "tableName": { "type": "string", "minLength": 1 } }, "required": [ "tableName" ] } }, "required": [ "kind", "source", "target" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "tool-pack" ] }, "source": { "type": "object", "properties": { "alias": { "type": "string", "minLength": 1 } }, "required": [ "alias" ] }, "target": { "type": "object", "properties": { "packageInstallId": { "type": "string", "minLength": 1 } }, "required": [ "packageInstallId" ] } }, "required": [ "kind", "source", "target" ] } ] } }, "workflowAttachedEnvs": { "type": "object", "additionalProperties": { "type": "object", "properties": { "environmentId": { "type": "string" } }, "required": [ "environmentId" ], "nullable": true } }, "triggerEnvironments": { "type": "object", "additionalProperties": { "type": "object", "properties": { "environmentId": { "type": "string" } }, "required": [ "environmentId" ], "nullable": true } } }, "required": [ "aliases", "workflowAttachedEnvs", "triggerEnvironments" ] } }, "required": [ "packageSummary", "fromVersion", "toVersion", "diff", "resources", "peerDepDecisions", "sharedEnvKeys", "currentBindings" ] }, "ReinstallCommitRequestDto": { "type": "object", "properties": { "incomingPackageVersionId": { "type": "string", "minLength": 1 }, "decisions": { "type": "object", "properties": { "aliases": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "env" ] }, "source": { "type": "object", "properties": { "env": { "oneOf": [ { "type": "string", "enum": [ "shared" ] }, {} ] }, "key": { "type": "string", "minLength": 1 } }, "required": [ "env", "key" ] }, "target": { "type": "object", "properties": { "env": { "type": "string", "minLength": 1 }, "key": { "type": "string", "minLength": 1 } }, "required": [ "env", "key" ] } }, "required": [ "kind", "source", "target" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "extension-point" ] }, "source": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] }, "target": { "type": "object", "properties": { "subworkflowId": { "type": "string", "minLength": 1 } }, "required": [ "subworkflowId" ] } }, "required": [ "kind", "source", "target" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "extension-point-fresh-copy" ] }, "source": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] } }, "required": [ "kind", "source" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "connection" ] }, "source": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] }, "target": { "type": "object", "properties": { "connectionId": { "type": "string", "minLength": 1 } }, "required": [ "connectionId" ] } }, "required": [ "kind", "source", "target" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "data-store-table" ] }, "source": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] }, "target": { "type": "object", "properties": { "tableName": { "type": "string", "minLength": 1 } }, "required": [ "tableName" ] } }, "required": [ "kind", "source", "target" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "tool-pack" ] }, "source": { "type": "object", "properties": { "alias": { "type": "string", "minLength": 1 } }, "required": [ "alias" ] }, "target": { "type": "object", "properties": { "packageInstallId": { "type": "string", "minLength": 1 } }, "required": [ "packageInstallId" ] } }, "required": [ "kind", "source", "target" ] } ] }, "default": [] }, "workflowAttachedEnvs": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "object", "properties": { "environmentId": { "type": "string", "minLength": 1 } }, "required": [ "environmentId" ] }, {} ] }, "default": {} }, "sharedEnvValuesToCreate": { "type": "object", "additionalProperties": { "type": "string" }, "default": {} }, "seedDataStoreRowsFor": { "type": "object", "additionalProperties": { "type": "boolean" } }, "triggerEnvironments": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "object", "properties": { "environmentId": { "type": "string", "minLength": 1 } }, "required": [ "environmentId" ] }, {} ] }, "default": {} } } } }, "required": [ "incomingPackageVersionId", "decisions" ] }, "ReinstallCommitResponseDto": { "type": "object", "properties": { "packageInstallId": { "description": "Unchanged: reinstall updates the record in place.", "type": "string" }, "fromVersion": { "type": "string" }, "toVersion": { "type": "string" }, "resourceChanges": { "type": "object", "properties": { "added": { "type": "number" }, "replaced": { "type": "number" }, "removed": { "type": "number" } }, "required": [ "added", "replaced", "removed" ] }, "installedResources": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "workflow", "sub-workflow", "trigger", "dashboard", "dashboard-data-source", "data-store-table", "connection-shape", "environment" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "didCreate": { "description": "False when the install bound to something that already existed.", "type": "boolean" } }, "required": [ "kind", "id", "name", "didCreate" ] } }, "setupChecklist": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "authenticate-connection", "set-env-var", "configure-trigger", "other" ] }, "label": { "type": "string" }, "description": { "type": "string" }, "relatedResourceId": { "type": "string" }, "envScope": { "description": "For `set-env-var` items: whether the value belongs in the shared environment or in whichever environment the workflow is attached to.", "type": "string", "enum": [ "flat", "shared" ] } }, "required": [ "id", "kind", "label" ] } }, "shipThroughNotices": { "type": "array", "items": { "type": "object", "properties": { "tableName": { "type": "string" }, "message": { "type": "string" } }, "required": [ "tableName", "message" ] } } }, "required": [ "packageInstallId", "fromVersion", "toVersion", "resourceChanges", "installedResources", "setupChecklist" ] }, "UninstallResponseDto": { "type": "object", "properties": { "deleted": { "type": "object", "properties": { "workflows": { "type": "number" }, "triggers": { "type": "number" }, "dashboards": { "type": "number" }, "dashboardDataSources": { "description": "Counted separately: one dashboard can reach several data sources.", "type": "number" } }, "required": [ "workflows", "triggers", "dashboards", "dashboardDataSources" ] } }, "required": [ "deleted" ] }, "DashboardListResponseDto": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Owning organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "userId": { "description": "User who created the dashboard.", "type": "string" }, "packageInstallId": { "description": "Package install that owns this dashboard. Absent for dashboards the organization created itself.", "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "isDefault": { "description": "Opens first when no dashboard is named. At most one per org.", "type": "boolean" }, "layout": { "description": "Grid placement for each widget. Empty on a new dashboard.", "type": "array", "items": { "type": "object", "properties": { "widgetId": { "description": "Widget occupying this grid slot.", "type": "string" }, "x": { "description": "Column offset in a 12-column grid.", "type": "integer" }, "y": { "description": "Row offset.", "type": "integer" }, "w": { "description": "Width in grid columns.", "type": "integer" }, "h": { "description": "Height in grid rows.", "type": "integer" }, "minW": { "type": "integer" }, "minH": { "type": "integer" } }, "required": [ "widgetId", "x", "y", "w", "h" ] } }, "filterConfig": { "description": "Controls rendered in the dashboard filter bar.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "dataSourceId": { "type": "string" }, "dimension": { "type": "string" }, "label": { "description": "Text shown above the control in the filter bar.", "type": "string" }, "bindings": { "description": "Per-data-source bindings. When present these are authoritative, and the top-level `dataSourceId`/`dimension` are the first binding.", "type": "array", "items": { "type": "object", "properties": { "dataSourceId": { "type": "string" }, "dimension": { "description": "Field on that data source this filter drives.", "type": "string" } }, "required": [ "dataSourceId", "dimension" ] } } }, "required": [ "id", "dataSourceId", "dimension", "label" ] } }, "filterDefaults": { "description": "Values each filter starts on, keyed by filter id.", "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "timezone": { "description": "IANA timezone every widget buckets and renders dates in. Absent means fall back to the viewer’s browser timezone.", "type": "string" } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "name", "isDefault", "layout" ] } }, "CreateDashboardDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string" }, "isDefault": { "type": "boolean" }, "timezone": { "type": "string", "maxLength": 100 } }, "required": [ "name" ] }, "DashboardResponseDto": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Owning organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "userId": { "description": "User who created the dashboard.", "type": "string" }, "packageInstallId": { "description": "Package install that owns this dashboard. Absent for dashboards the organization created itself.", "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "isDefault": { "description": "Opens first when no dashboard is named. At most one per org.", "type": "boolean" }, "layout": { "description": "Grid placement for each widget. Empty on a new dashboard.", "type": "array", "items": { "type": "object", "properties": { "widgetId": { "description": "Widget occupying this grid slot.", "type": "string" }, "x": { "description": "Column offset in a 12-column grid.", "type": "integer" }, "y": { "description": "Row offset.", "type": "integer" }, "w": { "description": "Width in grid columns.", "type": "integer" }, "h": { "description": "Height in grid rows.", "type": "integer" }, "minW": { "type": "integer" }, "minH": { "type": "integer" } }, "required": [ "widgetId", "x", "y", "w", "h" ] } }, "filterConfig": { "description": "Controls rendered in the dashboard filter bar.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "dataSourceId": { "type": "string" }, "dimension": { "type": "string" }, "label": { "description": "Text shown above the control in the filter bar.", "type": "string" }, "bindings": { "description": "Per-data-source bindings. When present these are authoritative, and the top-level `dataSourceId`/`dimension` are the first binding.", "type": "array", "items": { "type": "object", "properties": { "dataSourceId": { "type": "string" }, "dimension": { "description": "Field on that data source this filter drives.", "type": "string" } }, "required": [ "dataSourceId", "dimension" ] } } }, "required": [ "id", "dataSourceId", "dimension", "label" ] } }, "filterDefaults": { "description": "Values each filter starts on, keyed by filter id.", "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "timezone": { "description": "IANA timezone every widget buckets and renders dates in. Absent means fall back to the viewer’s browser timezone.", "type": "string" } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "name", "isDefault", "layout" ] }, "ImportDashboardDto": { "type": "object", "properties": { "version": { "type": "number", "minimum": 1, "maximum": 1 }, "exportedAt": { "type": "string" }, "dashboard": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "nullable": true }, "layout": { "type": "array", "items": { "type": "object", "properties": { "widgetId": { "type": "string", "minLength": 1 }, "x": { "type": "integer", "minimum": 0, "exclusiveMinimum": false }, "y": { "type": "integer", "minimum": 0, "exclusiveMinimum": false }, "w": { "type": "integer", "minimum": 1, "exclusiveMinimum": false }, "h": { "type": "integer", "minimum": 1, "exclusiveMinimum": false }, "minW": { "type": "integer", "minimum": 1, "exclusiveMinimum": false }, "minH": { "type": "integer", "minimum": 1, "exclusiveMinimum": false } }, "required": [ "widgetId", "x", "y", "w", "h" ] } }, "filterConfig": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "dataSourceId": { "type": "string", "minLength": 1 }, "dimension": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "bindings": { "type": "array", "items": { "type": "object", "properties": { "dataSourceId": { "type": "string", "minLength": 1 }, "dimension": { "type": "string", "minLength": 1 } }, "required": [ "dataSourceId", "dimension" ] } } }, "required": [ "id", "dataSourceId", "dimension", "label" ] } }, "filterDefaults": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "timezone": { "type": "string", "maxLength": 100, "nullable": true } }, "required": [ "name", "layout" ] }, "dataSources": { "type": "array", "maxItems": 50, "items": { "type": "object", "properties": { "exportId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "schema": { "type": "object", "properties": { "name": { "type": "string" }, "fields": { "type": "object", "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "string", "number", "boolean", "date" ] }, "label": { "type": "string" }, "measure": { "type": "boolean" }, "timeDimension": { "type": "boolean" } }, "required": [ "type", "label" ] } }, "calculatedFields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "string", "number", "boolean", "date" ] }, "expression": { "type": "object", "additionalProperties": {} }, "formula": { "type": "string" }, "measure": { "type": "boolean" } }, "required": [ "name", "label", "type", "expression" ] } } }, "required": [ "name", "fields" ] } }, "required": [ "exportId", "name", "schema" ] } }, "widgets": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "exportWidgetId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "chartType": { "type": "string", "enum": [ "bar", "line", "pie", "stat-card", "table", "area", "doughnut", "funnel", "stats-table", "pivot-table" ] }, "dataSourceExportId": { "type": "string", "minLength": 1 }, "queryConfig": { "type": "object", "additionalProperties": {} }, "displayConfig": { "type": "object", "additionalProperties": {}, "nullable": true } }, "required": [ "exportWidgetId", "title", "chartType", "dataSourceExportId", "queryConfig" ] } }, "dataSourceMappings": { "type": "object", "additionalProperties": { "type": "string", "format": "uuid" } } }, "required": [ "version", "exportedAt", "dashboard", "dataSources", "widgets", "dataSourceMappings" ] }, "DashboardWithWidgetsResponseDto": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Owning organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "userId": { "description": "User who created the dashboard.", "type": "string" }, "packageInstallId": { "description": "Package install that owns this dashboard. Absent for dashboards the organization created itself.", "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "isDefault": { "description": "Opens first when no dashboard is named. At most one per org.", "type": "boolean" }, "layout": { "description": "Grid placement for each widget. Empty on a new dashboard.", "type": "array", "items": { "type": "object", "properties": { "widgetId": { "description": "Widget occupying this grid slot.", "type": "string" }, "x": { "description": "Column offset in a 12-column grid.", "type": "integer" }, "y": { "description": "Row offset.", "type": "integer" }, "w": { "description": "Width in grid columns.", "type": "integer" }, "h": { "description": "Height in grid rows.", "type": "integer" }, "minW": { "type": "integer" }, "minH": { "type": "integer" } }, "required": [ "widgetId", "x", "y", "w", "h" ] } }, "filterConfig": { "description": "Controls rendered in the dashboard filter bar.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "dataSourceId": { "type": "string" }, "dimension": { "type": "string" }, "label": { "description": "Text shown above the control in the filter bar.", "type": "string" }, "bindings": { "description": "Per-data-source bindings. When present these are authoritative, and the top-level `dataSourceId`/`dimension` are the first binding.", "type": "array", "items": { "type": "object", "properties": { "dataSourceId": { "type": "string" }, "dimension": { "description": "Field on that data source this filter drives.", "type": "string" } }, "required": [ "dataSourceId", "dimension" ] } } }, "required": [ "id", "dataSourceId", "dimension", "label" ] } }, "filterDefaults": { "description": "Values each filter starts on, keyed by filter id.", "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "timezone": { "description": "IANA timezone every widget buckets and renders dates in. Absent means fall back to the viewer’s browser timezone.", "type": "string" }, "widgets": { "description": "Widgets on this dashboard, oldest first.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Owning organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "userId": { "type": "string" }, "dashboardId": { "type": "string" }, "title": { "type": "string" }, "chartType": { "type": "string", "enum": [ "bar", "line", "pie", "stat-card", "table", "area", "doughnut", "funnel", "stats-table", "pivot-table" ] }, "dataSourceId": { "description": "Data source this widget reads.", "type": "string" }, "queryConfig": { "description": "Analytics query: measures, dimensions, timeDimensions, filters, joins, order and limit. Same shape the create/update widget body accepts.", "type": "object", "additionalProperties": {} }, "displayConfig": { "description": "Chart display overrides merged over the generated options.", "type": "object", "additionalProperties": {} } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "dashboardId", "title", "chartType", "dataSourceId", "queryConfig" ] } } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "name", "isDefault", "layout", "widgets" ] }, "DashboardDataSourceListResponseDto": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Owning organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "userId": { "type": "string" }, "packageInstallId": { "description": "Package install that owns this source. Absent if customer-owned.", "type": "string" }, "packageDataSourceId": { "description": "Publish-time slug from the package manifest.", "type": "string" }, "name": { "type": "string" }, "type": { "description": "Feed type, e.g. `twilio:calls`, or `custom` for a manual source.", "type": "string" }, "connectionId": { "type": "string" }, "connectionName": { "type": "string" }, "dataStoreTableName": { "description": "Data store table records land in.", "type": "string" }, "recordSchema": { "type": "object", "properties": { "name": { "description": "Human-readable name for the record type.", "type": "string" }, "fields": { "description": "Field definitions keyed by field name.", "type": "object", "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "string", "number", "boolean", "date" ] }, "label": { "description": "Display label in field pickers.", "type": "string" }, "measure": { "description": "Aggregatable — offered under measures rather than dimensions.", "type": "boolean" }, "timeDimension": { "description": "The field date ranges and time bucketing apply to.", "type": "boolean" } }, "required": [ "type", "label" ] } }, "calculatedFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "description": "Identifier used in query refs, e.g. `ds_….handleRate`.", "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "string", "number", "boolean", "date" ] }, "expression": { "description": "Compiled jsep AST the analytics engine translates to SQL.", "type": "object", "additionalProperties": {} }, "formula": { "description": "Source text the AST was compiled from, shown in the editor.", "type": "string" }, "measure": { "type": "boolean" } }, "required": [ "id", "name", "label", "type", "expression" ] } }, "windowDimensions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "label": { "type": "string" }, "function": { "description": "Rank within group is the only supported function today.", "type": "string", "enum": [ "row_number" ] }, "partitionBy": { "description": "Fields defining the group.", "type": "array", "items": { "type": "string" } }, "orderBy": { "description": "Field ordering rows within the group.", "type": "string" }, "direction": { "description": "asc (default): rank 1 is the earliest row.", "type": "string", "enum": [ "asc", "desc" ] }, "semantic": { "description": "lifetime (default) ranks over the full history and filters after; window-reset filters first, so ranks restart inside the range.", "type": "string", "enum": [ "lifetime", "window-reset" ] } }, "required": [ "id", "name", "label", "function", "partitionBy", "orderBy" ] } } }, "required": [ "name", "fields" ] }, "syncConfig": { "type": "object", "properties": { "syncIntervalMinutes": { "type": "number" }, "lastSyncAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "lastSyncStatus": { "type": "string", "enum": [ "success", "error", "running", "pending" ] }, "lastSyncError": { "type": "string" }, "syncWorkflowId": { "type": "string" }, "syncScheduleId": { "type": "string" }, "syncTriggerId": { "type": "string" }, "lastSyncExecutionId": { "description": "Execution of the most recent sync, for tracing a failure.", "type": "string" } } }, "enabled": { "type": "boolean" }, "sharedFromOrganizationId": { "description": "Set when this source reads another organization’s shared table.", "type": "string" }, "sharedFromOrganizationIds": { "description": "Set on an aggregate source reading the same table across orgs.", "type": "array", "items": { "type": "string" } }, "aggregateEntries": { "description": "Per-org table names an aggregate source unions.", "type": "array", "items": { "type": "object", "properties": { "organizationId": { "type": "string" }, "tableName": { "type": "string" }, "label": { "type": "string" } }, "required": [ "organizationId", "tableName" ] } }, "schemaRefreshedAt": { "description": "When `recordSchema` was last re-sampled from the data.", "type": "string" }, "servingEngine": { "description": "Which engine answers analytics queries for this source.", "type": "string", "enum": [ "postgres", "clickhouse" ] }, "servingRelation": { "description": "ClickHouse table name. Only set on ClickHouse-served sources.", "type": "string" }, "hotPathMode": { "description": "This source’s INTENT for the Postgres hot copy. `evict-after-sync` drops the row once ClickHouse acks it, which makes point reads of the record stop working.", "type": "string", "enum": [ "retain", "evict-after-sync" ] }, "effectiveHotPathMode": { "description": "Mode actually in force for this source’s table.", "type": "string", "enum": [ "retain", "evict-after-sync" ] } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "name", "type", "dataStoreTableName", "recordSchema", "enabled", "servingEngine", "hotPathMode", "effectiveHotPathMode" ] } }, "CreateDataSourceDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "type": { "type": "string", "minLength": 1, "maxLength": 100 }, "connectionId": { "type": "string", "format": "uuid" }, "connectionName": { "type": "string" }, "dataStoreTableName": { "type": "string", "minLength": 1, "maxLength": 255 }, "recordSchema": { "type": "object", "properties": { "name": { "type": "string" }, "fields": { "type": "object", "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "string", "number", "boolean", "date" ] }, "label": { "type": "string" }, "measure": { "type": "boolean" }, "timeDimension": { "type": "boolean" } }, "required": [ "type", "label" ] } } }, "required": [ "name", "fields" ] }, "sharedFromOrganizationId": { "type": "string", "format": "uuid" }, "sharedFromOrganizationIds": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "type": "string", "format": "uuid" } }, "aggregateEntries": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "type": "object", "properties": { "organizationId": { "type": "string", "format": "uuid" }, "tableName": { "type": "string", "minLength": 1, "maxLength": 255 }, "label": { "type": "string", "maxLength": 255 } }, "required": [ "organizationId", "tableName" ] } }, "hotPathMode": { "type": "string", "enum": [ "retain", "evict-after-sync" ] } }, "required": [ "name", "type", "dataStoreTableName", "recordSchema" ] }, "DashboardDataSourceResponseDto": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Owning organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "userId": { "type": "string" }, "packageInstallId": { "description": "Package install that owns this source. Absent if customer-owned.", "type": "string" }, "packageDataSourceId": { "description": "Publish-time slug from the package manifest.", "type": "string" }, "name": { "type": "string" }, "type": { "description": "Feed type, e.g. `twilio:calls`, or `custom` for a manual source.", "type": "string" }, "connectionId": { "type": "string" }, "connectionName": { "type": "string" }, "dataStoreTableName": { "description": "Data store table records land in.", "type": "string" }, "recordSchema": { "type": "object", "properties": { "name": { "description": "Human-readable name for the record type.", "type": "string" }, "fields": { "description": "Field definitions keyed by field name.", "type": "object", "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "string", "number", "boolean", "date" ] }, "label": { "description": "Display label in field pickers.", "type": "string" }, "measure": { "description": "Aggregatable — offered under measures rather than dimensions.", "type": "boolean" }, "timeDimension": { "description": "The field date ranges and time bucketing apply to.", "type": "boolean" } }, "required": [ "type", "label" ] } }, "calculatedFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "description": "Identifier used in query refs, e.g. `ds_….handleRate`.", "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "string", "number", "boolean", "date" ] }, "expression": { "description": "Compiled jsep AST the analytics engine translates to SQL.", "type": "object", "additionalProperties": {} }, "formula": { "description": "Source text the AST was compiled from, shown in the editor.", "type": "string" }, "measure": { "type": "boolean" } }, "required": [ "id", "name", "label", "type", "expression" ] } }, "windowDimensions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "label": { "type": "string" }, "function": { "description": "Rank within group is the only supported function today.", "type": "string", "enum": [ "row_number" ] }, "partitionBy": { "description": "Fields defining the group.", "type": "array", "items": { "type": "string" } }, "orderBy": { "description": "Field ordering rows within the group.", "type": "string" }, "direction": { "description": "asc (default): rank 1 is the earliest row.", "type": "string", "enum": [ "asc", "desc" ] }, "semantic": { "description": "lifetime (default) ranks over the full history and filters after; window-reset filters first, so ranks restart inside the range.", "type": "string", "enum": [ "lifetime", "window-reset" ] } }, "required": [ "id", "name", "label", "function", "partitionBy", "orderBy" ] } } }, "required": [ "name", "fields" ] }, "syncConfig": { "type": "object", "properties": { "syncIntervalMinutes": { "type": "number" }, "lastSyncAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "lastSyncStatus": { "type": "string", "enum": [ "success", "error", "running", "pending" ] }, "lastSyncError": { "type": "string" }, "syncWorkflowId": { "type": "string" }, "syncScheduleId": { "type": "string" }, "syncTriggerId": { "type": "string" }, "lastSyncExecutionId": { "description": "Execution of the most recent sync, for tracing a failure.", "type": "string" } } }, "enabled": { "type": "boolean" }, "sharedFromOrganizationId": { "description": "Set when this source reads another organization’s shared table.", "type": "string" }, "sharedFromOrganizationIds": { "description": "Set on an aggregate source reading the same table across orgs.", "type": "array", "items": { "type": "string" } }, "aggregateEntries": { "description": "Per-org table names an aggregate source unions.", "type": "array", "items": { "type": "object", "properties": { "organizationId": { "type": "string" }, "tableName": { "type": "string" }, "label": { "type": "string" } }, "required": [ "organizationId", "tableName" ] } }, "schemaRefreshedAt": { "description": "When `recordSchema` was last re-sampled from the data.", "type": "string" }, "servingEngine": { "description": "Which engine answers analytics queries for this source.", "type": "string", "enum": [ "postgres", "clickhouse" ] }, "servingRelation": { "description": "ClickHouse table name. Only set on ClickHouse-served sources.", "type": "string" }, "hotPathMode": { "description": "This source’s INTENT for the Postgres hot copy. `evict-after-sync` drops the row once ClickHouse acks it, which makes point reads of the record stop working.", "type": "string", "enum": [ "retain", "evict-after-sync" ] } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "name", "type", "dataStoreTableName", "recordSchema", "enabled", "servingEngine", "hotPathMode" ] }, "DashboardDataSourceReadResponseDto": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Owning organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "userId": { "type": "string" }, "packageInstallId": { "description": "Package install that owns this source. Absent if customer-owned.", "type": "string" }, "packageDataSourceId": { "description": "Publish-time slug from the package manifest.", "type": "string" }, "name": { "type": "string" }, "type": { "description": "Feed type, e.g. `twilio:calls`, or `custom` for a manual source.", "type": "string" }, "connectionId": { "type": "string" }, "connectionName": { "type": "string" }, "dataStoreTableName": { "description": "Data store table records land in.", "type": "string" }, "recordSchema": { "type": "object", "properties": { "name": { "description": "Human-readable name for the record type.", "type": "string" }, "fields": { "description": "Field definitions keyed by field name.", "type": "object", "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "string", "number", "boolean", "date" ] }, "label": { "description": "Display label in field pickers.", "type": "string" }, "measure": { "description": "Aggregatable — offered under measures rather than dimensions.", "type": "boolean" }, "timeDimension": { "description": "The field date ranges and time bucketing apply to.", "type": "boolean" } }, "required": [ "type", "label" ] } }, "calculatedFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "description": "Identifier used in query refs, e.g. `ds_….handleRate`.", "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "string", "number", "boolean", "date" ] }, "expression": { "description": "Compiled jsep AST the analytics engine translates to SQL.", "type": "object", "additionalProperties": {} }, "formula": { "description": "Source text the AST was compiled from, shown in the editor.", "type": "string" }, "measure": { "type": "boolean" } }, "required": [ "id", "name", "label", "type", "expression" ] } }, "windowDimensions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "label": { "type": "string" }, "function": { "description": "Rank within group is the only supported function today.", "type": "string", "enum": [ "row_number" ] }, "partitionBy": { "description": "Fields defining the group.", "type": "array", "items": { "type": "string" } }, "orderBy": { "description": "Field ordering rows within the group.", "type": "string" }, "direction": { "description": "asc (default): rank 1 is the earliest row.", "type": "string", "enum": [ "asc", "desc" ] }, "semantic": { "description": "lifetime (default) ranks over the full history and filters after; window-reset filters first, so ranks restart inside the range.", "type": "string", "enum": [ "lifetime", "window-reset" ] } }, "required": [ "id", "name", "label", "function", "partitionBy", "orderBy" ] } } }, "required": [ "name", "fields" ] }, "syncConfig": { "type": "object", "properties": { "syncIntervalMinutes": { "type": "number" }, "lastSyncAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "lastSyncStatus": { "type": "string", "enum": [ "success", "error", "running", "pending" ] }, "lastSyncError": { "type": "string" }, "syncWorkflowId": { "type": "string" }, "syncScheduleId": { "type": "string" }, "syncTriggerId": { "type": "string" }, "lastSyncExecutionId": { "description": "Execution of the most recent sync, for tracing a failure.", "type": "string" } } }, "enabled": { "type": "boolean" }, "sharedFromOrganizationId": { "description": "Set when this source reads another organization’s shared table.", "type": "string" }, "sharedFromOrganizationIds": { "description": "Set on an aggregate source reading the same table across orgs.", "type": "array", "items": { "type": "string" } }, "aggregateEntries": { "description": "Per-org table names an aggregate source unions.", "type": "array", "items": { "type": "object", "properties": { "organizationId": { "type": "string" }, "tableName": { "type": "string" }, "label": { "type": "string" } }, "required": [ "organizationId", "tableName" ] } }, "schemaRefreshedAt": { "description": "When `recordSchema` was last re-sampled from the data.", "type": "string" }, "servingEngine": { "description": "Which engine answers analytics queries for this source.", "type": "string", "enum": [ "postgres", "clickhouse" ] }, "servingRelation": { "description": "ClickHouse table name. Only set on ClickHouse-served sources.", "type": "string" }, "hotPathMode": { "description": "This source’s INTENT for the Postgres hot copy. `evict-after-sync` drops the row once ClickHouse acks it, which makes point reads of the record stop working.", "type": "string", "enum": [ "retain", "evict-after-sync" ] }, "effectiveHotPathMode": { "description": "Mode actually in force for this source’s table.", "type": "string", "enum": [ "retain", "evict-after-sync" ] } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "name", "type", "dataStoreTableName", "recordSchema", "enabled", "servingEngine", "hotPathMode", "effectiveHotPathMode" ] }, "UpdateDataSourceDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "enabled": { "type": "boolean" }, "recordSchema": { "type": "object", "properties": { "name": { "type": "string" }, "fields": { "type": "object", "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "string", "number", "boolean", "date" ] }, "label": { "type": "string" }, "measure": { "type": "boolean" }, "timeDimension": { "type": "boolean" } }, "required": [ "type", "label" ] } } }, "required": [ "name", "fields" ] }, "syncIntervalMinutes": { "type": "integer", "minimum": 5, "exclusiveMinimum": false, "maximum": 1440, "exclusiveMaximum": false }, "sharedFromOrganizationIds": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "type": "string", "format": "uuid" } }, "aggregateEntries": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "type": "object", "properties": { "organizationId": { "type": "string", "format": "uuid" }, "tableName": { "type": "string", "minLength": 1, "maxLength": 255 }, "label": { "type": "string", "maxLength": 255 } }, "required": [ "organizationId", "tableName" ] } }, "hotPathMode": { "type": "string", "enum": [ "retain", "evict-after-sync" ] }, "confirmTimeFieldRekey": { "type": "boolean" } } }, "DeletedAckResponseDto": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ] }, "TriggerSyncDto": { "type": "object", "properties": { "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time" } } }, "TriggerSyncResultResponseDto": { "type": "object", "properties": { "message": { "description": "Confirmation that the sync workflow was queued.", "type": "string" } }, "required": [ "message" ] }, "ToggleDataFeedDto": { "type": "object", "properties": { "feedKey": { "type": "string", "minLength": 1, "maxLength": 100 }, "connectionId": { "type": "string", "format": "uuid" }, "connectionName": { "type": "string", "minLength": 1 }, "enabled": { "type": "boolean" }, "syncIntervalMinutes": { "type": "integer", "minimum": 5, "exclusiveMinimum": false, "maximum": 1440, "exclusiveMaximum": false } }, "required": [ "feedKey", "connectionId", "connectionName", "enabled" ] }, "ToggleDataFeedResultResponseDto": { "type": "object", "properties": { "enabled": { "description": "Echoes the requested state.", "type": "boolean" }, "dataSourceId": { "description": "The source created or re-enabled. Absent when disabling.", "type": "string" } }, "required": [ "enabled" ] }, "UpdateWidgetDto": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "chartType": { "type": "string", "enum": [ "bar", "line", "pie", "stat-card", "table", "area", "doughnut", "funnel", "stats-table", "pivot-table" ] }, "dataSourceId": { "type": "string", "format": "uuid" }, "queryConfig": { "type": "object", "properties": { "measures": { "type": "array", "items": { "type": "string" } }, "dimensions": { "type": "array", "items": { "type": "string" } }, "timeDimensions": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string" }, "granularity": { "type": "string", "enum": [ "15min", "30min", "hour", "day", "week", "month", "year" ] }, "dateRange": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, "required": [ "dimension" ] } }, "filters": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "member": { "type": "string" }, "dimension": { "type": "string" }, "operator": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } } }, "required": [ "operator" ] }, { "type": "object", "properties": { "expression": { "type": "object", "additionalProperties": {} }, "formula": { "type": "string", "maxLength": 2000 } }, "required": [ "expression" ] } ] } }, "filterExpression": { "type": "object", "additionalProperties": {} }, "filterFormula": { "type": "string", "maxLength": 2000 }, "joins": { "type": "array", "maxItems": 4, "items": { "type": "object", "properties": { "source": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "inner", "left" ] }, "leftField": { "type": "string", "minLength": 1 }, "rightField": { "type": "string", "minLength": 1 }, "keys": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "leftField": { "type": "string", "minLength": 1 }, "rightField": { "type": "string", "minLength": 1 } }, "required": [ "leftField", "rightField" ] } } }, "required": [ "source", "type" ] } }, "comparison": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "previous_period", "same_period_last_year", "custom" ] }, "dateRange": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, "required": [ "mode" ] }, "order": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "asc", "desc" ] } }, "limit": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "rateMode": { "type": "string", "enum": [ "average", "peak" ] }, "timeRange": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "relative", "absolute" ] }, "value": { "type": "string" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "type" ] } } }, "displayConfig": { "type": "object", "additionalProperties": {}, "nullable": true } } }, "DashboardWidgetResponseDto": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Owning organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "userId": { "type": "string" }, "dashboardId": { "type": "string" }, "title": { "type": "string" }, "chartType": { "type": "string", "enum": [ "bar", "line", "pie", "stat-card", "table", "area", "doughnut", "funnel", "stats-table", "pivot-table" ] }, "dataSourceId": { "description": "Data source this widget reads.", "type": "string" }, "queryConfig": { "description": "Analytics query: measures, dimensions, timeDimensions, filters, joins, order and limit. Same shape the create/update widget body accepts.", "type": "object", "additionalProperties": {} }, "displayConfig": { "description": "Chart display overrides merged over the generated options.", "type": "object", "additionalProperties": {} } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "dashboardId", "title", "chartType", "dataSourceId", "queryConfig" ] }, "ValidateDashboardRequestDto": { "type": "object", "properties": { "widgets": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Present when validating an edit.", "type": "string" }, "title": { "type": "string" }, "dataSourceId": { "description": "uuid or `ds_` alias.", "type": "string" }, "queryConfig": { "type": "object", "additionalProperties": {} } }, "required": [ "dataSourceId", "queryConfig" ] } } } }, "DashboardValidationResultResponseDto": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "ruleId": { "description": "Stable rule identifier, e.g. `field-refs` or `schema`.", "type": "string" }, "severity": { "type": "string", "enum": [ "error", "warning" ] }, "message": { "description": "Explains the problem and, where possible, the fix.", "type": "string" }, "widget": { "description": "Widget the issue is anchored to, by title or id.", "type": "string" } }, "required": [ "ruleId", "severity", "message" ] } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "ruleId": { "description": "Stable rule identifier, e.g. `field-refs` or `schema`.", "type": "string" }, "severity": { "type": "string", "enum": [ "error", "warning" ] }, "message": { "description": "Explains the problem and, where possible, the fix.", "type": "string" }, "widget": { "description": "Widget the issue is anchored to, by title or id.", "type": "string" } }, "required": [ "ruleId", "severity", "message" ] } }, "ok": { "description": "True when nothing error-severity was found, i.e. safe to save.", "type": "boolean" } }, "required": [ "errors", "warnings", "ok" ] }, "AnalyticsQueryRequestDto": { "type": "object", "properties": { "query": { "description": "measures, dimensions, timeDimensions, filters, joins, order, limit, offset, timezone. Refs are `.`; discover them from `GET /dashboards/analytics/meta`.", "type": "object", "additionalProperties": {} } }, "required": [ "query" ] }, "AnalyticsQueryResultResponseDto": { "type": "object", "properties": { "data": { "description": "Result rows. Each key is one requested measure or dimension, by its fully qualified `.` ref.", "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "annotation": { "description": "Reserved for per-field display metadata. Empty today.", "type": "object", "additionalProperties": {} }, "query": { "description": "The query as executed, after defaults and formula compilation. Differs from what was sent, which is why it is echoed.", "type": "object", "additionalProperties": {} }, "comparisonData": { "description": "Rows for the comparison period. Present only when the query set `comparison`, and omitted if that sub-query failed.", "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "comparisonDateRange": { "description": "Start and end of the comparison period, as ISO 8601 strings.", "type": "array", "items": { "type": "string" } } }, "required": [ "data", "annotation", "query" ] }, "AnalyticsMetaListResponseDto": { "type": "array", "items": { "type": "object", "properties": { "name": { "description": "Source alias used in query refs, e.g. `ds_9a2f47c1_…`.", "type": "string" }, "title": { "description": "Human-readable data source name.", "type": "string" }, "measures": { "type": "array", "items": { "type": "object", "properties": { "name": { "description": "Fully qualified ref, `.`.", "type": "string" }, "title": { "type": "string" }, "type": { "type": "string" }, "calculated": { "description": "True for user-defined calculated fields.", "type": "boolean" } }, "required": [ "name", "title", "type" ] } }, "dimensions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "title": { "type": "string" }, "type": { "type": "string" }, "calculated": { "type": "boolean" }, "window": { "description": "True for rank-within-group dimensions.", "type": "boolean" } }, "required": [ "name", "title", "type" ] } } }, "required": [ "name", "title", "measures", "dimensions" ] } }, "DistinctValuesRequestDto": { "type": "object", "properties": { "dataSourceId": { "type": "string" }, "dimension": { "description": "Field name, optionally `.` or `:`.", "type": "string" }, "search": { "description": "Substring filter on the values.", "type": "string" }, "limit": { "type": "number" }, "dateRange": { "description": "Relative range such as `last 30 days`, or `[start, end]`.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "timezone": { "description": "IANA timezone name.", "type": "string" } }, "required": [ "dataSourceId", "dimension" ] }, "DistinctValuesResultResponseDto": { "type": "object", "properties": { "values": { "description": "Distinct values for the dimension, for populating a filter control. Empty when the source is missing or disabled.", "type": "array", "items": { "type": "string" } } }, "required": [ "values" ] }, "ReindexedAckResponseDto": { "type": "object", "properties": { "reindexed": { "type": "boolean" } }, "required": [ "reindexed" ] }, "RefreshSchemaResultResponseDto": { "oneOf": [ { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Owning organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "userId": { "type": "string" }, "packageInstallId": { "description": "Package install that owns this source. Absent if customer-owned.", "type": "string" }, "packageDataSourceId": { "description": "Publish-time slug from the package manifest.", "type": "string" }, "name": { "type": "string" }, "type": { "description": "Feed type, e.g. `twilio:calls`, or `custom` for a manual source.", "type": "string" }, "connectionId": { "type": "string" }, "connectionName": { "type": "string" }, "dataStoreTableName": { "description": "Data store table records land in.", "type": "string" }, "recordSchema": { "type": "object", "properties": { "name": { "description": "Human-readable name for the record type.", "type": "string" }, "fields": { "description": "Field definitions keyed by field name.", "type": "object", "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "string", "number", "boolean", "date" ] }, "label": { "description": "Display label in field pickers.", "type": "string" }, "measure": { "description": "Aggregatable — offered under measures rather than dimensions.", "type": "boolean" }, "timeDimension": { "description": "The field date ranges and time bucketing apply to.", "type": "boolean" } }, "required": [ "type", "label" ] } }, "calculatedFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "description": "Identifier used in query refs, e.g. `ds_….handleRate`.", "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "string", "number", "boolean", "date" ] }, "expression": { "description": "Compiled jsep AST the analytics engine translates to SQL.", "type": "object", "additionalProperties": {} }, "formula": { "description": "Source text the AST was compiled from, shown in the editor.", "type": "string" }, "measure": { "type": "boolean" } }, "required": [ "id", "name", "label", "type", "expression" ] } }, "windowDimensions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "label": { "type": "string" }, "function": { "description": "Rank within group is the only supported function today.", "type": "string", "enum": [ "row_number" ] }, "partitionBy": { "description": "Fields defining the group.", "type": "array", "items": { "type": "string" } }, "orderBy": { "description": "Field ordering rows within the group.", "type": "string" }, "direction": { "description": "asc (default): rank 1 is the earliest row.", "type": "string", "enum": [ "asc", "desc" ] }, "semantic": { "description": "lifetime (default) ranks over the full history and filters after; window-reset filters first, so ranks restart inside the range.", "type": "string", "enum": [ "lifetime", "window-reset" ] } }, "required": [ "id", "name", "label", "function", "partitionBy", "orderBy" ] } } }, "required": [ "name", "fields" ] }, "syncConfig": { "type": "object", "properties": { "syncIntervalMinutes": { "type": "number" }, "lastSyncAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "lastSyncStatus": { "type": "string", "enum": [ "success", "error", "running", "pending" ] }, "lastSyncError": { "type": "string" }, "syncWorkflowId": { "type": "string" }, "syncScheduleId": { "type": "string" }, "syncTriggerId": { "type": "string" }, "lastSyncExecutionId": { "description": "Execution of the most recent sync, for tracing a failure.", "type": "string" } } }, "enabled": { "type": "boolean" }, "sharedFromOrganizationId": { "description": "Set when this source reads another organization’s shared table.", "type": "string" }, "sharedFromOrganizationIds": { "description": "Set on an aggregate source reading the same table across orgs.", "type": "array", "items": { "type": "string" } }, "aggregateEntries": { "description": "Per-org table names an aggregate source unions.", "type": "array", "items": { "type": "object", "properties": { "organizationId": { "type": "string" }, "tableName": { "type": "string" }, "label": { "type": "string" } }, "required": [ "organizationId", "tableName" ] } }, "schemaRefreshedAt": { "description": "When `recordSchema` was last re-sampled from the data.", "type": "string" }, "servingEngine": { "description": "Which engine answers analytics queries for this source.", "type": "string", "enum": [ "postgres", "clickhouse" ] }, "servingRelation": { "description": "ClickHouse table name. Only set on ClickHouse-served sources.", "type": "string" }, "hotPathMode": { "description": "This source’s INTENT for the Postgres hot copy. `evict-after-sync` drops the row once ClickHouse acks it, which makes point reads of the record stop working.", "type": "string", "enum": [ "retain", "evict-after-sync" ] } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "name", "type", "dataStoreTableName", "recordSchema", "enabled", "servingEngine", "hotPathMode" ] }, { "type": "object", "properties": { "refreshed": { "type": "boolean" }, "fieldsChanged": { "type": "boolean" } }, "required": [ "refreshed", "fieldsChanged" ] } ] }, "ExportCsvDto": { "type": "object", "properties": { "query": { "type": "object", "properties": { "measures": { "type": "array", "items": { "type": "string" } }, "dimensions": { "type": "array", "items": { "type": "string" } }, "timeDimensions": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string" }, "granularity": { "type": "string", "enum": [ "15min", "30min", "hour", "day", "week", "month", "year" ] }, "dateRange": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, "required": [ "dimension" ] } }, "filters": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "member": { "type": "string" }, "dimension": { "type": "string" }, "operator": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } } }, "required": [ "operator" ] }, { "type": "object", "properties": { "expression": { "type": "object", "additionalProperties": {} }, "formula": { "type": "string", "maxLength": 2000 } }, "required": [ "expression" ] } ] } }, "filterExpression": { "type": "object", "additionalProperties": {} }, "filterFormula": { "type": "string", "maxLength": 2000 }, "search": { "type": "string", "maxLength": 500 }, "order": { "oneOf": [ { "type": "object", "additionalProperties": { "type": "string", "enum": [ "asc", "desc" ] } }, { "type": "array", "items": { "type": "array", "items": { "type": "string" } } } ] }, "limit": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "offset": { "type": "integer", "minimum": 0, "exclusiveMinimum": false }, "timezone": { "type": "string", "maxLength": 100 }, "joins": { "type": "array", "maxItems": 4, "items": { "type": "object", "properties": { "source": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "inner", "left" ] }, "leftField": { "type": "string", "minLength": 1 }, "rightField": { "type": "string", "minLength": 1 }, "keys": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "leftField": { "type": "string", "minLength": 1 }, "rightField": { "type": "string", "minLength": 1 } }, "required": [ "leftField", "rightField" ] } } }, "required": [ "source", "type" ] } }, "rateMode": { "type": "string", "enum": [ "average", "peak" ] } } }, "title": { "type": "string", "maxLength": 255 } }, "required": [ "query" ] }, "CreateCalculatedFieldDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$" }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "type": { "type": "string", "enum": [ "number", "string", "boolean", "date" ] }, "expression": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "Identifier", "Literal", "BinaryExpression", "UnaryExpression", "CallExpression", "ConditionalExpression", "MemberExpression" ] } }, "required": [ "type" ] }, "formula": { "type": "string", "maxLength": 2000 }, "measure": { "type": "boolean" } }, "required": [ "name", "label", "type", "expression" ] }, "CalculatedFieldResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "description": "Identifier used in query refs, e.g. `ds_….handleRate`.", "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "string", "number", "boolean", "date" ] }, "expression": { "description": "Compiled jsep AST the analytics engine translates to SQL.", "type": "object", "additionalProperties": {} }, "formula": { "description": "Source text the AST was compiled from, shown in the editor.", "type": "string" }, "measure": { "type": "boolean" } }, "required": [ "id", "name", "label", "type", "expression" ] }, "UpdateCalculatedFieldDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$" }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "type": { "type": "string", "enum": [ "number", "string", "boolean", "date" ] }, "expression": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "Identifier", "Literal", "BinaryExpression", "UnaryExpression", "CallExpression", "ConditionalExpression", "MemberExpression" ] } }, "required": [ "type" ] }, "formula": { "type": "string", "maxLength": 2000 }, "measure": { "type": "boolean" } } }, "PreviewCalculatedFieldDto": { "type": "object", "properties": { "expression": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "Identifier", "Literal", "BinaryExpression", "UnaryExpression", "CallExpression", "ConditionalExpression", "MemberExpression" ] } }, "required": [ "type" ] }, "type": { "type": "string", "enum": [ "number", "string", "boolean", "date" ] } }, "required": [ "expression", "type" ] }, "CalculatedFieldPreviewResponseDto": { "type": "object", "properties": { "values": { "description": "The expression evaluated over a sample of rows. Element type follows the requested `type`, and a row the expression cannot evaluate yields null.", "type": "array", "items": {} } }, "required": [ "values" ] }, "CreateWindowDimensionDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$" }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "function": { "type": "string", "enum": [ "row_number" ] }, "partitionBy": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "type": "string", "minLength": 1 } }, "orderBy": { "type": "string", "minLength": 1 }, "direction": { "type": "string", "enum": [ "asc", "desc" ] }, "semantic": { "type": "string", "enum": [ "lifetime", "window-reset" ] } }, "required": [ "name", "label", "function", "partitionBy", "orderBy" ] }, "WindowDimensionResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "label": { "type": "string" }, "function": { "description": "Rank within group is the only supported function today.", "type": "string", "enum": [ "row_number" ] }, "partitionBy": { "description": "Fields defining the group.", "type": "array", "items": { "type": "string" } }, "orderBy": { "description": "Field ordering rows within the group.", "type": "string" }, "direction": { "description": "asc (default): rank 1 is the earliest row.", "type": "string", "enum": [ "asc", "desc" ] }, "semantic": { "description": "lifetime (default) ranks over the full history and filters after; window-reset filters first, so ranks restart inside the range.", "type": "string", "enum": [ "lifetime", "window-reset" ] } }, "required": [ "id", "name", "label", "function", "partitionBy", "orderBy" ] }, "UpdateWindowDimensionDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z][a-zA-Z0-9_]*$" }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "function": { "type": "string", "enum": [ "row_number" ] }, "partitionBy": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "type": "string", "minLength": 1 } }, "orderBy": { "type": "string", "minLength": 1 }, "direction": { "type": "string", "enum": [ "asc", "desc" ] }, "semantic": { "type": "string", "enum": [ "lifetime", "window-reset" ] } } }, "CreateDataStoreShareDto": { "type": "object", "properties": { "tableName": { "type": "string", "minLength": 1, "maxLength": 255 }, "sharedToOrganizationId": { "type": "string", "format": "uuid" }, "sharedToOrganizationSuid": { "type": "string", "minLength": 1, "maxLength": 100 }, "alias": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "tableName", "alias" ] }, "DataStoreShareResponseDto": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Owning organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "userId": { "type": "string" }, "ownerOrganizationId": { "description": "Organization that owns the data.", "type": "string" }, "tableName": { "description": "Data store table being shared.", "type": "string" }, "sharedToOrganizationId": { "description": "Organization granted read access.", "type": "string" }, "alias": { "description": "Name the table appears under in the receiving organization.", "type": "string" }, "readOnly": { "description": "Always true: a share never grants write access.", "type": "boolean" }, "revokedAt": { "description": "Set once revoked. Absent on an active share.", "type": "string" } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "ownerOrganizationId", "tableName", "sharedToOrganizationId", "alias", "readOnly" ] }, "DataStoreShareListResponseDto": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Owning organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "userId": { "type": "string" }, "ownerOrganizationId": { "description": "Organization that owns the data.", "type": "string" }, "tableName": { "description": "Data store table being shared.", "type": "string" }, "sharedToOrganizationId": { "description": "Organization granted read access.", "type": "string" }, "alias": { "description": "Name the table appears under in the receiving organization.", "type": "string" }, "readOnly": { "description": "Always true: a share never grants write access.", "type": "boolean" }, "revokedAt": { "description": "Set once revoked. Absent on an active share.", "type": "string" } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "ownerOrganizationId", "tableName", "sharedToOrganizationId", "alias", "readOnly" ] } }, "ReceivedDataStoreShareListResponseDto": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Owning organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "userId": { "type": "string" }, "ownerOrganizationId": { "description": "Organization that owns the data.", "type": "string" }, "tableName": { "description": "Data store table being shared.", "type": "string" }, "sharedToOrganizationId": { "description": "Organization granted read access.", "type": "string" }, "alias": { "description": "Name the table appears under in the receiving organization.", "type": "string" }, "readOnly": { "description": "Always true: a share never grants write access.", "type": "boolean" }, "revokedAt": { "description": "Set once revoked. Absent on an active share.", "type": "string" }, "analyticsTag": { "description": "Feed type the owner tagged the table with, e.g. `twilio:calls`. Absent on tables that predate tagging.", "type": "string" } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "ownerOrganizationId", "tableName", "sharedToOrganizationId", "alias", "readOnly" ] } }, "RevokedAckResponseDto": { "type": "object", "properties": { "revoked": { "type": "boolean" } }, "required": [ "revoked" ] }, "ExportPdfDto": { "type": "object", "properties": { "html": { "type": "string", "maxLength": 26214400 }, "title": { "type": "string", "maxLength": 255 }, "landscape": { "type": "boolean", "default": true }, "pageSize": { "type": "string", "maxLength": 20, "default": "A4" }, "includePageNumbers": { "type": "boolean", "default": true } }, "required": [ "html" ] }, "UpdateDashboardDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "nullable": true }, "isDefault": { "type": "boolean" }, "filterConfig": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "dataSourceId": { "type": "string", "format": "uuid" }, "dimension": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "bindings": { "type": "array", "items": { "type": "object", "properties": { "dataSourceId": { "type": "string", "format": "uuid" }, "dimension": { "type": "string", "minLength": 1 } }, "required": [ "dataSourceId", "dimension" ] } } }, "required": [ "id", "dataSourceId", "dimension", "label" ] }, "nullable": true }, "filterDefaults": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "nullable": true }, "timezone": { "type": "string", "maxLength": 100, "nullable": true } } }, "SaveDashboardLayoutDto": { "type": "object", "properties": { "layout": { "type": "array", "items": { "type": "object", "properties": { "widgetId": { "type": "string", "format": "uuid" }, "x": { "type": "integer", "minimum": 0, "exclusiveMinimum": false }, "y": { "type": "integer", "minimum": 0, "exclusiveMinimum": false }, "w": { "type": "integer", "minimum": 1, "exclusiveMinimum": false }, "h": { "type": "integer", "minimum": 1, "exclusiveMinimum": false }, "minW": { "type": "integer", "minimum": 1, "exclusiveMinimum": false }, "minH": { "type": "integer", "minimum": 1, "exclusiveMinimum": false } }, "required": [ "widgetId", "x", "y", "w", "h" ] } } }, "required": [ "layout" ] }, "CreateWidgetDto": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "chartType": { "type": "string", "enum": [ "bar", "line", "pie", "stat-card", "table", "area", "doughnut", "funnel", "stats-table", "pivot-table" ] }, "dataSourceId": { "type": "string", "format": "uuid" }, "queryConfig": { "type": "object", "properties": { "measures": { "type": "array", "items": { "type": "string" } }, "dimensions": { "type": "array", "items": { "type": "string" } }, "timeDimensions": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string" }, "granularity": { "type": "string", "enum": [ "15min", "30min", "hour", "day", "week", "month", "year" ] }, "dateRange": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, "required": [ "dimension" ] } }, "filters": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "member": { "type": "string" }, "dimension": { "type": "string" }, "operator": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } } }, "required": [ "operator" ] }, { "type": "object", "properties": { "expression": { "type": "object", "additionalProperties": {} }, "formula": { "type": "string", "maxLength": 2000 } }, "required": [ "expression" ] } ] } }, "filterExpression": { "type": "object", "additionalProperties": {} }, "filterFormula": { "type": "string", "maxLength": 2000 }, "joins": { "type": "array", "maxItems": 4, "items": { "type": "object", "properties": { "source": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "inner", "left" ] }, "leftField": { "type": "string", "minLength": 1 }, "rightField": { "type": "string", "minLength": 1 }, "keys": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "leftField": { "type": "string", "minLength": 1 }, "rightField": { "type": "string", "minLength": 1 } }, "required": [ "leftField", "rightField" ] } } }, "required": [ "source", "type" ] } }, "comparison": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "previous_period", "same_period_last_year", "custom" ] }, "dateRange": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, "required": [ "mode" ] }, "order": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "asc", "desc" ] } }, "limit": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "rateMode": { "type": "string", "enum": [ "average", "peak" ] }, "timeRange": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "relative", "absolute" ] }, "value": { "type": "string" }, "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "type" ] } } }, "displayConfig": { "type": "object", "additionalProperties": {} } }, "required": [ "title", "chartType", "dataSourceId", "queryConfig" ] }, "KnowledgeBaseDocumentResponseDto": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Owning organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "knowledgeBase": { "description": "Id of the knowledge base this document belongs to.", "type": "string" }, "name": { "description": "Uploaded file name, or the source URL for a URL document. Unique within the knowledge base: re-adding the same name replaces the existing document rather than creating a second one.", "type": "string" }, "mimeType": { "description": "Content type of the source. Always `text/html` for URL documents. PDF, DOCX, plain text, Markdown, CSV and HTML are parsed natively; anything else is read as UTF-8 text.", "type": "string" }, "fileSize": { "description": "Size in bytes as a decimal string — the column is a `bigint`, which serializes as a string to stay exact. `\"0\"` for URL documents: the fetched body is never sized or stored.", "type": "string" }, "sourceType": { "description": "How the document got here. Only `url` documents can be resynced.", "type": "string", "enum": [ "file", "url" ] }, "sourceUrl": { "description": "Fetched URL. Absent for uploaded files.", "type": "string", "nullable": true }, "storagePath": { "description": "`gs://` URI of the stored original. Empty string for URL documents, which are re-fetched rather than archived.", "type": "string" }, "status": { "description": "Ingestion state. `pending` on arrival, then `processing` while the text is chunked and embedded, then `ready` or `failed`. Poll `GET /knowledge-bases/{id}/documents` to observe the transition.", "type": "string", "enum": [ "pending", "processing", "ready", "failed" ] }, "errorMessage": { "description": "Why ingestion failed. Only set while `status` is `failed`; cleared on resync.", "type": "string", "nullable": true }, "chunkCount": { "description": "Embedded chunks. `0` until ingestion reaches `ready`.", "type": "number" }, "userId": { "description": "User who added the document.", "type": "string", "nullable": true }, "metadata": { "description": "Caller-owned metadata.", "type": "object", "additionalProperties": {} } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "knowledgeBase", "name", "mimeType", "fileSize", "sourceType", "storagePath", "status", "chunkCount", "metadata" ] }, "KnowledgeBaseErrorResponseDto": { "type": "object", "properties": { "statusCode": { "type": "number" }, "message": { "type": "string" }, "error": { "description": "Additional detail, when available." } }, "required": [ "statusCode", "message" ] }, "KnowledgeBaseDocumentDeletedResponseDto": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ] }, "KnowledgeBaseListResponseDto": { "type": "object", "properties": { "total": { "description": "Total records matching the filter, ignoring paging.", "type": "number" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Owning organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "name": { "description": "Unique within the organization: creating a second knowledge base with the same name fails.", "type": "string" }, "description": { "description": "Free-text note about what this collection holds.", "type": "string", "nullable": true }, "embeddingModel": { "description": "Model used to embed this collection’s chunks. Fixed at creation: changing it would invalidate every embedding already stored.", "type": "string" }, "userId": { "description": "User who created the knowledge base.", "type": "string", "nullable": true }, "metadata": { "description": "Caller-owned metadata.", "type": "object", "additionalProperties": {} } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "name", "embeddingModel", "metadata" ] } } }, "required": [ "total", "data" ] }, "CreateKnowledgeBaseDto": { "type": "object", "properties": { "organizationId": { "type": "string", "format": "uuid" }, "userId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {} }, "updatedAt": {}, "createdAt": {}, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 2000 }, "embeddingModel": { "type": "string", "default": "text-embedding-3-small" } }, "required": [ "name" ] }, "KnowledgeBaseResponseDto": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Owning organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "name": { "description": "Unique within the organization: creating a second knowledge base with the same name fails.", "type": "string" }, "description": { "description": "Free-text note about what this collection holds.", "type": "string", "nullable": true }, "embeddingModel": { "description": "Model used to embed this collection’s chunks. Fixed at creation: changing it would invalidate every embedding already stored.", "type": "string" }, "userId": { "description": "User who created the knowledge base.", "type": "string", "nullable": true }, "metadata": { "description": "Caller-owned metadata.", "type": "object", "additionalProperties": {} } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "name", "embeddingModel", "metadata" ] }, "UpdateKnowledgeBaseDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 2000 } } }, "OrganizationListResponseDto": { "type": "object", "properties": { "total": { "description": "Total matching organizations, ignoring paging.", "type": "number" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Organization id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "name": { "type": "string" }, "userId": { "description": "User who created the organization.", "type": "string" }, "organizationId": { "description": "Always equal to `id`. Present for consistency with other resources.", "type": "string" }, "metadata": { "description": "Caller-owned metadata.", "type": "object", "additionalProperties": {} }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" } }, "required": [ "id", "suid", "name", "userId", "organizationId", "metadata", "createdAt", "updatedAt" ] } } }, "required": [ "total", "data" ] }, "CreateOrganizationBodyDto": { "type": "object", "properties": { "name": { "description": "Human-readable name for the organization.", "type": "string", "minLength": 1, "maxLength": 200 }, "metadata": { "type": "object", "additionalProperties": {} } }, "required": [ "name" ] }, "OrganizationResponseDto": { "type": "object", "properties": { "id": { "description": "Organization id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "name": { "type": "string" }, "userId": { "description": "User who created the organization.", "type": "string" }, "organizationId": { "description": "Always equal to `id`. Present for consistency with other resources.", "type": "string" }, "metadata": { "description": "Caller-owned metadata.", "type": "object", "additionalProperties": {} }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" } }, "required": [ "id", "suid", "name", "userId", "organizationId", "metadata", "createdAt", "updatedAt" ] }, "UpdateOrganizationBodyDto": { "type": "object", "properties": { "name": { "description": "Human-readable name for the organization.", "type": "string", "minLength": 1, "maxLength": 200 }, "metadata": { "type": "object", "additionalProperties": {} } } }, "ExecutionTraceListResponseDto": { "type": "object", "properties": { "total": { "description": "Total records matching the filter, ignoring paging.", "type": "number" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Owning organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "userId": { "description": "Identity that started the run, when a user started it.", "type": "string" }, "metadata": { "description": "Caller-owned metadata.", "type": "object", "additionalProperties": {} }, "workflowId": { "description": "Workflow this run executed.", "type": "string" }, "workflowName": { "description": "Workflow name as of the run. Denormalized, not a live lookup.", "type": "string" }, "status": { "description": "Where the run stands. `crashed` and `suspended` are not terminal: both are resumable and may move to a terminal status later.", "type": "string", "enum": [ "running", "success", "completed_with_errors", "failed", "cancelled", "rejected", "crashed", "suspended", "timed_out" ] }, "operationalStatus": { "description": "Roll-up of every step’s operational outcome. Distinct from `status`: a run can read `success` while this reads `error`. Absent while running and for rejected runs.", "type": "string", "enum": [ "ok", "warning", "error" ] }, "operationalMessages": { "description": "Capped roll-up of the run’s operational and continue-on-error failures. The complete set lives in the trace blob’s `$errors`.", "type": "array", "items": { "type": "object", "properties": { "stepId": { "type": "string" }, "stepType": { "type": "string" }, "type": { "type": "string", "enum": [ "operational", "execution" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "severity": { "type": "string", "enum": [ "warning", "error" ] }, "cause": { "type": "string", "enum": [ "transient", "permanent", "unknown" ] }, "isRetryable": { "type": "boolean" } }, "required": [ "stepId", "stepType", "type", "code", "message", "severity" ] } }, "failureCode": { "description": "Short snake_case classification of a terminal state, e.g. `auth_failed`, `payload_too_large`, `resume_cap_exhausted`. The human-readable message is in `error`.", "type": "string" }, "error": { "description": "Human-readable failure message.", "type": "string" }, "startedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "completedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "durationMilliseconds": { "type": "number" }, "totalSteps": { "type": "number" }, "stepsExecuted": { "type": "number" }, "stepsFailed": { "type": "number" }, "stepsSkipped": { "type": "number" }, "contextMemoryPeakBytes": { "description": "Peak size of the run’s in-memory context, in bytes.", "type": "number" }, "triggerType": { "description": "What started the run, e.g. `manual`, `webhook`, `schedule`, `api`.", "type": "string" }, "workerTier": { "description": "Execution tier the run was routed to, e.g. `standard`, `heavy`, `xl`.", "type": "string" }, "searchAttributes": { "description": "Flat, dot-notated attributes lifted from the run’s initial input. Only fields the workflow marked `x-searchable` appear here; they are what `where[searchAttributes]` filters against.", "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "initialPayload": { "description": "Captured request for a rejected run (method, query, redacted headers, body preview). Rejected runs write no trace blob, so this is the only record of what was sent.", "type": "object", "additionalProperties": {} }, "parentExecutionId": { "description": "Run that spawned this one. Absent means this run is a root.", "type": "string" }, "rootExecutionId": { "description": "Top-level ancestor, at any nesting depth. Absent on roots. Filter on it to pull a whole sub-workflow tree in one query.", "type": "string" }, "stepStatuses": { "description": "Compact per-step index keyed by step id, deliberately abbreviated to keep the row small: `s` status (`s`/`f`/`k`), `d` duration ms, `b` output bytes, `e` error message, `n` nested steps. Outputs are NOT here — fetch them per step.", "type": "object", "additionalProperties": {} }, "stepPaths": { "description": "Step id to its stored path, e.g. `for-each-1/3/send-email`. Pass a value from here as `stepPath` to disambiguate a nested step.", "type": "object", "additionalProperties": { "type": "string" } }, "activeStepProgress": { "description": "Live loop progress while the run is open, keyed by step id. Nested loops report both levels. Cleared once the loops finish.", "type": "object", "additionalProperties": { "type": "object", "properties": { "stepId": { "type": "string" }, "currentIteration": { "type": "number" }, "totalIterations": { "type": "number" } }, "required": [ "stepId", "currentIteration", "totalIterations" ] }, "nullable": true }, "traceStorageUri": { "description": "Where the run’s trace blob lives. Absent means there is nothing to download — rejected runs never write one.", "type": "string" }, "cancelRequestedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "cancelRequestedBy": { "description": "Identity that asked to cancel.", "type": "string" }, "archivedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "archivedBy": { "description": "Identity that archived the run.", "type": "string" }, "executionEpoch": { "description": "Incarnation counter. Every claim of the run mints a new epoch and fences off the previous owner.", "type": "number" }, "resumeAttempts": { "description": "Crash-shaped resumes so far. Voluntary wakes from `suspended` do not count. Exhausting the cap fails the run.", "type": "number" }, "heartbeatAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "parkInterruptedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "instanceId": { "description": "Worker instance hosting the current incarnation.", "type": "string" }, "crashedInstanceId": { "description": "Instance the run last died on. Lets one incident be split into the instance that failed and the runs it took with it.", "type": "string" }, "pinnedJobHash": { "description": "Digest of the pinned payload a resume re-enters through. Absent means the run cannot be resumed after a crash.", "type": "string" }, "suspension": { "description": "Why the run is parked. Present iff `status` is `suspended`.", "type": "object", "properties": { "reason": { "description": "What parked the run. `deploy` = graceful-shutdown park.", "type": "string", "enum": [ "deploy", "human-input", "webhook", "timer" ] }, "payload": { "description": "Reason-specific data, e.g. the condition a wait step yielded.", "type": "object", "additionalProperties": {} }, "expiresAt": { "description": "After this instant the run is re-published unprompted. Absent means the run sleeps until something external answers it.", "type": "string" }, "resumeToken": { "description": "Opaque token a future external resume call must present.", "type": "string" } }, "required": [ "reason" ] }, "externalInputs": { "description": "Recorded answers keyed by the waiting step’s path.", "type": "object", "additionalProperties": { "type": "object", "properties": { "gcsRef": { "description": "Stored location of the answer payload.", "type": "string" }, "receivedAt": { "description": "ISO 8601 timestamp.", "type": "string" } }, "required": [ "gcsRef", "receivedAt" ] } }, "checkpoint": { "description": "Legacy pause column, superseded by `suspension`. Only historical rows carry it; it is not writable through the API.", "type": "object", "additionalProperties": {} } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "workflowId", "status", "startedAt", "executionEpoch", "resumeAttempts" ] } }, "childCounts": { "description": "Descendant count per root run, so a grouped view can badge each row without a second request. Only present on a roots-only query (`where[parentExecutionId]=null`), and only for roots that have descendants.", "type": "object", "additionalProperties": { "type": "number" } } }, "required": [ "total", "data" ] }, "CreateExecutionTraceDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "minLength": 1 }, "userId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {} }, "updatedAt": {}, "createdAt": {}, "workflowId": { "type": "string", "minLength": 1 }, "workflowName": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "completed_with_errors", "failed", "cancelled", "rejected", "crashed", "suspended", "timed_out" ] }, "operationalStatus": { "type": "string", "enum": [ "ok", "warning", "error" ] }, "operationalMessages": { "type": "array", "items": { "type": "object", "properties": { "stepId": { "type": "string" }, "stepType": { "type": "string" }, "type": { "type": "string", "enum": [ "operational", "execution" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "severity": { "type": "string", "enum": [ "warning", "error" ] }, "cause": { "type": "string", "enum": [ "transient", "permanent", "unknown" ] }, "isRetryable": { "type": "boolean" } }, "required": [ "stepId", "stepType", "type", "code", "message", "severity" ] } }, "startedAt": {}, "completedAt": {}, "durationMilliseconds": { "type": "integer", "minimum": 0, "exclusiveMinimum": false }, "totalSteps": { "type": "integer", "minimum": 0, "exclusiveMinimum": false }, "stepsExecuted": { "type": "integer", "minimum": 0, "exclusiveMinimum": false }, "stepsFailed": { "type": "integer", "minimum": 0, "exclusiveMinimum": false }, "stepsSkipped": { "type": "integer", "minimum": 0, "exclusiveMinimum": false }, "error": { "type": "string" }, "contextMemoryPeakBytes": { "type": "integer", "minimum": 0, "exclusiveMinimum": false }, "traceStorageUri": { "type": "string" }, "workerTier": { "type": "string", "enum": [ "standard", "heavy", "xl" ] }, "stepStatuses": { "type": "object", "additionalProperties": {} }, "stepPaths": { "type": "object", "additionalProperties": { "type": "string" } }, "activeStepProgress": { "type": "object", "additionalProperties": { "type": "object", "properties": { "stepId": { "type": "string" }, "currentIteration": { "type": "integer", "minimum": 0, "exclusiveMinimum": false }, "totalIterations": { "type": "integer", "minimum": 0, "exclusiveMinimum": false } }, "required": [ "stepId", "currentIteration", "totalIterations" ] }, "nullable": true }, "cancelRequestedAt": {}, "cancelRequestedBy": { "type": "string" }, "archivedAt": {}, "archivedBy": { "type": "string" }, "parentExecutionId": { "type": "string" }, "rootExecutionId": { "type": "string" } }, "required": [ "id", "organizationId", "workflowId", "status", "startedAt", "completedAt", "durationMilliseconds" ] }, "ExecutionTraceResponseDto": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Owning organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "userId": { "description": "Identity that started the run, when a user started it.", "type": "string" }, "metadata": { "description": "Caller-owned metadata.", "type": "object", "additionalProperties": {} }, "workflowId": { "description": "Workflow this run executed.", "type": "string" }, "workflowName": { "description": "Workflow name as of the run. Denormalized, not a live lookup.", "type": "string" }, "status": { "description": "Where the run stands. `crashed` and `suspended` are not terminal: both are resumable and may move to a terminal status later.", "type": "string", "enum": [ "running", "success", "completed_with_errors", "failed", "cancelled", "rejected", "crashed", "suspended", "timed_out" ] }, "operationalStatus": { "description": "Roll-up of every step’s operational outcome. Distinct from `status`: a run can read `success` while this reads `error`. Absent while running and for rejected runs.", "type": "string", "enum": [ "ok", "warning", "error" ] }, "operationalMessages": { "description": "Capped roll-up of the run’s operational and continue-on-error failures. The complete set lives in the trace blob’s `$errors`.", "type": "array", "items": { "type": "object", "properties": { "stepId": { "type": "string" }, "stepType": { "type": "string" }, "type": { "type": "string", "enum": [ "operational", "execution" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "severity": { "type": "string", "enum": [ "warning", "error" ] }, "cause": { "type": "string", "enum": [ "transient", "permanent", "unknown" ] }, "isRetryable": { "type": "boolean" } }, "required": [ "stepId", "stepType", "type", "code", "message", "severity" ] } }, "failureCode": { "description": "Short snake_case classification of a terminal state, e.g. `auth_failed`, `payload_too_large`, `resume_cap_exhausted`. The human-readable message is in `error`.", "type": "string" }, "error": { "description": "Human-readable failure message.", "type": "string" }, "startedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "completedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "durationMilliseconds": { "type": "number" }, "totalSteps": { "type": "number" }, "stepsExecuted": { "type": "number" }, "stepsFailed": { "type": "number" }, "stepsSkipped": { "type": "number" }, "contextMemoryPeakBytes": { "description": "Peak size of the run’s in-memory context, in bytes.", "type": "number" }, "triggerType": { "description": "What started the run, e.g. `manual`, `webhook`, `schedule`, `api`.", "type": "string" }, "workerTier": { "description": "Execution tier the run was routed to, e.g. `standard`, `heavy`, `xl`.", "type": "string" }, "searchAttributes": { "description": "Flat, dot-notated attributes lifted from the run’s initial input. Only fields the workflow marked `x-searchable` appear here; they are what `where[searchAttributes]` filters against.", "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "initialPayload": { "description": "Captured request for a rejected run (method, query, redacted headers, body preview). Rejected runs write no trace blob, so this is the only record of what was sent.", "type": "object", "additionalProperties": {} }, "parentExecutionId": { "description": "Run that spawned this one. Absent means this run is a root.", "type": "string" }, "rootExecutionId": { "description": "Top-level ancestor, at any nesting depth. Absent on roots. Filter on it to pull a whole sub-workflow tree in one query.", "type": "string" }, "stepStatuses": { "description": "Compact per-step index keyed by step id, deliberately abbreviated to keep the row small: `s` status (`s`/`f`/`k`), `d` duration ms, `b` output bytes, `e` error message, `n` nested steps. Outputs are NOT here — fetch them per step.", "type": "object", "additionalProperties": {} }, "stepPaths": { "description": "Step id to its stored path, e.g. `for-each-1/3/send-email`. Pass a value from here as `stepPath` to disambiguate a nested step.", "type": "object", "additionalProperties": { "type": "string" } }, "activeStepProgress": { "description": "Live loop progress while the run is open, keyed by step id. Nested loops report both levels. Cleared once the loops finish.", "type": "object", "additionalProperties": { "type": "object", "properties": { "stepId": { "type": "string" }, "currentIteration": { "type": "number" }, "totalIterations": { "type": "number" } }, "required": [ "stepId", "currentIteration", "totalIterations" ] }, "nullable": true }, "traceStorageUri": { "description": "Where the run’s trace blob lives. Absent means there is nothing to download — rejected runs never write one.", "type": "string" }, "cancelRequestedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "cancelRequestedBy": { "description": "Identity that asked to cancel.", "type": "string" }, "archivedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "archivedBy": { "description": "Identity that archived the run.", "type": "string" }, "executionEpoch": { "description": "Incarnation counter. Every claim of the run mints a new epoch and fences off the previous owner.", "type": "number" }, "resumeAttempts": { "description": "Crash-shaped resumes so far. Voluntary wakes from `suspended` do not count. Exhausting the cap fails the run.", "type": "number" }, "heartbeatAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "parkInterruptedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "instanceId": { "description": "Worker instance hosting the current incarnation.", "type": "string" }, "crashedInstanceId": { "description": "Instance the run last died on. Lets one incident be split into the instance that failed and the runs it took with it.", "type": "string" }, "pinnedJobHash": { "description": "Digest of the pinned payload a resume re-enters through. Absent means the run cannot be resumed after a crash.", "type": "string" }, "suspension": { "description": "Why the run is parked. Present iff `status` is `suspended`.", "type": "object", "properties": { "reason": { "description": "What parked the run. `deploy` = graceful-shutdown park.", "type": "string", "enum": [ "deploy", "human-input", "webhook", "timer" ] }, "payload": { "description": "Reason-specific data, e.g. the condition a wait step yielded.", "type": "object", "additionalProperties": {} }, "expiresAt": { "description": "After this instant the run is re-published unprompted. Absent means the run sleeps until something external answers it.", "type": "string" }, "resumeToken": { "description": "Opaque token a future external resume call must present.", "type": "string" } }, "required": [ "reason" ] }, "externalInputs": { "description": "Recorded answers keyed by the waiting step’s path.", "type": "object", "additionalProperties": { "type": "object", "properties": { "gcsRef": { "description": "Stored location of the answer payload.", "type": "string" }, "receivedAt": { "description": "ISO 8601 timestamp.", "type": "string" } }, "required": [ "gcsRef", "receivedAt" ] } }, "checkpoint": { "description": "Legacy pause column, superseded by `suspension`. Only historical rows carry it; it is not writable through the API.", "type": "object", "additionalProperties": {} } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "workflowId", "status", "startedAt", "executionEpoch", "resumeAttempts" ] }, "ExecutionStepOutputResponseDto": { "type": "object", "properties": { "$meta": { "description": "Engine-attached step metadata.", "type": "object", "properties": { "success": { "description": "Whether the step executed without throwing.", "type": "boolean" }, "error": { "description": "Serialized error when the step threw; null otherwise.", "type": "object", "additionalProperties": {}, "nullable": true }, "skipped": { "description": "Whether a `skipIf` condition skipped the step.", "type": "boolean" }, "durationMilliseconds": { "type": "number" }, "stepType": { "description": "Step type identifier, e.g. `core.http`.", "type": "string" }, "outputSizeBytes": { "type": "number" }, "retry": { "description": "Present when the step carries a retry policy.", "type": "object", "properties": { "attempts": { "description": "Retries made. 0 = succeeded first try.", "type": "number" }, "succeededOnRetry": { "type": "boolean" } }, "required": [ "attempts", "succeededOnRetry" ] }, "operationalStatus": { "description": "Present when the step classifies its own output. A step can succeed at the engine level and still fail operationally (HTTP 400, API fault).", "type": "string", "enum": [ "ok", "warning", "error" ] }, "operationalErrors": { "description": "Detail behind a `warning` or `error` operational status.", "type": "array", "items": { "type": "object", "additionalProperties": {} } } }, "required": [ "success" ] }, "$input": { "description": "The step’s resolved input, with credential values redacted." }, "$preview": { "description": "Present and true when the real output exceeded the view cap and this is a bounded sketch of it rather than the whole thing.", "type": "boolean" }, "$truncated": { "description": "Present when the output exceeded the 10485760-byte view cap. Still returned at HTTP 200 — download the full trace to get the untruncated value.", "type": "object", "properties": { "sizeBytes": { "description": "Best-known size of the real output, when known.", "type": "number" }, "capBytes": { "description": "The cap that was exceeded.", "type": "number" }, "hasPreview": { "description": "Whether a sketch of the body is included, or only metadata.", "type": "boolean" } }, "required": [ "capBytes", "hasPreview" ] } } }, "UpdateExecutionTraceDto": { "type": "object", "properties": { "userId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {} }, "updatedAt": {}, "createdAt": {}, "workflowId": { "type": "string", "minLength": 1 }, "workflowName": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "success", "completed_with_errors", "failed", "cancelled", "rejected", "crashed", "suspended", "timed_out" ] }, "operationalStatus": { "type": "string", "enum": [ "ok", "warning", "error" ] }, "operationalMessages": { "type": "array", "items": { "type": "object", "properties": { "stepId": { "type": "string" }, "stepType": { "type": "string" }, "type": { "type": "string", "enum": [ "operational", "execution" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "severity": { "type": "string", "enum": [ "warning", "error" ] }, "cause": { "type": "string", "enum": [ "transient", "permanent", "unknown" ] }, "isRetryable": { "type": "boolean" } }, "required": [ "stepId", "stepType", "type", "code", "message", "severity" ] } }, "startedAt": {}, "completedAt": {}, "durationMilliseconds": { "type": "integer", "minimum": 0, "exclusiveMinimum": false }, "totalSteps": { "type": "integer", "minimum": 0, "exclusiveMinimum": false }, "stepsExecuted": { "type": "integer", "minimum": 0, "exclusiveMinimum": false }, "stepsFailed": { "type": "integer", "minimum": 0, "exclusiveMinimum": false }, "stepsSkipped": { "type": "integer", "minimum": 0, "exclusiveMinimum": false }, "error": { "type": "string" }, "contextMemoryPeakBytes": { "type": "integer", "minimum": 0, "exclusiveMinimum": false }, "traceStorageUri": { "type": "string" }, "workerTier": { "type": "string", "enum": [ "standard", "heavy", "xl" ] }, "stepStatuses": { "type": "object", "additionalProperties": {} }, "stepPaths": { "type": "object", "additionalProperties": { "type": "string" } }, "activeStepProgress": { "type": "object", "additionalProperties": { "type": "object", "properties": { "stepId": { "type": "string" }, "currentIteration": { "type": "integer", "minimum": 0, "exclusiveMinimum": false }, "totalIterations": { "type": "integer", "minimum": 0, "exclusiveMinimum": false } }, "required": [ "stepId", "currentIteration", "totalIterations" ] }, "nullable": true }, "cancelRequestedAt": {}, "cancelRequestedBy": { "type": "string" }, "archivedAt": {}, "archivedBy": { "type": "string" }, "parentExecutionId": { "type": "string" }, "rootExecutionId": { "type": "string" } } }, "BulkExecutionTraceIdsDto": { "type": "object", "properties": { "ids": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "string", "format": "uuid" } } }, "required": [ "ids" ] }, "ExecutionBulkArchiveResponseDto": { "type": "object", "properties": { "archived": { "description": "Runs actually archived. Ids already archived are not counted.", "type": "number" } }, "required": [ "archived" ] }, "ExecutionBulkUnarchiveResponseDto": { "type": "object", "properties": { "unarchived": { "description": "Runs actually restored.", "type": "number" } }, "required": [ "unarchived" ] }, "ExecutionBulkCancelResponseDto": { "type": "object", "properties": { "cancelled": { "description": "Cancel requests issued. Runs that were not running are skipped, so this can be lower than the number of ids sent.", "type": "number" } }, "required": [ "cancelled" ] }, "RecordExternalInputDto": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[a-zA-Z0-9_\\-/]+$" }, "payload": {} }, "required": [ "path", "payload" ] }, "ExecutionExternalInputResponseDto": { "type": "object", "properties": { "recorded": { "description": "The answer is durably stored against the execution.", "type": "boolean" }, "resumed": { "description": "The execution was woken. A failure to wake returns 409 instead.", "type": "boolean" } }, "required": [ "recorded", "resumed" ] }, "ExecutionSignedUrlResponseDto": { "type": "object", "properties": { "signedUrl": { "description": "Time-limited download URL for the file.", "type": "string" }, "expiresAt": { "description": "When the URL stops working.", "type": "string" } }, "required": [ "signedUrl", "expiresAt" ] }, "WorkflowListResponseDto": { "type": "object", "properties": { "total": { "description": "Total records matching the filter, ignoring paging.", "type": "number" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Owning organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "userId": { "description": "User who created the workflow.", "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "definition": { "description": "The executable definition: steps, initial data and run options.", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "workflowId": { "type": "string" }, "organizationId": { "type": "string" }, "environment": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "stepId": { "type": "string", "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" }, "stepType": { "type": "string", "minLength": 1 }, "input": { "type": "object", "additionalProperties": {} }, "continueOnError": { "type": "boolean" }, "skipCondition": { "type": "object", "additionalProperties": {} }, "retryPolicy": { "type": "object", "properties": { "maxRetries": { "oneOf": [ { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 10, "exclusiveMaximum": false }, { "type": "string" } ] }, "delayMs": { "oneOf": [ { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 30000, "exclusiveMaximum": false }, { "type": "string" } ] }, "backoffMultiplier": { "oneOf": [ { "type": "number", "minimum": 1, "exclusiveMinimum": false, "maximum": 3, "exclusiveMaximum": false }, { "type": "string" } ] }, "maxDelayMs": { "oneOf": [ { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 60000, "exclusiveMaximum": false }, { "type": "string" } ] }, "mode": { "type": "string", "enum": [ "smart", "aggressive", "rate-limits-only", "custom" ] }, "nonRetryableErrorCodes": { "oneOf": [ { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 64 } }, { "type": "string" } ] }, "retryableErrorCodes": { "oneOf": [ { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 64 } }, { "type": "string" } ] }, "http": { "type": "object", "properties": { "methods": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, "statusCodes": { "oneOf": [ { "type": "array", "items": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] } }, { "type": "string" } ] }, "statusCodesAnyMethod": { "oneOf": [ { "type": "array", "items": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] } }, { "type": "string" } ] } } } }, "required": [ "maxRetries" ] } }, "required": [ "stepId", "stepType" ] } }, "initial": { "type": "object", "additionalProperties": {} }, "testData": { "type": "object", "additionalProperties": {} }, "inputSchema": { "type": "object", "additionalProperties": {} }, "triggerProvidedKeys": { "type": "array", "items": { "type": "string" } }, "packageInstallId": { "type": "string" }, "extensionPointBindings": { "type": "object", "additionalProperties": { "type": "string" } }, "options": { "type": "object", "properties": { "stopOnError": { "type": "boolean", "default": true }, "executionMode": { "type": "string", "enum": [ "sync", "async", "auto" ], "default": "auto" }, "timeoutMilliseconds": { "type": "integer", "minimum": 1000, "exclusiveMinimum": false, "maximum": 1800000, "exclusiveMaximum": false, "default": 300000 }, "workerTier": { "type": "string", "enum": [ "standard", "medium", "heavy", "xl" ], "default": "standard" } } } }, "required": [ "name", "steps" ] }, "isTemplate": { "description": "True when this workflow can be called as a sub-workflow.", "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string" } }, "parameters": { "description": "JSON Schema for the sub-workflow call signature. Generated on save when `isTemplate` is true.", "type": "object", "properties": { "input": { "type": "object", "additionalProperties": {} }, "output": { "type": "object", "additionalProperties": {} } } }, "uiMetadata": { "description": "Builder canvas layout. Ignored at run time.", "type": "object", "properties": { "nodePositions": { "type": "object", "additionalProperties": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ] } } } }, "usedActionTypes": { "description": "Step types the definition uses, derived on save.", "type": "array", "items": { "type": "string" } }, "agentToolMetadata": { "description": "How this workflow behaves when an agent calls it as a tool.", "type": "object", "properties": { "toolName": { "type": "string" }, "requiresApproval": { "type": "boolean" }, "approvalMessage": { "type": "string", "maxLength": 1000 } } }, "packageInstallId": { "description": "The package install that owns this workflow. Absent means you own it: package-managed workflows are replaced on upgrade, so edit the package rather than the workflow.", "type": "string" }, "metadata": { "type": "object", "additionalProperties": {} } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "name", "definition", "isTemplate" ] } } }, "required": [ "total", "data" ] }, "WorkflowTagsResponseDto": { "type": "object", "properties": { "tags": { "description": "Every distinct tag in the organization, with its usage count.", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "count": { "description": "Workflows carrying this tag.", "type": "number" } }, "required": [ "name", "count" ] } }, "untaggedCount": { "description": "Workflows carrying no tags at all.", "type": "number" } }, "required": [ "tags", "untaggedCount" ] }, "BulkDeleteWorkflowsDto": { "type": "object", "properties": { "ids": { "type": "array", "minItems": 1, "items": { "type": "string", "format": "uuid" } } }, "required": [ "ids" ] }, "BulkDeleteResponseDto": { "type": "object", "properties": { "deleted": { "description": "Workflows actually deleted. Lower than the ids you sent when some were already gone or out of your access scope.", "type": "number" } }, "required": [ "deleted" ] }, "BulkUpdateTagsDto": { "type": "object", "properties": { "ids": { "type": "array", "minItems": 1, "items": { "type": "string", "format": "uuid" } }, "tags": { "type": "array", "items": { "type": "string" } }, "mode": { "type": "string", "enum": [ "set", "add", "remove" ] } }, "required": [ "ids", "tags", "mode" ] }, "BulkUpdateTagsResponseDto": { "type": "object", "properties": { "updated": { "description": "Workflows whose tags changed.", "type": "number" } }, "required": [ "updated" ] }, "CreateWorkflowTemplateBodyDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "userId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {} }, "updatedAt": {}, "createdAt": {}, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 12000 }, "definition": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string", "default": "1.0" }, "workflowId": { "type": "string" }, "organizationId": { "type": "string" }, "environment": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "stepId": { "type": "string", "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" }, "stepType": { "type": "string", "minLength": 1 }, "input": { "type": "object", "additionalProperties": {} }, "continueOnError": { "type": "boolean" }, "skipCondition": { "type": "object", "additionalProperties": {} }, "retryPolicy": { "type": "object", "properties": { "maxRetries": { "oneOf": [ { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 10, "exclusiveMaximum": false }, { "type": "string" } ] }, "delayMs": { "oneOf": [ { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 30000, "exclusiveMaximum": false }, { "type": "string" } ] }, "backoffMultiplier": { "oneOf": [ { "type": "number", "minimum": 1, "exclusiveMinimum": false, "maximum": 3, "exclusiveMaximum": false }, { "type": "string" } ] }, "maxDelayMs": { "oneOf": [ { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 60000, "exclusiveMaximum": false }, { "type": "string" } ] }, "mode": { "type": "string", "enum": [ "smart", "aggressive", "rate-limits-only", "custom" ] }, "nonRetryableErrorCodes": { "oneOf": [ { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 64 } }, { "type": "string" } ] }, "retryableErrorCodes": { "oneOf": [ { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 64 } }, { "type": "string" } ] }, "http": { "type": "object", "properties": { "methods": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, "statusCodes": { "oneOf": [ { "type": "array", "items": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] } }, { "type": "string" } ] }, "statusCodesAnyMethod": { "oneOf": [ { "type": "array", "items": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] } }, { "type": "string" } ] } } } }, "required": [ "maxRetries" ] } }, "required": [ "stepId", "stepType" ] } }, "initial": { "type": "object", "additionalProperties": {} }, "testData": { "type": "object", "additionalProperties": {} }, "inputSchema": { "type": "object", "additionalProperties": {} }, "triggerProvidedKeys": { "type": "array", "items": { "type": "string" } }, "packageInstallId": { "type": "string" }, "extensionPointBindings": { "type": "object", "additionalProperties": { "type": "string" } }, "options": { "type": "object", "properties": { "stopOnError": { "type": "boolean", "default": true }, "executionMode": { "type": "string", "enum": [ "sync", "async", "auto" ], "default": "auto" }, "timeoutMilliseconds": { "type": "integer", "minimum": 1000, "exclusiveMinimum": false, "maximum": 1800000, "exclusiveMaximum": false, "default": 300000 }, "workerTier": { "type": "string", "enum": [ "standard", "medium", "heavy", "xl" ], "default": "standard" } } } }, "required": [ "steps" ] }, "parameters": { "type": "object", "properties": { "input": { "type": "object", "additionalProperties": {} }, "output": { "type": "object", "additionalProperties": {} } } }, "isTemplate": { "type": "boolean", "default": false }, "tags": { "type": "array", "items": { "type": "string" } }, "uiMetadata": { "type": "object", "properties": { "nodePositions": { "type": "object", "additionalProperties": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ] } } } }, "packageInstallId": { "type": "string" }, "agentToolMetadata": { "type": "object", "properties": { "toolName": { "type": "string" }, "requiresApproval": { "type": "boolean" }, "approvalMessage": { "type": "string", "maxLength": 1000 } } } }, "required": [ "name", "definition" ] }, "WorkflowSaveResponseDto": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Owning organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "userId": { "description": "User who created the workflow.", "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "definition": { "description": "The executable definition: steps, initial data and run options.", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "workflowId": { "type": "string" }, "organizationId": { "type": "string" }, "environment": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "stepId": { "type": "string", "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" }, "stepType": { "type": "string", "minLength": 1 }, "input": { "type": "object", "additionalProperties": {} }, "continueOnError": { "type": "boolean" }, "skipCondition": { "type": "object", "additionalProperties": {} }, "retryPolicy": { "type": "object", "properties": { "maxRetries": { "oneOf": [ { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 10, "exclusiveMaximum": false }, { "type": "string" } ] }, "delayMs": { "oneOf": [ { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 30000, "exclusiveMaximum": false }, { "type": "string" } ] }, "backoffMultiplier": { "oneOf": [ { "type": "number", "minimum": 1, "exclusiveMinimum": false, "maximum": 3, "exclusiveMaximum": false }, { "type": "string" } ] }, "maxDelayMs": { "oneOf": [ { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 60000, "exclusiveMaximum": false }, { "type": "string" } ] }, "mode": { "type": "string", "enum": [ "smart", "aggressive", "rate-limits-only", "custom" ] }, "nonRetryableErrorCodes": { "oneOf": [ { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 64 } }, { "type": "string" } ] }, "retryableErrorCodes": { "oneOf": [ { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 64 } }, { "type": "string" } ] }, "http": { "type": "object", "properties": { "methods": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, "statusCodes": { "oneOf": [ { "type": "array", "items": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] } }, { "type": "string" } ] }, "statusCodesAnyMethod": { "oneOf": [ { "type": "array", "items": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] } }, { "type": "string" } ] } } } }, "required": [ "maxRetries" ] } }, "required": [ "stepId", "stepType" ] } }, "initial": { "type": "object", "additionalProperties": {} }, "testData": { "type": "object", "additionalProperties": {} }, "inputSchema": { "type": "object", "additionalProperties": {} }, "triggerProvidedKeys": { "type": "array", "items": { "type": "string" } }, "packageInstallId": { "type": "string" }, "extensionPointBindings": { "type": "object", "additionalProperties": { "type": "string" } }, "options": { "type": "object", "properties": { "stopOnError": { "type": "boolean", "default": true }, "executionMode": { "type": "string", "enum": [ "sync", "async", "auto" ], "default": "auto" }, "timeoutMilliseconds": { "type": "integer", "minimum": 1000, "exclusiveMinimum": false, "maximum": 1800000, "exclusiveMaximum": false, "default": 300000 }, "workerTier": { "type": "string", "enum": [ "standard", "medium", "heavy", "xl" ], "default": "standard" } } } }, "required": [ "name", "steps" ] }, "isTemplate": { "description": "True when this workflow can be called as a sub-workflow.", "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string" } }, "parameters": { "description": "JSON Schema for the sub-workflow call signature. Generated on save when `isTemplate` is true.", "type": "object", "properties": { "input": { "type": "object", "additionalProperties": {} }, "output": { "type": "object", "additionalProperties": {} } } }, "uiMetadata": { "description": "Builder canvas layout. Ignored at run time.", "type": "object", "properties": { "nodePositions": { "type": "object", "additionalProperties": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ] } } } }, "usedActionTypes": { "description": "Step types the definition uses, derived on save.", "type": "array", "items": { "type": "string" } }, "agentToolMetadata": { "description": "How this workflow behaves when an agent calls it as a tool.", "type": "object", "properties": { "toolName": { "type": "string" }, "requiresApproval": { "type": "boolean" }, "approvalMessage": { "type": "string", "maxLength": 1000 } } }, "packageInstallId": { "description": "The package install that owns this workflow. Absent means you own it: package-managed workflows are replaced on upgrade, so edit the package rather than the workflow.", "type": "string" }, "metadata": { "type": "object", "additionalProperties": {} }, "validationWarnings": { "description": "Advisory only. Empty when the definition is clean.", "type": "array", "items": { "type": "object", "properties": { "ruleId": { "type": "string" }, "severity": { "type": "string", "enum": [ "error", "warning" ] }, "message": { "type": "string" }, "stepId": { "type": "string" }, "docUrl": { "type": "string" } }, "required": [ "ruleId", "severity", "message" ] } } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "name", "definition", "isTemplate", "validationWarnings" ] }, "WorkflowResponseDto": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Owning organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "userId": { "description": "User who created the workflow.", "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "definition": { "description": "The executable definition: steps, initial data and run options.", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "workflowId": { "type": "string" }, "organizationId": { "type": "string" }, "environment": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "stepId": { "type": "string", "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" }, "stepType": { "type": "string", "minLength": 1 }, "input": { "type": "object", "additionalProperties": {} }, "continueOnError": { "type": "boolean" }, "skipCondition": { "type": "object", "additionalProperties": {} }, "retryPolicy": { "type": "object", "properties": { "maxRetries": { "oneOf": [ { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 10, "exclusiveMaximum": false }, { "type": "string" } ] }, "delayMs": { "oneOf": [ { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 30000, "exclusiveMaximum": false }, { "type": "string" } ] }, "backoffMultiplier": { "oneOf": [ { "type": "number", "minimum": 1, "exclusiveMinimum": false, "maximum": 3, "exclusiveMaximum": false }, { "type": "string" } ] }, "maxDelayMs": { "oneOf": [ { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 60000, "exclusiveMaximum": false }, { "type": "string" } ] }, "mode": { "type": "string", "enum": [ "smart", "aggressive", "rate-limits-only", "custom" ] }, "nonRetryableErrorCodes": { "oneOf": [ { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 64 } }, { "type": "string" } ] }, "retryableErrorCodes": { "oneOf": [ { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 64 } }, { "type": "string" } ] }, "http": { "type": "object", "properties": { "methods": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, "statusCodes": { "oneOf": [ { "type": "array", "items": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] } }, { "type": "string" } ] }, "statusCodesAnyMethod": { "oneOf": [ { "type": "array", "items": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] } }, { "type": "string" } ] } } } }, "required": [ "maxRetries" ] } }, "required": [ "stepId", "stepType" ] } }, "initial": { "type": "object", "additionalProperties": {} }, "testData": { "type": "object", "additionalProperties": {} }, "inputSchema": { "type": "object", "additionalProperties": {} }, "triggerProvidedKeys": { "type": "array", "items": { "type": "string" } }, "packageInstallId": { "type": "string" }, "extensionPointBindings": { "type": "object", "additionalProperties": { "type": "string" } }, "options": { "type": "object", "properties": { "stopOnError": { "type": "boolean", "default": true }, "executionMode": { "type": "string", "enum": [ "sync", "async", "auto" ], "default": "auto" }, "timeoutMilliseconds": { "type": "integer", "minimum": 1000, "exclusiveMinimum": false, "maximum": 1800000, "exclusiveMaximum": false, "default": 300000 }, "workerTier": { "type": "string", "enum": [ "standard", "medium", "heavy", "xl" ], "default": "standard" } } } }, "required": [ "name", "steps" ] }, "isTemplate": { "description": "True when this workflow can be called as a sub-workflow.", "type": "boolean" }, "tags": { "type": "array", "items": { "type": "string" } }, "parameters": { "description": "JSON Schema for the sub-workflow call signature. Generated on save when `isTemplate` is true.", "type": "object", "properties": { "input": { "type": "object", "additionalProperties": {} }, "output": { "type": "object", "additionalProperties": {} } } }, "uiMetadata": { "description": "Builder canvas layout. Ignored at run time.", "type": "object", "properties": { "nodePositions": { "type": "object", "additionalProperties": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ] } } } }, "usedActionTypes": { "description": "Step types the definition uses, derived on save.", "type": "array", "items": { "type": "string" } }, "agentToolMetadata": { "description": "How this workflow behaves when an agent calls it as a tool.", "type": "object", "properties": { "toolName": { "type": "string" }, "requiresApproval": { "type": "boolean" }, "approvalMessage": { "type": "string", "maxLength": 1000 } } }, "packageInstallId": { "description": "The package install that owns this workflow. Absent means you own it: package-managed workflows are replaced on upgrade, so edit the package rather than the workflow.", "type": "string" }, "metadata": { "type": "object", "additionalProperties": {} } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "name", "definition", "isTemplate" ] }, "UpdateWorkflowTemplateBodyDto": { "type": "object", "properties": { "organizationId": { "type": "string", "format": "uuid" }, "userId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {} }, "updatedAt": {}, "createdAt": {}, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 12000 }, "definition": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string", "default": "1.0" }, "workflowId": { "type": "string" }, "organizationId": { "type": "string" }, "environment": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "stepId": { "type": "string", "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" }, "stepType": { "type": "string", "minLength": 1 }, "input": { "type": "object", "additionalProperties": {} }, "continueOnError": { "type": "boolean" }, "skipCondition": { "type": "object", "additionalProperties": {} }, "retryPolicy": { "type": "object", "properties": { "maxRetries": { "oneOf": [ { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 10, "exclusiveMaximum": false }, { "type": "string" } ] }, "delayMs": { "oneOf": [ { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 30000, "exclusiveMaximum": false }, { "type": "string" } ] }, "backoffMultiplier": { "oneOf": [ { "type": "number", "minimum": 1, "exclusiveMinimum": false, "maximum": 3, "exclusiveMaximum": false }, { "type": "string" } ] }, "maxDelayMs": { "oneOf": [ { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 60000, "exclusiveMaximum": false }, { "type": "string" } ] }, "mode": { "type": "string", "enum": [ "smart", "aggressive", "rate-limits-only", "custom" ] }, "nonRetryableErrorCodes": { "oneOf": [ { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 64 } }, { "type": "string" } ] }, "retryableErrorCodes": { "oneOf": [ { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 64 } }, { "type": "string" } ] }, "http": { "type": "object", "properties": { "methods": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, "statusCodes": { "oneOf": [ { "type": "array", "items": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] } }, { "type": "string" } ] }, "statusCodesAnyMethod": { "oneOf": [ { "type": "array", "items": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] } }, { "type": "string" } ] } } } }, "required": [ "maxRetries" ] } }, "required": [ "stepId", "stepType" ] } }, "initial": { "type": "object", "additionalProperties": {} }, "testData": { "type": "object", "additionalProperties": {} }, "inputSchema": { "type": "object", "additionalProperties": {} }, "triggerProvidedKeys": { "type": "array", "items": { "type": "string" } }, "packageInstallId": { "type": "string" }, "extensionPointBindings": { "type": "object", "additionalProperties": { "type": "string" } }, "options": { "type": "object", "properties": { "stopOnError": { "type": "boolean", "default": true }, "executionMode": { "type": "string", "enum": [ "sync", "async", "auto" ], "default": "auto" }, "timeoutMilliseconds": { "type": "integer", "minimum": 1000, "exclusiveMinimum": false, "maximum": 1800000, "exclusiveMaximum": false, "default": 300000 }, "workerTier": { "type": "string", "enum": [ "standard", "medium", "heavy", "xl" ], "default": "standard" } } } }, "required": [ "steps" ] }, "parameters": { "type": "object", "properties": { "input": { "type": "object", "additionalProperties": {} }, "output": { "type": "object", "additionalProperties": {} } } }, "isTemplate": { "type": "boolean", "default": false }, "tags": { "type": "array", "items": { "type": "string" } }, "uiMetadata": { "type": "object", "properties": { "nodePositions": { "type": "object", "additionalProperties": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ] } } } }, "packageInstallId": { "type": "string" }, "agentToolMetadata": { "type": "object", "properties": { "toolName": { "type": "string" }, "requiresApproval": { "type": "boolean" }, "approvalMessage": { "type": "string", "maxLength": 1000 } } } } }, "WorkflowRunResponseDto": { "type": "object", "properties": { "status": { "description": "Present only when the run was queued for background execution.", "type": "string", "enum": [ "queued" ] }, "executionId": { "description": "Queued runs only. Use it to poll or download the trace.", "type": "string" }, "output": { "description": "Sync runs only. Step output keyed by `stepId`, filtered by the `show`/`hide` query parameters. Empty unless `show` is set.", "type": "object", "additionalProperties": {} }, "success": { "description": "Sync runs only. False when any step failed.", "type": "boolean" }, "metadata": { "description": "Sync runs only. Carries the execution id for a completed run.", "type": "object", "properties": { "executionId": { "type": "string" }, "workflowName": { "type": "string" }, "workflowId": { "type": "string" }, "organizationId": { "type": "string" }, "environment": { "type": "string" }, "startedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "completedSteps": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "stepName": { "type": "string" }, "message": { "type": "string" }, "stack": { "type": "string" }, "timestamp": { "description": "ISO 8601 timestamp.", "type": "string" } }, "required": [ "stepName", "message", "timestamp" ] } }, "inputSchema": { "type": "object", "additionalProperties": {} }, "triggerProvidedKeys": { "type": "array", "items": { "type": "string" } } }, "required": [ "executionId", "startedAt", "completedSteps", "warnings", "errors" ] }, "error": { "description": "Sync runs only. Sanitized engine-level failure (`message`, `name`, truncated `stack`), or null. Per-step failures are in `metadata.errors`.", "nullable": true }, "metrics": { "description": "Sync runs only.", "type": "object", "properties": { "totalDurationMilliseconds": { "type": "number" }, "totalSteps": { "type": "number" }, "stepsExecuted": { "type": "number" }, "stepsFailed": { "type": "number" }, "stepsSkipped": { "type": "number" }, "contextMemoryBytes": { "type": "number" }, "stepsWithOperationalErrors": { "type": "number" } }, "required": [ "totalDurationMilliseconds", "totalSteps", "stepsExecuted", "stepsFailed", "stepsSkipped" ] } } }, "PublishedWorkflowDefinitionDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "workflowId": { "type": "string" }, "organizationId": { "type": "string" }, "environment": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "stepId": { "type": "string", "minLength": 1, "pattern": "^[a-zA-Z0-9_-]+$" }, "stepType": { "type": "string", "minLength": 1 }, "input": { "type": "object", "additionalProperties": {} }, "continueOnError": { "type": "boolean" }, "skipCondition": { "type": "object", "additionalProperties": {} }, "retryPolicy": { "type": "object", "properties": { "maxRetries": { "oneOf": [ { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 10, "exclusiveMaximum": false }, { "type": "string" } ] }, "delayMs": { "oneOf": [ { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 30000, "exclusiveMaximum": false }, { "type": "string" } ] }, "backoffMultiplier": { "oneOf": [ { "type": "number", "minimum": 1, "exclusiveMinimum": false, "maximum": 3, "exclusiveMaximum": false }, { "type": "string" } ] }, "maxDelayMs": { "oneOf": [ { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 60000, "exclusiveMaximum": false }, { "type": "string" } ] }, "mode": { "type": "string", "enum": [ "smart", "aggressive", "rate-limits-only", "custom" ] }, "nonRetryableErrorCodes": { "oneOf": [ { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 64 } }, { "type": "string" } ] }, "retryableErrorCodes": { "oneOf": [ { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 64 } }, { "type": "string" } ] }, "http": { "type": "object", "properties": { "methods": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, "statusCodes": { "oneOf": [ { "type": "array", "items": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] } }, { "type": "string" } ] }, "statusCodesAnyMethod": { "oneOf": [ { "type": "array", "items": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] } }, { "type": "string" } ] } } } }, "required": [ "maxRetries" ] } }, "required": [ "stepId", "stepType" ] } }, "initial": { "type": "object", "additionalProperties": {} }, "testData": { "type": "object", "additionalProperties": {} }, "inputSchema": { "type": "object", "additionalProperties": {} }, "triggerProvidedKeys": { "type": "array", "items": { "type": "string" } }, "packageInstallId": { "type": "string" }, "extensionPointBindings": { "type": "object", "additionalProperties": { "type": "string" } }, "options": { "type": "object", "properties": { "stopOnError": { "type": "boolean", "default": true }, "executionMode": { "type": "string", "enum": [ "sync", "async", "auto" ], "default": "auto" }, "timeoutMilliseconds": { "type": "integer", "minimum": 1000, "exclusiveMinimum": false, "maximum": 1800000, "exclusiveMaximum": false, "default": 300000 }, "workerTier": { "type": "string", "enum": [ "standard", "medium", "heavy", "xl" ], "default": "standard" } } } }, "required": [ "name", "steps" ] }, "WorkflowValidationResponseDto": { "type": "object", "properties": { "ok": { "description": "True when there are no error-severity issues.", "type": "boolean" }, "errors": { "description": "Block the workflow from being saved.", "type": "array", "items": { "type": "object", "properties": { "ruleId": { "description": "Stable rule identifier, e.g. `reference-resolution`.", "type": "string" }, "severity": { "type": "string", "enum": [ "error", "warning" ] }, "message": { "description": "Explains both the problem and the fix.", "type": "string" }, "stepId": { "description": "Step the issue is anchored to.", "type": "string" }, "docUrl": { "type": "string" } }, "required": [ "ruleId", "severity", "message" ] } }, "warnings": { "description": "Advisory only. A workflow with warnings still saves and runs.", "type": "array", "items": { "type": "object", "properties": { "ruleId": { "description": "Stable rule identifier, e.g. `reference-resolution`.", "type": "string" }, "severity": { "type": "string", "enum": [ "error", "warning" ] }, "message": { "description": "Explains both the problem and the fix.", "type": "string" }, "stepId": { "description": "Step the issue is anchored to.", "type": "string" }, "docUrl": { "type": "string" } }, "required": [ "ruleId", "severity", "message" ] } } }, "required": [ "ok", "errors", "warnings" ] }, "StepCatalogResponseDto": { "type": "object", "properties": { "total": { "description": "Number of steps in `steps`, after filtering.", "type": "number" }, "filters": { "description": "The `fields`/`types` query parameters, echoed back.", "type": "object", "properties": { "fields": { "type": "string" }, "types": { "type": "string" } } }, "steps": { "type": "array", "items": { "type": "object", "properties": { "stepType": { "description": "Catalog id, e.g. `core.http`.", "type": "string" }, "description": { "type": "string" }, "usageHint": { "description": "When to reach for this step over a similar one.", "type": "string" }, "inputSchema": { "description": "JSON Schema for the step's `input` block.", "type": "object", "additionalProperties": {} }, "outputSchema": { "type": "object", "additionalProperties": {} }, "exampleInput": { "description": "Omitted from the list response unless requested via `?fields=...,exampleInput`; always present on the single-step response. Generating examples for the whole catalog is expensive.", "type": "object", "additionalProperties": {} }, "ui": { "description": "Builder rendering hints: icon, color, category, keywords.", "type": "object", "additionalProperties": {} } } } } }, "required": [ "total", "filters", "steps" ] }, "StepInfoResponseDto": { "type": "object", "properties": { "stepType": { "description": "Catalog id, e.g. `core.http`.", "type": "string" }, "description": { "type": "string" }, "usageHint": { "description": "When to reach for this step over a similar one.", "type": "string" }, "inputSchema": { "description": "JSON Schema for the step's `input` block.", "type": "object", "additionalProperties": {} }, "outputSchema": { "type": "object", "additionalProperties": {} }, "exampleInput": { "description": "Omitted from the list response unless requested via `?fields=...,exampleInput`; always present on the single-step response. Generating examples for the whole catalog is expensive.", "type": "object", "additionalProperties": {} }, "ui": { "description": "Builder rendering hints: icon, color, category, keywords.", "type": "object", "additionalProperties": {} } } }, "WorkflowTriggerListResponseDto": { "type": "object", "properties": { "total": { "description": "Total records matching the filter, ignoring paging.", "type": "number" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Owning organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "workflowId": { "description": "Workflow this trigger starts.", "type": "string" }, "packageInstallId": { "description": "Package install that owns this trigger. Absent means the trigger is customer-owned rather than managed by an installed package.", "type": "string" }, "type": { "description": "What starts the workflow.", "type": "string", "enum": [ "webhook", "schedule", "manual", "event", "form" ] }, "name": { "description": "URL-safe name, unique within the organization. Webhook and form triggers need one before they get a named public URL.", "type": "string" }, "orgSuid": { "description": "Owning organization's short id, denormalized to build URLs.", "type": "string" }, "enabled": { "description": "Disabled triggers stay configured but never fire.", "type": "boolean" }, "config": { "description": "Type-specific configuration. Only the block matching `type` is populated.", "type": "object", "properties": { "webhook": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ], "default": "POST" }, "authType": { "type": "string", "enum": [ "none", "token", "qf-identity" ], "default": "token" }, "secret": { "type": "string" }, "appId": { "type": "string", "minLength": 1, "nullable": true }, "timeout": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "default": 30000 }, "exposeErrors": { "type": "boolean", "default": true }, "includeRawBody": { "type": "boolean", "default": false } } }, "schedule": { "type": "object", "properties": { "cron": { "type": "string" }, "timezone": { "type": "string", "default": "UTC" }, "environment": { "type": "string", "nullable": true }, "qstashScheduleId": { "type": "string" }, "nextRun": { "description": "ISO 8601 timestamp of the next scheduled run.", "type": "string" }, "initialData": { "type": "object", "additionalProperties": {} } }, "required": [ "cron" ] }, "event": { "oneOf": [ { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "five9", "five9-ess" ] }, "connectionName": { "type": "string", "minLength": 1, "maxLength": 100 }, "eventTypes": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } }, "filter": { "type": "object", "additionalProperties": {} }, "providerConfig": { "type": "object", "additionalProperties": {} } }, "required": [ "provider", "connectionName", "eventTypes" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "custom-poll" ] }, "connectionName": { "type": "string", "minLength": 1, "maxLength": 100 }, "url": { "type": "string", "minLength": 1 }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH" ], "default": "GET" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "body": { "type": "object", "additionalProperties": {} }, "pollIntervalMs": { "type": "number", "minimum": 5000, "exclusiveMinimum": false, "maximum": 300000, "exclusiveMaximum": false, "default": 30000 }, "eventPath": { "type": "string" }, "eventTypePath": { "type": "string" }, "eventType": { "type": "string", "minLength": 1 }, "filter": { "type": "object", "additionalProperties": {} }, "dedupeField": { "type": "string" } }, "required": [ "provider", "url" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "custom-websocket" ] }, "connectionName": { "type": "string", "minLength": 1, "maxLength": 100 }, "url": { "type": "string", "minLength": 1 }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "connectMessage": { "type": "object", "additionalProperties": {} }, "eventTypePath": { "type": "string" }, "eventType": { "type": "string", "minLength": 1 }, "filter": { "type": "object", "additionalProperties": {} }, "heartbeatIntervalMs": { "type": "number", "minimum": 0, "exclusiveMinimum": false, "maximum": 300000, "exclusiveMaximum": false, "default": 30000 }, "heartbeatMessage": { "type": "object", "additionalProperties": {} } }, "required": [ "provider", "url" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "custom-webhook" ] }, "connectionName": { "type": "string", "minLength": 1, "maxLength": 100 }, "signatureHeader": { "type": "string" }, "signatureAlgorithm": { "type": "string", "enum": [ "hmac-sha256", "hmac-sha1", "hmac-sha512" ] }, "eventTypePath": { "type": "string" }, "eventType": { "type": "string", "minLength": 1 }, "filter": { "type": "object", "additionalProperties": {} } }, "required": [ "provider" ] } ] }, "form": { "type": "object", "properties": { "schema": { "type": "object", "additionalProperties": {} }, "meta": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "submitButtonText": { "type": "string" }, "successMessage": { "type": "string" }, "errorMessage": { "type": "string" }, "logo": { "type": "string" }, "pageTitle": { "type": "string" }, "favicon": { "type": "string" }, "layout": { "type": "string", "enum": [ "narrow", "standard", "wide", "full" ] }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "icon": { "type": "string" }, "description": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "label", "fields" ] } } } }, "allowBulk": { "type": "boolean", "default": false }, "auth": { "oneOf": [ { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "none" ] } }, "required": [ "provider" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "credentials" ] }, "credentialIds": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "hint": { "type": "string" } }, "required": [ "provider", "credentialIds" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "qf-identity" ] }, "appId": { "type": "string", "minLength": 1 } }, "required": [ "provider" ] } ], "default": { "provider": "none" } }, "rateLimit": { "type": "object", "properties": { "maxPerMinute": { "type": "number", "default": 60 } } }, "redirectUrl": { "type": "string", "format": "uri" }, "exposeErrors": { "type": "boolean", "default": true }, "prefill": { "type": "object", "properties": { "workflowId": { "type": "string", "format": "uuid" }, "timeoutMs": { "type": "integer", "minimum": 1000, "exclusiveMinimum": false, "maximum": 60000, "exclusiveMaximum": false, "default": 10000 } }, "required": [ "workflowId" ] }, "confirmation": { "type": "object", "properties": { "workflowId": { "type": "string", "format": "uuid" }, "timeoutMs": { "type": "integer", "minimum": 1000, "exclusiveMinimum": false, "maximum": 60000, "exclusiveMaximum": false, "default": 10000 } }, "required": [ "workflowId" ] }, "mode": { "type": "string", "enum": [ "standard", "chat" ], "default": "standard" }, "chat": { "type": "object", "properties": { "historyDepth": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 200, "exclusiveMaximum": false, "default": 20 }, "eventRetentionDays": { "type": "integer", "minimum": 7, "exclusiveMinimum": false, "maximum": 30, "exclusiveMaximum": false, "default": 14 }, "sessionTimeoutSeconds": { "type": "integer", "minimum": 30, "exclusiveMinimum": false, "maximum": 86400, "exclusiveMaximum": false, "default": 600 }, "hideHistory": { "type": "boolean", "default": false }, "hideToolCards": { "type": "boolean", "default": false }, "disclaimer": { "type": "string", "maxLength": 500 }, "welcomeMessage": { "type": "string", "maxLength": 2000 }, "endedWorkflowId": { "type": "string", "format": "uuid" }, "endedWorkflowTimeoutMs": { "type": "integer", "minimum": 1000, "exclusiveMinimum": false, "maximum": 60000, "exclusiveMaximum": false, "default": 30000 }, "memory": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false }, "maxRecallSessions": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 50, "exclusiveMaximum": false, "default": 10 }, "retentionDays": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 3650, "exclusiveMaximum": false, "default": 90 } } } } } } } } }, "lastTriggeredAt": { "description": "ISO 8601 timestamp of the last time this trigger fired.", "type": "string", "nullable": true }, "lastTriggerExecutionId": { "description": "Execution started by the most recent firing.", "type": "string" }, "triggerCount": { "description": "Lifetime number of firings.", "type": "number" }, "userId": { "description": "User who created the trigger.", "type": "string" }, "metadata": { "description": "Caller-owned metadata.", "type": "object", "additionalProperties": {} }, "webhookUrl": { "description": "Public URL to POST to. Webhook triggers only.", "type": "string" }, "formUrl": { "description": "Hosted form (or chat) URL. Form triggers only, and only once the trigger has a name.", "type": "string" }, "eventWebhookUrl": { "description": "Inbound URL the event provider posts to. Event triggers on webhook-delivered providers only.", "type": "string" }, "eventWebhookSecret": { "description": "Shared secret the event provider signs its deliveries with.", "type": "string" }, "eventAssignmentId": { "description": "Event-listener assignment backing this trigger.", "type": "string" }, "eventAuthRequired": { "description": "When false, anyone holding the event webhook URL can start the workflow without presenting the secret. Defaults to true.", "type": "boolean" } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "workflowId", "type", "enabled", "config", "triggerCount" ] } } }, "required": [ "total", "data" ] }, "WorkflowTriggerResponseDto": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Owning organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "workflowId": { "description": "Workflow this trigger starts.", "type": "string" }, "packageInstallId": { "description": "Package install that owns this trigger. Absent means the trigger is customer-owned rather than managed by an installed package.", "type": "string" }, "type": { "description": "What starts the workflow.", "type": "string", "enum": [ "webhook", "schedule", "manual", "event", "form" ] }, "name": { "description": "URL-safe name, unique within the organization. Webhook and form triggers need one before they get a named public URL.", "type": "string" }, "orgSuid": { "description": "Owning organization's short id, denormalized to build URLs.", "type": "string" }, "enabled": { "description": "Disabled triggers stay configured but never fire.", "type": "boolean" }, "config": { "description": "Type-specific configuration. Only the block matching `type` is populated.", "type": "object", "properties": { "webhook": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ], "default": "POST" }, "authType": { "type": "string", "enum": [ "none", "token", "qf-identity" ], "default": "token" }, "secret": { "type": "string" }, "appId": { "type": "string", "minLength": 1, "nullable": true }, "timeout": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "default": 30000 }, "exposeErrors": { "type": "boolean", "default": true }, "includeRawBody": { "type": "boolean", "default": false } } }, "schedule": { "type": "object", "properties": { "cron": { "type": "string" }, "timezone": { "type": "string", "default": "UTC" }, "environment": { "type": "string", "nullable": true }, "qstashScheduleId": { "type": "string" }, "nextRun": { "description": "ISO 8601 timestamp of the next scheduled run.", "type": "string" }, "initialData": { "type": "object", "additionalProperties": {} } }, "required": [ "cron" ] }, "event": { "oneOf": [ { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "five9", "five9-ess" ] }, "connectionName": { "type": "string", "minLength": 1, "maxLength": 100 }, "eventTypes": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } }, "filter": { "type": "object", "additionalProperties": {} }, "providerConfig": { "type": "object", "additionalProperties": {} } }, "required": [ "provider", "connectionName", "eventTypes" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "custom-poll" ] }, "connectionName": { "type": "string", "minLength": 1, "maxLength": 100 }, "url": { "type": "string", "minLength": 1 }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH" ], "default": "GET" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "body": { "type": "object", "additionalProperties": {} }, "pollIntervalMs": { "type": "number", "minimum": 5000, "exclusiveMinimum": false, "maximum": 300000, "exclusiveMaximum": false, "default": 30000 }, "eventPath": { "type": "string" }, "eventTypePath": { "type": "string" }, "eventType": { "type": "string", "minLength": 1 }, "filter": { "type": "object", "additionalProperties": {} }, "dedupeField": { "type": "string" } }, "required": [ "provider", "url" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "custom-websocket" ] }, "connectionName": { "type": "string", "minLength": 1, "maxLength": 100 }, "url": { "type": "string", "minLength": 1 }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "connectMessage": { "type": "object", "additionalProperties": {} }, "eventTypePath": { "type": "string" }, "eventType": { "type": "string", "minLength": 1 }, "filter": { "type": "object", "additionalProperties": {} }, "heartbeatIntervalMs": { "type": "number", "minimum": 0, "exclusiveMinimum": false, "maximum": 300000, "exclusiveMaximum": false, "default": 30000 }, "heartbeatMessage": { "type": "object", "additionalProperties": {} } }, "required": [ "provider", "url" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "custom-webhook" ] }, "connectionName": { "type": "string", "minLength": 1, "maxLength": 100 }, "signatureHeader": { "type": "string" }, "signatureAlgorithm": { "type": "string", "enum": [ "hmac-sha256", "hmac-sha1", "hmac-sha512" ] }, "eventTypePath": { "type": "string" }, "eventType": { "type": "string", "minLength": 1 }, "filter": { "type": "object", "additionalProperties": {} } }, "required": [ "provider" ] } ] }, "form": { "type": "object", "properties": { "schema": { "type": "object", "additionalProperties": {} }, "meta": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "submitButtonText": { "type": "string" }, "successMessage": { "type": "string" }, "errorMessage": { "type": "string" }, "logo": { "type": "string" }, "pageTitle": { "type": "string" }, "favicon": { "type": "string" }, "layout": { "type": "string", "enum": [ "narrow", "standard", "wide", "full" ] }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "icon": { "type": "string" }, "description": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "label", "fields" ] } } } }, "allowBulk": { "type": "boolean", "default": false }, "auth": { "oneOf": [ { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "none" ] } }, "required": [ "provider" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "credentials" ] }, "credentialIds": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "hint": { "type": "string" } }, "required": [ "provider", "credentialIds" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "qf-identity" ] }, "appId": { "type": "string", "minLength": 1 } }, "required": [ "provider" ] } ], "default": { "provider": "none" } }, "rateLimit": { "type": "object", "properties": { "maxPerMinute": { "type": "number", "default": 60 } } }, "redirectUrl": { "type": "string", "format": "uri" }, "exposeErrors": { "type": "boolean", "default": true }, "prefill": { "type": "object", "properties": { "workflowId": { "type": "string", "format": "uuid" }, "timeoutMs": { "type": "integer", "minimum": 1000, "exclusiveMinimum": false, "maximum": 60000, "exclusiveMaximum": false, "default": 10000 } }, "required": [ "workflowId" ] }, "confirmation": { "type": "object", "properties": { "workflowId": { "type": "string", "format": "uuid" }, "timeoutMs": { "type": "integer", "minimum": 1000, "exclusiveMinimum": false, "maximum": 60000, "exclusiveMaximum": false, "default": 10000 } }, "required": [ "workflowId" ] }, "mode": { "type": "string", "enum": [ "standard", "chat" ], "default": "standard" }, "chat": { "type": "object", "properties": { "historyDepth": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 200, "exclusiveMaximum": false, "default": 20 }, "eventRetentionDays": { "type": "integer", "minimum": 7, "exclusiveMinimum": false, "maximum": 30, "exclusiveMaximum": false, "default": 14 }, "sessionTimeoutSeconds": { "type": "integer", "minimum": 30, "exclusiveMinimum": false, "maximum": 86400, "exclusiveMaximum": false, "default": 600 }, "hideHistory": { "type": "boolean", "default": false }, "hideToolCards": { "type": "boolean", "default": false }, "disclaimer": { "type": "string", "maxLength": 500 }, "welcomeMessage": { "type": "string", "maxLength": 2000 }, "endedWorkflowId": { "type": "string", "format": "uuid" }, "endedWorkflowTimeoutMs": { "type": "integer", "minimum": 1000, "exclusiveMinimum": false, "maximum": 60000, "exclusiveMaximum": false, "default": 30000 }, "memory": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false }, "maxRecallSessions": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 50, "exclusiveMaximum": false, "default": 10 }, "retentionDays": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 3650, "exclusiveMaximum": false, "default": 90 } } } } } } } } }, "lastTriggeredAt": { "description": "ISO 8601 timestamp of the last time this trigger fired.", "type": "string", "nullable": true }, "lastTriggerExecutionId": { "description": "Execution started by the most recent firing.", "type": "string" }, "triggerCount": { "description": "Lifetime number of firings.", "type": "number" }, "userId": { "description": "User who created the trigger.", "type": "string" }, "metadata": { "description": "Caller-owned metadata.", "type": "object", "additionalProperties": {} }, "webhookUrl": { "description": "Public URL to POST to. Webhook triggers only.", "type": "string" }, "formUrl": { "description": "Hosted form (or chat) URL. Form triggers only, and only once the trigger has a name.", "type": "string" }, "eventWebhookUrl": { "description": "Inbound URL the event provider posts to. Event triggers on webhook-delivered providers only.", "type": "string" }, "eventWebhookSecret": { "description": "Shared secret the event provider signs its deliveries with.", "type": "string" }, "eventAssignmentId": { "description": "Event-listener assignment backing this trigger.", "type": "string" }, "eventAuthRequired": { "description": "When false, anyone holding the event webhook URL can start the workflow without presenting the secret. Defaults to true.", "type": "boolean" } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "workflowId", "type", "enabled", "config", "triggerCount" ] }, "TriggerErrorResponseDto": { "type": "object", "properties": { "statusCode": { "type": "number" }, "message": { "type": "string" }, "error": { "description": "Additional detail, when available." } }, "required": [ "statusCode", "message" ] }, "UpdateTriggerDto": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "config": { "type": "object", "properties": { "webhook": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ], "default": "POST" }, "authType": { "type": "string", "enum": [ "none", "token", "qf-identity" ], "default": "token" }, "secret": { "type": "string" }, "appId": { "type": "string", "minLength": 1, "nullable": true }, "timeout": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "default": 30000 }, "exposeErrors": { "type": "boolean", "default": true }, "includeRawBody": { "type": "boolean", "default": false } } }, "schedule": { "type": "object", "properties": { "cron": { "type": "string" }, "timezone": { "type": "string", "default": "UTC" }, "environment": { "type": "string", "nullable": true }, "qstashScheduleId": { "type": "string" }, "nextRun": {}, "initialData": { "type": "object", "additionalProperties": {} } }, "required": [ "cron" ] }, "event": { "oneOf": [ { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "five9", "five9-ess" ] }, "connectionName": { "type": "string", "minLength": 1, "maxLength": 100 }, "eventTypes": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } }, "filter": { "type": "object", "additionalProperties": {} }, "providerConfig": { "type": "object", "additionalProperties": {} } }, "required": [ "provider", "connectionName", "eventTypes" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "custom-poll" ] }, "connectionName": { "type": "string", "minLength": 1, "maxLength": 100 }, "url": { "type": "string", "minLength": 1 }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH" ], "default": "GET" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "body": { "type": "object", "additionalProperties": {} }, "pollIntervalMs": { "type": "number", "minimum": 5000, "exclusiveMinimum": false, "maximum": 300000, "exclusiveMaximum": false, "default": 30000 }, "eventPath": { "type": "string" }, "eventTypePath": { "type": "string" }, "eventType": { "type": "string", "minLength": 1 }, "filter": { "type": "object", "additionalProperties": {} }, "dedupeField": { "type": "string" } }, "required": [ "provider", "url" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "custom-websocket" ] }, "connectionName": { "type": "string", "minLength": 1, "maxLength": 100 }, "url": { "type": "string", "minLength": 1 }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "connectMessage": { "type": "object", "additionalProperties": {} }, "eventTypePath": { "type": "string" }, "eventType": { "type": "string", "minLength": 1 }, "filter": { "type": "object", "additionalProperties": {} }, "heartbeatIntervalMs": { "type": "number", "minimum": 0, "exclusiveMinimum": false, "maximum": 300000, "exclusiveMaximum": false, "default": 30000 }, "heartbeatMessage": { "type": "object", "additionalProperties": {} } }, "required": [ "provider", "url" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "custom-webhook" ] }, "connectionName": { "type": "string", "minLength": 1, "maxLength": 100 }, "signatureHeader": { "type": "string" }, "signatureAlgorithm": { "type": "string", "enum": [ "hmac-sha256", "hmac-sha1", "hmac-sha512" ] }, "eventTypePath": { "type": "string" }, "eventType": { "type": "string", "minLength": 1 }, "filter": { "type": "object", "additionalProperties": {} } }, "required": [ "provider" ] } ] }, "form": { "type": "object", "properties": { "schema": { "type": "object", "additionalProperties": {} }, "meta": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "submitButtonText": { "type": "string" }, "successMessage": { "type": "string" }, "errorMessage": { "type": "string" }, "logo": { "type": "string" }, "pageTitle": { "type": "string" }, "favicon": { "type": "string" }, "layout": { "type": "string", "enum": [ "narrow", "standard", "wide", "full" ] }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "icon": { "type": "string" }, "description": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "label", "fields" ] } } } }, "allowBulk": { "type": "boolean", "default": false }, "auth": { "oneOf": [ { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "none" ] } }, "required": [ "provider" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "credentials" ] }, "credentialIds": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "hint": { "type": "string" } }, "required": [ "provider", "credentialIds" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "qf-identity" ] }, "appId": { "type": "string", "minLength": 1 } }, "required": [ "provider" ] } ], "default": { "provider": "none" } }, "rateLimit": { "type": "object", "properties": { "maxPerMinute": { "type": "number", "default": 60 } } }, "redirectUrl": { "type": "string", "format": "uri" }, "exposeErrors": { "type": "boolean", "default": true }, "prefill": { "type": "object", "properties": { "workflowId": { "type": "string", "format": "uuid" }, "timeoutMs": { "type": "integer", "minimum": 1000, "exclusiveMinimum": false, "maximum": 60000, "exclusiveMaximum": false, "default": 10000 } }, "required": [ "workflowId" ] }, "confirmation": { "type": "object", "properties": { "workflowId": { "type": "string", "format": "uuid" }, "timeoutMs": { "type": "integer", "minimum": 1000, "exclusiveMinimum": false, "maximum": 60000, "exclusiveMaximum": false, "default": 10000 } }, "required": [ "workflowId" ] }, "mode": { "type": "string", "enum": [ "standard", "chat" ], "default": "standard" }, "chat": { "type": "object", "properties": { "historyDepth": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 200, "exclusiveMaximum": false, "default": 20 }, "eventRetentionDays": { "type": "integer", "minimum": 7, "exclusiveMinimum": false, "maximum": 30, "exclusiveMaximum": false, "default": 14 }, "sessionTimeoutSeconds": { "type": "integer", "minimum": 30, "exclusiveMinimum": false, "maximum": 86400, "exclusiveMaximum": false, "default": 600 }, "hideHistory": { "type": "boolean", "default": false }, "hideToolCards": { "type": "boolean", "default": false }, "disclaimer": { "type": "string", "maxLength": 500 }, "welcomeMessage": { "type": "string", "maxLength": 2000 }, "endedWorkflowId": { "type": "string", "format": "uuid" }, "endedWorkflowTimeoutMs": { "type": "integer", "minimum": 1000, "exclusiveMinimum": false, "maximum": 60000, "exclusiveMaximum": false, "default": 30000 }, "memory": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false }, "maxRecallSessions": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 50, "exclusiveMaximum": false, "default": 10 }, "retentionDays": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 3650, "exclusiveMaximum": false, "default": 90 } } } } } } } } }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9._~-]+$" } } }, "DeleteTriggerResponseDto": { "type": "object", "properties": { "id": { "description": "Id of the deleted trigger.", "type": "string" }, "message": { "type": "string" } }, "required": [ "id", "message" ] }, "BulkDeleteTriggersDto": { "type": "object", "properties": { "ids": { "type": "array", "minItems": 1, "items": { "type": "string", "format": "uuid" } } }, "required": [ "ids" ] }, "BulkDeleteTriggersResponseDto": { "type": "object", "properties": { "deleted": { "description": "Triggers removed.", "type": "number" }, "failed": { "description": "Triggers that could not be removed.", "type": "number" } }, "required": [ "deleted", "failed" ] }, "BulkUpdateTriggersEnabledDto": { "type": "object", "properties": { "ids": { "type": "array", "minItems": 1, "items": { "type": "string", "format": "uuid" } }, "enabled": { "type": "boolean" } }, "required": [ "ids", "enabled" ] }, "BulkUpdateTriggersEnabledResponseDto": { "type": "object", "properties": { "updated": { "description": "Triggers now in the requested state. Counts triggers that were already in that state.", "type": "number" }, "failed": { "description": "Triggers that could not be changed.", "type": "number" } }, "required": [ "updated", "failed" ] }, "TriggerTypeListResponseDto": { "type": "object", "properties": { "types": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Trigger type id, e.g. `webhook` or `custom-poll`.", "type": "string" }, "type": { "description": "Underlying trigger type stored on the trigger. Several ids share one type: every event provider maps to `event`.", "type": "string" }, "provider": { "description": "Event provider, or null for non-event types.", "type": "string", "nullable": true }, "label": { "type": "string" }, "icon": { "description": "Material icon name.", "type": "string" }, "description": { "type": "string" } }, "required": [ "id", "type", "provider", "label", "icon", "description" ] } } }, "required": [ "types" ] }, "TriggerTypeSchemaResponseDto": { "type": "object", "properties": { "id": { "description": "Trigger type id, e.g. `webhook` or `custom-poll`.", "type": "string" }, "type": { "description": "Underlying trigger type stored on the trigger. Several ids share one type: every event provider maps to `event`.", "type": "string" }, "provider": { "description": "Event provider, or null for non-event types.", "type": "string", "nullable": true }, "label": { "type": "string" }, "icon": { "description": "Material icon name.", "type": "string" }, "description": { "type": "string" }, "schema": { "description": "JSON Schema (draft-07) for this type’s config. Shape varies per trigger type, so it is not modelled further here.", "type": "object", "additionalProperties": {} }, "defaultConfig": { "description": "Config values to start from when creating this trigger type.", "type": "object", "additionalProperties": {} } }, "required": [ "id", "type", "provider", "label", "icon", "description", "schema", "defaultConfig" ] }, "CreateTriggerDto": { "type": "object", "properties": { "organizationId": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "webhook", "schedule", "manual", "event", "form" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9._~-]+$" }, "config": { "type": "object", "properties": { "webhook": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ], "default": "POST" }, "authType": { "type": "string", "enum": [ "none", "token", "qf-identity" ], "default": "token" }, "secret": { "type": "string" }, "appId": { "type": "string", "minLength": 1 }, "timeout": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "default": 30000 }, "exposeErrors": { "type": "boolean", "default": true }, "includeRawBody": { "type": "boolean", "default": false } } }, "schedule": { "type": "object", "properties": { "cron": { "type": "string" }, "timezone": { "type": "string", "default": "UTC" }, "environment": { "type": "string" }, "initialData": { "type": "object", "additionalProperties": {} } }, "required": [ "cron" ] }, "event": { "oneOf": [ { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "five9", "five9-ess" ] }, "connectionName": { "type": "string", "minLength": 1, "maxLength": 100 }, "eventTypes": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } }, "filter": { "type": "object", "additionalProperties": {} }, "providerConfig": { "type": "object", "additionalProperties": {} } }, "required": [ "provider", "connectionName", "eventTypes" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "custom-poll" ] }, "connectionName": { "type": "string", "minLength": 1, "maxLength": 100 }, "url": { "type": "string", "minLength": 1 }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH" ], "default": "GET" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "body": { "type": "object", "additionalProperties": {} }, "pollIntervalMs": { "type": "number", "minimum": 5000, "exclusiveMinimum": false, "maximum": 300000, "exclusiveMaximum": false, "default": 30000 }, "eventPath": { "type": "string" }, "eventTypePath": { "type": "string" }, "eventType": { "type": "string", "minLength": 1 }, "filter": { "type": "object", "additionalProperties": {} }, "dedupeField": { "type": "string" } }, "required": [ "provider", "url" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "custom-websocket" ] }, "connectionName": { "type": "string", "minLength": 1, "maxLength": 100 }, "url": { "type": "string", "minLength": 1 }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "connectMessage": { "type": "object", "additionalProperties": {} }, "eventTypePath": { "type": "string" }, "eventType": { "type": "string", "minLength": 1 }, "filter": { "type": "object", "additionalProperties": {} }, "heartbeatIntervalMs": { "type": "number", "minimum": 0, "exclusiveMinimum": false, "maximum": 300000, "exclusiveMaximum": false, "default": 30000 }, "heartbeatMessage": { "type": "object", "additionalProperties": {} } }, "required": [ "provider", "url" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "custom-webhook" ] }, "connectionName": { "type": "string", "minLength": 1, "maxLength": 100 }, "signatureHeader": { "type": "string" }, "signatureAlgorithm": { "type": "string", "enum": [ "hmac-sha256", "hmac-sha1", "hmac-sha512" ] }, "eventTypePath": { "type": "string" }, "eventType": { "type": "string", "minLength": 1 }, "filter": { "type": "object", "additionalProperties": {} } }, "required": [ "provider" ] } ] }, "form": { "type": "object", "properties": { "schema": { "type": "object", "additionalProperties": {} }, "meta": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "submitButtonText": { "type": "string" }, "successMessage": { "type": "string" }, "errorMessage": { "type": "string" }, "logo": { "type": "string" }, "pageTitle": { "type": "string" }, "favicon": { "type": "string" }, "layout": { "type": "string", "enum": [ "narrow", "standard", "wide", "full" ] }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "icon": { "type": "string" }, "description": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "label", "fields" ] } } } }, "allowBulk": { "type": "boolean", "default": false }, "auth": { "oneOf": [ { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "none" ] } }, "required": [ "provider" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "credentials" ] }, "credentialIds": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "hint": { "type": "string" } }, "required": [ "provider", "credentialIds" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "qf-identity" ] }, "appId": { "type": "string", "minLength": 1 } }, "required": [ "provider" ] } ], "default": { "provider": "none" } }, "rateLimit": { "type": "object", "properties": { "maxPerMinute": { "type": "number", "default": 60 } } }, "redirectUrl": { "type": "string", "format": "uri" }, "exposeErrors": { "type": "boolean", "default": true }, "prefill": { "type": "object", "properties": { "workflowId": { "type": "string", "format": "uuid" }, "timeoutMs": { "type": "integer", "minimum": 1000, "exclusiveMinimum": false, "maximum": 300000, "exclusiveMaximum": false, "default": 10000 } }, "required": [ "workflowId" ] }, "confirmation": { "type": "object", "properties": { "workflowId": { "type": "string", "format": "uuid" }, "timeoutMs": { "type": "integer", "minimum": 1000, "exclusiveMinimum": false, "maximum": 300000, "exclusiveMaximum": false, "default": 10000 } }, "required": [ "workflowId" ] }, "mode": { "type": "string", "enum": [ "standard", "chat" ], "default": "standard" }, "chat": { "type": "object", "properties": { "historyDepth": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 200, "exclusiveMaximum": false, "default": 20 }, "eventRetentionDays": { "type": "integer", "minimum": 7, "exclusiveMinimum": false, "maximum": 30, "exclusiveMaximum": false, "default": 14 }, "sessionTimeoutSeconds": { "type": "integer", "minimum": 30, "exclusiveMinimum": false, "maximum": 86400, "exclusiveMaximum": false, "default": 600 }, "hideHistory": { "type": "boolean", "default": false }, "hideToolCards": { "type": "boolean", "default": false }, "disclaimer": { "type": "string", "maxLength": 500 }, "welcomeMessage": { "type": "string", "maxLength": 2000 }, "endedWorkflowId": { "type": "string", "format": "uuid" }, "endedWorkflowTimeoutMs": { "type": "integer", "minimum": 1000, "exclusiveMinimum": false, "maximum": 60000, "exclusiveMaximum": false, "default": 30000 }, "memory": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false }, "maxRecallSessions": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 50, "exclusiveMaximum": false, "default": 10 }, "retentionDays": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 3650, "exclusiveMaximum": false, "default": 90 } } } } } } } } } }, "required": [ "type", "config" ] }, "RegenerateTriggerSecretResponseDto": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Owning organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "workflowId": { "description": "Workflow this trigger starts.", "type": "string" }, "packageInstallId": { "description": "Package install that owns this trigger. Absent means the trigger is customer-owned rather than managed by an installed package.", "type": "string" }, "type": { "description": "What starts the workflow.", "type": "string", "enum": [ "webhook", "schedule", "manual", "event", "form" ] }, "name": { "description": "URL-safe name, unique within the organization. Webhook and form triggers need one before they get a named public URL.", "type": "string" }, "orgSuid": { "description": "Owning organization's short id, denormalized to build URLs.", "type": "string" }, "enabled": { "description": "Disabled triggers stay configured but never fire.", "type": "boolean" }, "config": { "description": "Type-specific configuration. Only the block matching `type` is populated.", "type": "object", "properties": { "webhook": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1 }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ], "default": "POST" }, "authType": { "type": "string", "enum": [ "none", "token", "qf-identity" ], "default": "token" }, "secret": { "type": "string" }, "appId": { "type": "string", "minLength": 1, "nullable": true }, "timeout": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "default": 30000 }, "exposeErrors": { "type": "boolean", "default": true }, "includeRawBody": { "type": "boolean", "default": false } } }, "schedule": { "type": "object", "properties": { "cron": { "type": "string" }, "timezone": { "type": "string", "default": "UTC" }, "environment": { "type": "string", "nullable": true }, "qstashScheduleId": { "type": "string" }, "nextRun": { "description": "ISO 8601 timestamp of the next scheduled run.", "type": "string" }, "initialData": { "type": "object", "additionalProperties": {} } }, "required": [ "cron" ] }, "event": { "oneOf": [ { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "five9", "five9-ess" ] }, "connectionName": { "type": "string", "minLength": 1, "maxLength": 100 }, "eventTypes": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } }, "filter": { "type": "object", "additionalProperties": {} }, "providerConfig": { "type": "object", "additionalProperties": {} } }, "required": [ "provider", "connectionName", "eventTypes" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "custom-poll" ] }, "connectionName": { "type": "string", "minLength": 1, "maxLength": 100 }, "url": { "type": "string", "minLength": 1 }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH" ], "default": "GET" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "body": { "type": "object", "additionalProperties": {} }, "pollIntervalMs": { "type": "number", "minimum": 5000, "exclusiveMinimum": false, "maximum": 300000, "exclusiveMaximum": false, "default": 30000 }, "eventPath": { "type": "string" }, "eventTypePath": { "type": "string" }, "eventType": { "type": "string", "minLength": 1 }, "filter": { "type": "object", "additionalProperties": {} }, "dedupeField": { "type": "string" } }, "required": [ "provider", "url" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "custom-websocket" ] }, "connectionName": { "type": "string", "minLength": 1, "maxLength": 100 }, "url": { "type": "string", "minLength": 1 }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "connectMessage": { "type": "object", "additionalProperties": {} }, "eventTypePath": { "type": "string" }, "eventType": { "type": "string", "minLength": 1 }, "filter": { "type": "object", "additionalProperties": {} }, "heartbeatIntervalMs": { "type": "number", "minimum": 0, "exclusiveMinimum": false, "maximum": 300000, "exclusiveMaximum": false, "default": 30000 }, "heartbeatMessage": { "type": "object", "additionalProperties": {} } }, "required": [ "provider", "url" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "custom-webhook" ] }, "connectionName": { "type": "string", "minLength": 1, "maxLength": 100 }, "signatureHeader": { "type": "string" }, "signatureAlgorithm": { "type": "string", "enum": [ "hmac-sha256", "hmac-sha1", "hmac-sha512" ] }, "eventTypePath": { "type": "string" }, "eventType": { "type": "string", "minLength": 1 }, "filter": { "type": "object", "additionalProperties": {} } }, "required": [ "provider" ] } ] }, "form": { "type": "object", "properties": { "schema": { "type": "object", "additionalProperties": {} }, "meta": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "submitButtonText": { "type": "string" }, "successMessage": { "type": "string" }, "errorMessage": { "type": "string" }, "logo": { "type": "string" }, "pageTitle": { "type": "string" }, "favicon": { "type": "string" }, "layout": { "type": "string", "enum": [ "narrow", "standard", "wide", "full" ] }, "sections": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "icon": { "type": "string" }, "description": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "label", "fields" ] } } } }, "allowBulk": { "type": "boolean", "default": false }, "auth": { "oneOf": [ { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "none" ] } }, "required": [ "provider" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "credentials" ] }, "credentialIds": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "hint": { "type": "string" } }, "required": [ "provider", "credentialIds" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "qf-identity" ] }, "appId": { "type": "string", "minLength": 1 } }, "required": [ "provider" ] } ], "default": { "provider": "none" } }, "rateLimit": { "type": "object", "properties": { "maxPerMinute": { "type": "number", "default": 60 } } }, "redirectUrl": { "type": "string", "format": "uri" }, "exposeErrors": { "type": "boolean", "default": true }, "prefill": { "type": "object", "properties": { "workflowId": { "type": "string", "format": "uuid" }, "timeoutMs": { "type": "integer", "minimum": 1000, "exclusiveMinimum": false, "maximum": 60000, "exclusiveMaximum": false, "default": 10000 } }, "required": [ "workflowId" ] }, "confirmation": { "type": "object", "properties": { "workflowId": { "type": "string", "format": "uuid" }, "timeoutMs": { "type": "integer", "minimum": 1000, "exclusiveMinimum": false, "maximum": 60000, "exclusiveMaximum": false, "default": 10000 } }, "required": [ "workflowId" ] }, "mode": { "type": "string", "enum": [ "standard", "chat" ], "default": "standard" }, "chat": { "type": "object", "properties": { "historyDepth": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 200, "exclusiveMaximum": false, "default": 20 }, "eventRetentionDays": { "type": "integer", "minimum": 7, "exclusiveMinimum": false, "maximum": 30, "exclusiveMaximum": false, "default": 14 }, "sessionTimeoutSeconds": { "type": "integer", "minimum": 30, "exclusiveMinimum": false, "maximum": 86400, "exclusiveMaximum": false, "default": 600 }, "hideHistory": { "type": "boolean", "default": false }, "hideToolCards": { "type": "boolean", "default": false }, "disclaimer": { "type": "string", "maxLength": 500 }, "welcomeMessage": { "type": "string", "maxLength": 2000 }, "endedWorkflowId": { "type": "string", "format": "uuid" }, "endedWorkflowTimeoutMs": { "type": "integer", "minimum": 1000, "exclusiveMinimum": false, "maximum": 60000, "exclusiveMaximum": false, "default": 30000 }, "memory": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false }, "maxRecallSessions": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 50, "exclusiveMaximum": false, "default": 10 }, "retentionDays": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 3650, "exclusiveMaximum": false, "default": 90 } } } } } } } } }, "lastTriggeredAt": { "description": "ISO 8601 timestamp of the last time this trigger fired.", "type": "string", "nullable": true }, "lastTriggerExecutionId": { "description": "Execution started by the most recent firing.", "type": "string" }, "triggerCount": { "description": "Lifetime number of firings.", "type": "number" }, "userId": { "description": "User who created the trigger.", "type": "string" }, "metadata": { "description": "Caller-owned metadata.", "type": "object", "additionalProperties": {} }, "webhookUrl": { "description": "Public URL to POST to. Webhook triggers only.", "type": "string" }, "formUrl": { "description": "Hosted form (or chat) URL. Form triggers only, and only once the trigger has a name.", "type": "string" }, "eventWebhookUrl": { "description": "Inbound URL the event provider posts to. Event triggers on webhook-delivered providers only.", "type": "string" }, "eventWebhookSecret": { "description": "Shared secret the event provider signs its deliveries with.", "type": "string" }, "eventAssignmentId": { "description": "Event-listener assignment backing this trigger.", "type": "string" }, "eventAuthRequired": { "description": "When false, anyone holding the event webhook URL can start the workflow without presenting the secret. Defaults to true.", "type": "boolean" }, "message": { "type": "string" } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "workflowId", "type", "enabled", "config", "triggerCount", "message" ] }, "DuplicateTriggerBodyDto": { "type": "object", "properties": { "targetWorkflowId": { "description": "Workflow to attach the copy to.", "type": "string" }, "name": { "description": "Name for the copy. Defaults to the source name with a `-copy-` suffix, which keeps the copy unique within the organization.", "type": "string" } }, "required": [ "targetWorkflowId" ] }, "ConnectionListResponseDto": { "type": "object", "properties": { "total": { "description": "Total records matching the filter, ignoring paging.", "type": "number" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Owning organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "userId": { "description": "User who created the connection.", "type": "string" }, "name": { "description": "The identifier workflow steps reference this connection by. Unique within the organization.", "type": "string" }, "type": { "description": "Connection type. Determines which fields the config carries — fetch the per-type schema from `GET /connections/types/{type}/schema`.", "type": "string", "enum": [ "five9", "basic-auth", "database", "api-key", "gcp-service-account", "aws-credentials", "sftp", "smtp", "twilio", "custom", "form-auth", "custom-oauth", "oauth-google", "oauth-microsoft", "oauth-salesforce", "oauth-github", "oauth-slack", "oauth-zoom", "oauth-webex" ] }, "config": { "description": "The stored config, encrypted. An opaque envelope rather than a usable credential: read the real values with `GET /connections/{id}/config`.", "type": "string" }, "metadata": { "description": "Caller-owned metadata.", "type": "object", "additionalProperties": {} }, "oauth": { "description": "Public profile of the authorized account, for the `oauth-*` connection types. Access and refresh tokens stay inside the encrypted config and never appear here.", "type": "object", "properties": { "tokenExpiresAt": { "description": "ISO 8601 timestamp the stored access token expires at.", "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" }, "profileUrl": { "type": "string" } } }, "settings": { "description": "Behavior toggles attached to this connection. Stored unencrypted: this field never carries credentials.", "type": "object", "properties": { "integrations": { "description": "Background integration toggles, keyed by integration id.", "type": "object", "additionalProperties": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] } }, "dataFeeds": { "description": "Scheduled sync toggles, keyed by data-feed id.", "type": "object", "additionalProperties": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "syncIntervalMinutes": { "type": "integer" } }, "required": [ "enabled" ] } } } }, "variant": { "description": "Which branch of a multi-variant connection type this row uses (for `form-auth`, its `authMethod`). A mode label, never a credential. Absent for types with a single config shape, and for a row whose config could not be read.", "type": "string" } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "name", "type", "config", "metadata" ] } } }, "required": [ "total", "data" ] }, "CreateConnectionDto": { "type": "object", "properties": { "organizationId": { "type": "string", "format": "uuid" }, "userId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {} }, "updatedAt": {}, "createdAt": {}, "name": { "description": "Connection identifier - use snake_case, kebab-case, or camelCase (e.g., \"five9-production\")", "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[a-zA-Z_][a-zA-Z0-9_-]*$" }, "type": { "description": "Connection type - determines the structure of the config", "type": "string", "enum": [ "five9", "basic-auth", "database", "api-key", "gcp-service-account", "aws-credentials", "sftp", "smtp", "twilio", "custom", "form-auth", "custom-oauth", "oauth-google", "oauth-microsoft", "oauth-salesforce", "oauth-github", "oauth-slack", "oauth-zoom", "oauth-webex" ] }, "config": { "description": "Connection configuration (will be validated and encrypted)", "type": "object", "additionalProperties": {} }, "oauth": { "description": "OAuth metadata (public profile data, not sensitive)", "type": "object", "properties": { "tokenExpiresAt": { "description": "OAuth token expiration date" }, "email": { "description": "OAuth user email", "type": "string" }, "name": { "description": "OAuth user name", "type": "string" }, "profileUrl": { "description": "OAuth user profile picture URL", "type": "string" } } }, "settings": { "type": "object", "properties": { "integrations": { "type": "object", "additionalProperties": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] } }, "dataFeeds": { "type": "object", "additionalProperties": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "syncIntervalMinutes": { "type": "integer", "minimum": 5, "exclusiveMinimum": false, "maximum": 1440, "exclusiveMaximum": false } }, "required": [ "enabled" ] } } } } }, "required": [ "name", "type", "config" ] }, "ConnectionResponseDto": { "type": "object", "properties": { "id": { "description": "Unique id.", "type": "string" }, "suid": { "description": "Short, human-friendly id used in URLs and slugs.", "type": "string" }, "organizationId": { "description": "Owning organization.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "updatedAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "userId": { "description": "User who created the connection.", "type": "string" }, "name": { "description": "The identifier workflow steps reference this connection by. Unique within the organization.", "type": "string" }, "type": { "description": "Connection type. Determines which fields the config carries — fetch the per-type schema from `GET /connections/types/{type}/schema`.", "type": "string", "enum": [ "five9", "basic-auth", "database", "api-key", "gcp-service-account", "aws-credentials", "sftp", "smtp", "twilio", "custom", "form-auth", "custom-oauth", "oauth-google", "oauth-microsoft", "oauth-salesforce", "oauth-github", "oauth-slack", "oauth-zoom", "oauth-webex" ] }, "config": { "description": "The stored config, encrypted. An opaque envelope rather than a usable credential: read the real values with `GET /connections/{id}/config`.", "type": "string" }, "metadata": { "description": "Caller-owned metadata.", "type": "object", "additionalProperties": {} }, "oauth": { "description": "Public profile of the authorized account, for the `oauth-*` connection types. Access and refresh tokens stay inside the encrypted config and never appear here.", "type": "object", "properties": { "tokenExpiresAt": { "description": "ISO 8601 timestamp the stored access token expires at.", "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" }, "profileUrl": { "type": "string" } } }, "settings": { "description": "Behavior toggles attached to this connection. Stored unencrypted: this field never carries credentials.", "type": "object", "properties": { "integrations": { "description": "Background integration toggles, keyed by integration id.", "type": "object", "additionalProperties": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] } }, "dataFeeds": { "description": "Scheduled sync toggles, keyed by data-feed id.", "type": "object", "additionalProperties": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "syncIntervalMinutes": { "type": "integer" } }, "required": [ "enabled" ] } } } } }, "required": [ "id", "suid", "organizationId", "createdAt", "updatedAt", "name", "type", "config", "metadata" ] }, "UpdateConnectionDto": { "type": "object", "properties": { "userId": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {} }, "updatedAt": {}, "createdAt": {}, "name": { "description": "Connection identifier - use snake_case, kebab-case, or camelCase (e.g., \"five9-production\")", "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[a-zA-Z_][a-zA-Z0-9_-]*$" }, "type": { "description": "Connection type - determines the structure of the config", "type": "string", "enum": [ "five9", "basic-auth", "database", "api-key", "gcp-service-account", "aws-credentials", "sftp", "smtp", "twilio", "custom", "form-auth", "custom-oauth", "oauth-google", "oauth-microsoft", "oauth-salesforce", "oauth-github", "oauth-slack", "oauth-zoom", "oauth-webex" ] }, "config": { "description": "Connection configuration (will be validated and encrypted)", "type": "object", "additionalProperties": {} }, "oauth": { "description": "OAuth metadata (public profile data, not sensitive)", "type": "object", "properties": { "tokenExpiresAt": { "description": "OAuth token expiration date" }, "email": { "description": "OAuth user email", "type": "string" }, "name": { "description": "OAuth user name", "type": "string" }, "profileUrl": { "description": "OAuth user profile picture URL", "type": "string" } } }, "settings": { "type": "object", "properties": { "integrations": { "type": "object", "additionalProperties": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] } }, "dataFeeds": { "type": "object", "additionalProperties": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "syncIntervalMinutes": { "type": "integer", "minimum": 5, "exclusiveMinimum": false, "maximum": 1440, "exclusiveMaximum": false } }, "required": [ "enabled" ] } } } } } }, "ConnectionTypesResponseDto": { "type": "object", "properties": { "types": { "description": "Every connection type this deployment can create.", "type": "array", "items": { "type": "string" } } }, "required": [ "types" ] }, "ConnectionTypeSchemaResponseDto": { "type": "object", "properties": { "type": { "description": "The type that was requested.", "type": "string" }, "schema": { "description": "JSON Schema for that type's config, generated from the server-side Zod definition. Describes the shape `config` must have on create and update; also what the builder renders its credential form from.", "type": "object", "additionalProperties": {} } }, "required": [ "type", "schema" ] }, "CreateManagedOrgBody": { "type": "object", "properties": { "name": { "description": "Display name for the new customer organization", "type": "string", "minLength": 1, "maxLength": 200 }, "planSlug": { "description": "Slug of the plan the child is created on. Must be a plan granted to this partner.", "type": "string", "minLength": 1 }, "trialDays": { "description": "Evaluation/pilot window: child is born TRIALING and contributes no invoice lines until activated. Omit for an immediately-billable child.", "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 180, "exclusiveMaximum": false }, "autoJoin": { "description": "Seat the creating user in the new child org (default true — convenient for hands-on partners). Pass false for machine-driven bulk provisioning to avoid seat sprawl. Ignored when the credential has no linked user.", "type": "boolean" }, "externalRef": { "description": "Partner's own customer key, unique per partner. Repeat creates with the same ref return the existing child instead of provisioning a duplicate — makes machine-driven creation retry-safe.", "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "name", "planSlug" ] }, "ManagedOrgResponseDto": { "type": "object", "properties": { "organizationId": { "description": "Id of the child organization.", "type": "string" }, "name": { "type": "string" }, "plan": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" } }, "required": [ "slug", "name" ] }, "pendingPlan": { "description": "A requested plan change that has not taken effect yet. Plan changes land at the NEXT billing period, never mid-period: the month in progress bills at the current plan. Absent when no change is pending.", "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "effectiveAt": { "description": "ISO 8601 date the change takes effect (next period start).", "type": "string" } }, "required": [ "slug", "name", "effectiveAt" ] }, "status": { "description": "Billing status of the child: `active`, `trialing`, `suspended`, `past_due`, `canceled` or `incomplete`. Only `active` and `trialing` are working states; `trialing` children contribute no invoice lines until activated.", "type": "string" }, "suspendedReason": { "description": "Why the child was suspended, when it is.", "type": "string" }, "trialEnd": { "description": "ISO 8601 end of the trial window, when the child is trialing.", "type": "string" }, "currentPeriodStart": { "description": "ISO 8601 start of the billing period currently accruing.", "type": "string" }, "currentPeriodEnd": { "description": "ISO 8601 end of that period.", "type": "string" }, "createdAt": { "description": "ISO 8601 timestamp.", "type": "string" }, "externalRef": { "description": "The partner's own customer key, when the child was created with one.", "type": "string" }, "yourPriceMonthlyCents": { "description": "What this child costs YOU per month, in cents — per-deal override, wholesale discount, or retail, in that precedence. Present on list responses.", "type": "number" }, "retailPriceMonthlyCents": { "description": "The plan's public retail price per month, in cents. The margin between this and `yourPriceMonthlyCents` is yours. Present on list responses.", "type": "number" }, "reused": { "description": "True when a create call matched an existing `externalRef` and returned the existing child instead of provisioning a new one. Absent otherwise.", "type": "boolean" }, "billing": { "description": "How this org is billed. `partner-paid` = on your consolidated invoice. `direct-pay` = the customer pays the platform directly and you operate the org (e.g. after graduation): price fields are absent and billing-lifecycle actions do not apply, but tokens and seats still work.", "type": "string", "enum": [ "partner-paid", "direct-pay" ] } }, "required": [ "organizationId", "name", "plan", "status", "currentPeriodStart", "currentPeriodEnd" ] }, "AssignablePlanResponseDto": { "type": "object", "properties": { "slug": { "description": "Pass this as `planSlug` when creating a child organization.", "type": "string" }, "name": { "description": "Display name of the plan.", "type": "string" }, "description": { "type": "string" }, "family": { "description": "Plan family, when the plan belongs to one.", "type": "string" }, "priceMonthly": { "description": "Retail list price of the plan, in whole dollars. This is the public price, NOT necessarily what you pay: see `yourPriceMonthlyCents`.", "type": "number" }, "yourPriceMonthlyCents": { "description": "What a new child on this plan costs YOU per month, in cents, after your wholesale discount. Cents because a percentage discount on a whole-dollar retail price can land on fractional dollars. A per-deal negotiated price agreed for one specific child overrides even this, and is not visible here because it is set per child rather than per plan.", "type": "number" }, "priceSource": { "description": "Which rule produced `yourPriceMonthlyCents`: `wholesale-discount` when your default partner discount applied, `retail` when it did not. Non-public plans always report `retail` because their listed price is already the negotiated one and discounting it again would double-discount.", "type": "string", "enum": [ "retail", "wholesale-discount" ] }, "discountPercent": { "description": "The wholesale discount percentage applied. Present only when `priceSource` is `wholesale-discount`.", "type": "number" } }, "required": [ "slug", "name", "yourPriceMonthlyCents", "priceSource" ] }, "UpcomingInvoiceResponseDto": { "type": "object", "properties": { "totalCents": { "description": "Everything accrued so far, in cents. baseFeeCents + overageCents.", "type": "number" }, "baseFeeCents": { "description": "Closed base-fee months captured and awaiting the next invoice.", "type": "number" }, "overageCents": { "description": "Unbilled overage accrued by your customers.", "type": "number" }, "chargeCount": { "description": "Number of base-fee months awaiting billing.", "type": "number" }, "snapshotCount": { "description": "Number of unbilled overage records.", "type": "number" } }, "required": [ "totalCents", "baseFeeCents", "overageCents", "chargeCount", "snapshotCount" ] }, "PartnerSolutionResponseDto": { "type": "object", "properties": { "organizationId": { "description": "The customer org the package is installed in.", "type": "string" }, "packageId": { "type": "string" }, "packageName": { "type": "string" }, "origin": { "description": "Whose package it is: `yours` = published by your org, `theirs` = the customer’s own, `marketplace` = any other publisher.", "type": "string", "enum": [ "yours", "marketplace", "theirs" ] }, "installedVersion": { "type": "string" }, "latestVersion": { "type": "string" }, "behindLatest": { "description": "True when a newer published version of your package exists.", "type": "boolean" }, "lastRunAt": { "description": "ISO 8601 time of the install’s most recent workflow run.", "type": "string" }, "runs": { "description": "Execution counts over the trailing 14 days.", "type": "object", "properties": { "total": { "type": "number" }, "success": { "type": "number" }, "failed": { "type": "number" } }, "required": [ "total", "success", "failed" ] } }, "required": [ "organizationId", "packageId", "packageName", "origin", "installedVersion", "behindLatest", "runs" ] }, "ChildUsageResponseDto": { "type": "object", "properties": { "organizationId": { "type": "string" }, "factors": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "used": { "type": "number" }, "included": { "type": "number" }, "isUnlimited": { "type": "boolean" } }, "required": [ "key", "name", "used", "included", "isUnlimited" ] } } }, "required": [ "organizationId", "factors" ] }, "PartnerInvoiceResponseDto": { "type": "object", "properties": { "invoiceId": { "description": "The invoice id, matching the emailed Stripe invoice.", "type": "string" }, "issuedAt": { "description": "ISO 8601.", "type": "string" }, "totalCents": { "type": "number" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "amountCents": { "type": "number" }, "kind": { "description": "`base-fee` or `overage`.", "type": "string" } }, "required": [ "description", "amountCents", "kind" ] } } }, "required": [ "invoiceId", "totalCents", "lines" ] }, "InvoiceLinkResponseDto": { "type": "object", "properties": { "invoiceId": { "type": "string" }, "issuedAt": { "description": "ISO 8601.", "type": "string" }, "totalCents": { "type": "number" }, "status": { "description": "Live Stripe status: `draft` (not sent yet, no link), `open` (sent, awaiting payment), `paid`, `void`, `uncollectible`, or `deleted` when the invoice no longer exists in Stripe.", "type": "string" }, "hostedUrl": { "description": "The invoice page your customer receives. Present only once the invoice is finalized: a draft has no shareable page yet.", "type": "string" } }, "required": [ "invoiceId", "totalCents", "status" ] }, "ChangeManagedOrgPlanBody": { "type": "object", "properties": { "planSlug": { "description": "Slug of the plan to move the child to. Must be a plan granted to this partner (GET /partner/managed-orgs/plans). Passing the child's CURRENT plan cancels any pending change.", "type": "string", "minLength": 1 } }, "required": [ "planSlug" ] }, "DetachResultResponseDto": { "type": "object", "properties": { "organizationId": { "type": "string" }, "detached": { "type": "boolean" }, "capturedMonths": { "description": "Closed months settled to you before the relationship ended — they appear on your next consolidated invoice.", "type": "number" } }, "required": [ "organizationId", "detached", "capturedMonths" ] }, "GraduateManagedOrgBody": { "type": "object", "properties": { "graceDays": { "description": "How long the customer has to subscribe directly before the org suspends. Defaults to 30 days.", "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 90, "exclusiveMaximum": false } } }, "GraduateResultResponseDto": { "type": "object", "properties": { "organizationId": { "type": "string" }, "graduated": { "type": "boolean" }, "capturedMonths": { "description": "Closed months settled to you — on your next consolidated invoice.", "type": "number" }, "checkoutBy": { "description": "ISO 8601 deadline: the customer must subscribe directly by this date or the org suspends.", "type": "string" } }, "required": [ "organizationId", "graduated", "capturedMonths", "checkoutBy" ] }, "ChildTokenResponseDto": { "type": "object", "properties": { "tokenId": { "type": "string" }, "name": { "type": "string" }, "revoked": { "type": "boolean" }, "createdAt": { "description": "ISO 8601.", "type": "string" }, "expiresAt": { "description": "ISO 8601.", "type": "string" } }, "required": [ "tokenId", "revoked" ] }, "MintChildTokenBody": { "type": "object", "properties": { "name": { "description": "Label for the token. Defaults to \"partner-minted\".", "type": "string", "minLength": 1, "maxLength": 100 }, "expiresInDays": { "description": "Token lifetime in days. Defaults to 90 — operator keys never live forever by accident.", "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 365, "exclusiveMaximum": false }, "rotate": { "description": "Revoke all previously partner-minted tokens for this child in the same call (create new + revoke old).", "type": "boolean" } } }, "MintedChildTokenResponseDto": { "type": "object", "properties": { "tokenId": { "description": "Id of the minted token. Safe to store and log.", "type": "string" }, "secret": { "description": "The token value. Returned ONLY on this response and never recoverable afterwards: capture it now or mint again.", "type": "string" }, "name": { "description": "Label the token was created with.", "type": "string" }, "expiresAt": { "description": "ISO 8601 expiry. Defaults to 90 days out.", "type": "string" }, "revokedCount": { "description": "How many previously partner-minted tokens for this child were revoked by this call. Always 0 unless `rotate` was set.", "type": "number" } }, "required": [ "tokenId", "secret", "name", "revokedCount" ] }, "ChildMembershipResponseDto": { "type": "object", "properties": { "organizationId": { "description": "Id of the child organization.", "type": "string" }, "seated": { "description": "Whether the calling user is a member of the child after this call.", "type": "boolean" } }, "required": [ "organizationId", "seated" ] }, "LogsSearchDto": { "type": "object", "properties": { "sources": { "type": "array", "maxItems": 6, "items": { "type": "string", "enum": [ "workflow", "connection", "event-receiver", "integration-sync", "audit", "trigger" ] } }, "level": { "type": "array", "maxItems": 4, "items": { "type": "string", "enum": [ "debug", "info", "warn", "error" ] } }, "channels": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1, "maxLength": 256 } }, "providers": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1, "maxLength": 256 } }, "origins": { "type": "array", "maxItems": 10, "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "workflowId": { "type": "string", "minLength": 1, "maxLength": 256 }, "executionId": { "type": "string", "minLength": 1, "maxLength": 256 }, "connectionId": { "type": "string", "minLength": 1, "maxLength": 256 }, "connectionName": { "type": "string", "minLength": 1, "maxLength": 256 }, "triggerId": { "type": "string", "minLength": 1, "maxLength": 256 }, "instanceId": { "type": "string", "minLength": 1, "maxLength": 256 }, "tags": { "type": "array", "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "text": { "type": "array", "maxItems": 10, "items": { "type": "string", "minLength": 1, "maxLength": 512 } }, "dataFilters": { "type": "array", "maxItems": 10, "items": { "type": "object", "properties": { "path": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "type": "string", "minLength": 1, "maxLength": 256 } }, "operator": { "type": "string", "enum": [ "eq", "neq", "contains", "not_contains", "regex", "not_regex", "gt", "gte", "lt", "lte" ], "default": "eq" }, "value": { "type": "string", "maxLength": 512 } }, "required": [ "path", "value" ] } }, "messageFilters": { "type": "array", "maxItems": 10, "items": { "type": "object", "properties": { "operator": { "type": "string", "enum": [ "eq", "neq", "contains", "not_contains", "regex", "not_regex", "gt", "gte", "lt", "lte" ], "default": "eq" }, "value": { "type": "string", "maxLength": 512 } }, "required": [ "value" ] } }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "before": { "type": "string", "format": "date-time" }, "limit": { "type": "integer", "minimum": 1, "exclusiveMinimum": false, "maximum": 1000, "exclusiveMaximum": false, "default": 200 } } }, "LogsSearchResponseDto": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Synthesized row id. Stable for a given row: pass it back as `id` to deep-link one entry, or as `rowId` to reveal a masked field.", "type": "string" }, "organizationId": { "type": "string" }, "source": { "description": "Which subsystem emitted the row. Also the permission boundary: a caller only ever sees sources they hold the mapped permission for.", "type": "string", "enum": [ "workflow", "connection", "event-receiver", "integration-sync", "audit", "trigger" ] }, "channel": { "description": "Sub-stream within the source.", "type": "string" }, "level": { "type": "string", "enum": [ "debug", "info", "warn", "error" ] }, "origin": { "description": "What produced the row — `core.log` for an author-written step, `engine` for one the engine generated. Empty where it does not apply.", "type": "string" }, "timestamp": { "description": "ISO 8601 timestamp, millisecond precision.", "type": "string" }, "message": { "type": "string" }, "workflowId": { "type": "string" }, "workflowName": { "description": "Resolved at read time from the workflow’s current name.", "type": "string" }, "executionId": { "type": "string" }, "stepId": { "type": "string" }, "connectionId": { "type": "string" }, "connectionName": { "type": "string" }, "triggerId": { "type": "string" }, "instanceId": { "type": "string" }, "provider": { "type": "string" }, "eventId": { "type": "string" }, "actorUserId": { "description": "Audit rows only.", "type": "string" }, "actorType": { "description": "Audit rows only.", "type": "string" }, "action": { "description": "Audit rows only.", "type": "string" }, "resourceType": { "description": "Audit rows only.", "type": "string" }, "resourceId": { "description": "Audit rows only.", "type": "string" }, "sensitivity": { "description": "Redaction class the row was written with. `restricted` masks every top-level key of `data`.", "type": "string" }, "data": { "description": "The structured payload, as emitted. Shape varies by source and channel; sensitive values are masked here, not omitted.", "type": "object", "additionalProperties": {} }, "tags": { "description": "The workflow’s tags as they stand now, not as of the write.", "type": "array", "items": { "type": "string" } }, "redactedPaths": { "description": "Paths within `data` (plus the literal `message`) that the read-time redactor masked. These are exactly the paths `POST /logs/reveal` will un-mask; empty when nothing was masked.", "type": "array", "items": { "type": "string" } } }, "required": [ "id", "organizationId", "source", "channel", "level", "origin", "timestamp", "message", "workflowId", "workflowName", "executionId", "stepId", "connectionId", "connectionName", "triggerId", "instanceId", "provider", "eventId", "actorUserId", "actorType", "action", "resourceType", "resourceId", "sensitivity", "data", "tags", "redactedPaths" ] } }, "hasMore": { "description": "More rows exist older than the last one returned. Page by sending the oldest `timestamp` you received as `before`.", "type": "boolean" }, "facets": { "description": "Value counts per facet column, over the same window and permissions as the rows. Drives the explorer’s facet rail.", "type": "object", "properties": { "source": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" } }, "required": [ "value", "count" ] } }, "level": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" } }, "required": [ "value", "count" ] } }, "channel": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" } }, "required": [ "value", "count" ] } }, "provider": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" } }, "required": [ "value", "count" ] } }, "origin": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" } }, "required": [ "value", "count" ] } }, "tags": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" } }, "required": [ "value", "count" ] } } }, "required": [ "source", "level", "channel", "provider", "origin", "tags" ] }, "histogram": { "description": "Row counts over time, bucketed to suit the requested window.", "type": "array", "items": { "type": "object", "properties": { "ts": { "description": "ISO 8601 start of the bucket.", "type": "string" }, "counts": { "description": "Row count per level, keyed by `debug` / `info` / `warn` / `error`.", "type": "object", "additionalProperties": { "type": "number" } } }, "required": [ "ts", "counts" ] } } }, "required": [ "entries", "hasMore", "facets", "histogram" ] }, "LogsRevealDto": { "type": "object", "properties": { "rowId": { "type": "string", "minLength": 1, "maxLength": 64 }, "path": { "type": "string", "minLength": 1, "maxLength": 512 }, "timestamp": { "type": "string", "format": "date-time" } }, "required": [ "rowId", "path", "timestamp" ] }, "LogRevealResponseDto": { "type": "object", "properties": { "value": { "description": "The un-masked value at the requested path. Any JSON type, because it is whatever the emitting subsystem wrote there." }, "source": { "description": "Source of the row that was revealed.", "type": "string", "enum": [ "workflow", "connection", "event-receiver", "integration-sync", "audit", "trigger" ] }, "auditContext": { "description": "Identifiers of the revealed row, echoed from what was written to the `logs.sensitive.reveal` audit event. Correlators only — never the value, never the raw message.", "type": "object", "properties": { "timestamp": { "type": "string" }, "level": { "type": "string", "enum": [ "debug", "info", "warn", "error" ] }, "channel": { "type": "string" }, "origin": { "type": "string" }, "workflowId": { "type": "string" }, "executionId": { "type": "string" }, "stepId": { "type": "string" }, "connectionId": { "type": "string" }, "triggerId": { "type": "string" }, "eventId": { "type": "string" } }, "required": [ "timestamp", "level", "channel", "origin", "workflowId", "executionId", "stepId", "connectionId", "triggerId", "eventId" ] } }, "required": [ "value", "source", "auditContext" ] } } }, "security": [ { "accessToken": [] } ] }