{ "openapi": "3.1.0", "info": { "title": "SCMotif data API", "version": "2.0.0", "description": "Upload files into a project, run its saved workflows and download the results, from a system of your own. Every call carries an integration key a person created under Settings, as `Authorization: Bearer `, and acts as that person within the projects and access the key was given. File bytes never travel in these requests: an upload answers signed links to send its parts to, and an export answers a signed link to download from." }, "paths": { "/projects": { "get": { "operationId": "list_projects", "summary": "List projects", "description": "List the projects this key reaches, to find the id of the one a script works in.", "parameters": [ { "name": "include_counts", "in": "query", "required": false, "schema": { "default": false, "title": "Include Counts", "type": "boolean" } } ], "responses": { "200": { "description": "List projects", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/ProjectListItem" }, "title": "Response List Projects Api Projects Get", "type": "array" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/data-sources": { "get": { "operationId": "list_data_sources", "summary": "List data sources", "description": "List a project's data sources, to find the one a refreshed file goes into, or one a run wrote.", "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "description": "Keep the data sources whose latest file is of this kind. Omit for all.", "enum": [ "tabular", "document" ], "type": "string" } }, { "name": "project_id", "in": "query", "required": true, "schema": { "description": "The project this call acts in.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "List data sources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSourceListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/data-sources/{id}": { "get": { "operationId": "get_data_source", "summary": "Get data source", "description": "Read one data source: its name, how many files it holds and its latest file.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "title": "Data Source Id", "type": "string" } }, { "name": "project_id", "in": "query", "required": true, "schema": { "description": "The project this call acts in.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Get data source", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSourceResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/data-sources/upload": { "post": { "operationId": "upload_data_source", "summary": "Upload a file", "description": "Start uploading a file under a name no other file in the project has, into the data source `data_source_id` names (it becomes the latest) or starting one named `data_source_name`. The answer lists the parts to PUT to their signed links; the file's bytes never travel in this request.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The file's name: .csv, .xlsx, .md or .txt (save .xls as .xlsx), unused by the project's files.", "maxLength": 200, "type": "string", "minLength": 1, "pattern": "\\S" }, "project_id": { "description": "The project this call acts in.", "format": "uuid", "type": "string" }, "sha256": { "description": "Lowercase hex SHA-256 over the exact whole file. Required independently of storage multipart ETags; ingestion rejects the session if the stored bytes differ.", "pattern": "^[0-9a-f]{64}$", "type": "string" }, "size_bytes": { "description": "The exact file size in bytes. It reserves account capacity and determines the fixed multipart slices before bytes travel.", "minimum": 1, "type": "integer" }, "data_source_id": { "description": "Joins this data source as its latest file.", "format": "uuid", "type": "string" }, "data_source_name": { "description": "Or starts a data source of this name.", "maxLength": 200, "minLength": 1, "pattern": "\\S", "type": "string" } }, "additionalProperties": false, "required": [ "name", "project_id", "sha256", "size_bytes" ] } } } }, "responses": { "200": { "description": "Upload a file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSourceUploadSessionInProgress" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "403": { "$ref": "#/components/responses/ReadOnlyKey" } } } }, "/upload-sessions/{id}": { "get": { "operationId": "get_upload_session", "summary": "Get upload session", "description": "Read where an upload stands. `ready` carries the new file's id and its data source's id; `rejected` carries what was wrong with the file.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "name": "project_id", "in": "query", "required": true, "schema": { "description": "The project this call acts in.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Get upload session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSourceUploadSession" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/upload-sessions/{id}/resume": { "post": { "operationId": "resume_upload", "summary": "Resume upload", "description": "Ask again for the signed links of the parts an upload still needs, after the earlier links expired.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "project_id": { "description": "The project this call acts in.", "format": "uuid", "type": "string" } }, "additionalProperties": false, "required": [ "project_id" ] } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Resume upload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSourceUploadSession" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "403": { "$ref": "#/components/responses/ReadOnlyKey" } } } }, "/upload-sessions/{id}/cancel": { "post": { "operationId": "cancel_data_source_upload", "summary": "Cancel data source upload", "description": "Abandon an upload that has not finished; nothing is published.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "project_id": { "description": "The project this call acts in.", "format": "uuid", "type": "string" } }, "additionalProperties": false, "required": [ "project_id" ] } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Cancel data source upload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteConfirmation" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "403": { "$ref": "#/components/responses/ReadOnlyKey" } } } }, "/upload-sessions/{id}/complete": { "post": { "operationId": "complete_upload", "summary": "Complete upload", "description": "Finish an upload once every part has been sent. Checking the file takes a moment: poll the upload until it is `ready` or `rejected`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "project_id": { "description": "The project this call acts in.", "format": "uuid", "type": "string" } }, "additionalProperties": false, "required": [ "project_id" ] } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Complete upload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSourceUploadSession" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "403": { "$ref": "#/components/responses/ReadOnlyKey" } } } }, "/data-sources/{id}/files": { "get": { "operationId": "list_data_source_files", "summary": "List the files of a data source", "description": "List a data source's files, newest first, to see which file is its latest.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "name": "before_version", "in": "query", "required": false, "schema": { "description": "The last `number` the page before answered.", "minimum": 1, "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "name": "project_id", "in": "query", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "List the files of a data source", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/FileResponse" }, "type": "array" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/workflows": { "get": { "operationId": "list_workflows", "summary": "List workflows", "description": "List a project's workflows, to find the id of the one to run.", "parameters": [ { "name": "project_id", "in": "query", "required": true, "schema": { "description": "The project this call acts in.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "List workflows", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/WorkflowListResponse" }, "title": "Response List Workflows Api Projects Project Id Workflow Get", "type": "array" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/workflows/{id}/run": { "post": { "operationId": "run_workflow", "summary": "Run workflow", "description": "Start a run of a saved workflow. The answer carries the execution id to follow it by.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "project_id": { "description": "The project this call acts in.", "format": "uuid", "type": "string" } }, "additionalProperties": false, "required": [ "project_id" ] } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "description": "UUID of the deployed workflow.", "format": "uuid", "type": "string" } } ], "responses": { "201": { "description": "Run workflow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowExecutionResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "403": { "$ref": "#/components/responses/ReadOnlyKey" } } } }, "/executions/{id}": { "get": { "operationId": "get_execution", "summary": "Get execution", "description": "Read a run's status. Poll until it has finished; a finished run lists the scenarios it published.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "description": "The execution id `run_workflow` answered as `executionId`.", "format": "uuid", "type": "string" } }, { "name": "include_provenance", "in": "query", "required": false, "schema": { "default": false, "description": "Also answer `workflowSnapshot` and `reproductionManifest`. Both are fixed at acceptance, so ask once, not on every poll.", "type": "boolean" } }, { "name": "project_id", "in": "query", "required": true, "schema": { "description": "The project this call acts in.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Get execution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowExecutionStatus" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/executions/{id}/cancel": { "post": { "operationId": "cancel_execution", "summary": "Cancel execution", "description": "Stop a run that has not finished.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "project_id": { "description": "The project this call acts in.", "format": "uuid", "type": "string" } }, "additionalProperties": false, "required": [ "project_id" ] } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "description": "The execution id `run_workflow` answered as `executionId`.", "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Cancel execution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelExecutionResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "403": { "$ref": "#/components/responses/ReadOnlyKey" } } } }, "/executions/{id}/diagnostics": { "get": { "operationId": "list_execution_diagnostics", "summary": "List execution diagnostics", "description": "Read a run's findings, a page at a time, to see why it failed or what it warned about.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "description": "The execution id `run_workflow` answered as `executionId`.", "format": "uuid", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 25, "description": "Page size (default 25, max 100).", "maximum": 100, "minimum": 1, "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "schema": { "default": 0, "description": "Page offset for the next batch.", "minimum": 0, "type": "integer" } }, { "name": "project_id", "in": "query", "required": true, "schema": { "description": "The project this call acts in.", "format": "uuid", "type": "string" } }, { "name": "severity", "in": "query", "required": false, "schema": { "description": "Return only findings of this severity; omit for all.", "enum": [ "error", "warning", "info" ], "type": "string" } } ], "responses": { "200": { "description": "List execution diagnostics", "content": { "application/json": { "schema": { "description": "The items are `Diagnostic`, the shape \u00a74 fixes and every other surface returns. `WorkflowExecutionIssueResponse` is a persisted *row* \u2014 it carries `id`, `executionId`, `projectId`, `workflowName` and per-severity counts \u2014 and returning that here would make the same finding two different objects depending on which operation a caller reached it through, which is the disagreement \u00a71 exists to remove.", "items": { "$ref": "#/components/schemas/Diagnostic" }, "type": "array" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/scenarios/{id}/export": { "post": { "operationId": "export_scenario", "summary": "Export scenario", "description": "Prepare a scenario's tables as one file and answer a short-lived signed link to download it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "project_id": { "description": "The project this call acts in.", "format": "uuid", "type": "string" } }, "additionalProperties": false, "required": [ "project_id" ] } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "Export scenario", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactExport" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } } }, "components": { "schemas": { "Error": { "description": "A refusal the caller can act on: what is wrong, and, where there is one, what to do about it.", "properties": { "error": { "type": "string" }, "explanation": { "type": "string" }, "remedy": { "type": "string" }, "field": { "description": "The input the refusal is about.", "type": "string" } }, "required": [ "error" ], "title": "Error", "type": "object" }, "Refusal": { "description": "The operation read the request and refused it, saying why in one diagnostic per problem.", "properties": { "diagnostics": { "items": { "$ref": "#/components/schemas/Diagnostic" }, "type": "array" } }, "required": [ "diagnostics" ], "title": "Refusal", "type": "object" }, "ArtifactExport": { "additionalProperties": false, "description": "A prepared, immutable export artifact held for a limited time.", "properties": { "download_expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "download_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A GET-only link to the file, valid until download_expires_at. Null when this deployment has no public object storage." }, "expires_at": { "description": "After this the export can be neither downloaded nor imported.", "format": "date-time", "type": "string" }, "export_id": { "format": "uuid", "type": "string" }, "filename": { "type": "string" }, "guide_url": { "description": "The guide section that says, for each agent client, which network setting lets its sandbox fetch download_url's host. If your fetch cannot connect, your environment blocks that host: tell the person the host and this link instead of working around the missing file. Whole, composed by the product, absent when download_url is null.", "type": "string" }, "kind": { "enum": [ "scenario", "data_source" ], "type": "string" }, "sha256": { "pattern": "^[0-9a-f]{64}$", "type": "string" }, "size_bytes": { "minimum": 1, "type": "integer" }, "subject_id": { "description": "The exported object.", "format": "uuid", "type": "string" } }, "required": [ "export_id", "kind", "subject_id", "filename", "size_bytes", "sha256", "expires_at", "download_url", "download_expires_at" ], "title": "ArtifactExport", "type": "object" }, "CancelExecutionResponse": { "description": "Response model for cancelling a workflow execution.", "properties": { "executionId": { "description": "This run's execution id. Pass it as `execution_id` to `get` (kind execution), `cancel` (kind execution) and `list_execution_diagnostics`.", "title": "Execution ID", "type": "string" }, "status": { "title": "Status", "type": "string" }, "url": { "description": "This run's page, under the workflow it is a run of. Hand this to the person, and report the run by its name with that name as the link \u2014 the id is for your next call and is not something to put in front of a reader. The address is whole (scheme, host and path) and the product composed it: never build one yourself out of an id and a host, and if this field is absent, say what was done and name the run without a link.", "type": "string" } }, "required": [ "status", "executionId" ], "title": "CancelExecutionResponse", "type": "object" }, "DashboardRefreshAction": { "type": "object", "title": "DashboardRefreshAction", "description": "Explicit next step for the requested dashboard. A completed workflow never refreshes saved selections by itself.", "properties": { "tool": { "type": "string", "enum": [ "update" ] }, "kind": { "type": "string", "enum": [ "dashboard" ] }, "refresh_from_execution_id": { "type": "string" }, "instruction": { "type": "string" } }, "required": [ "tool", "kind", "refresh_from_execution_id", "instruction" ] }, "DashboardRefreshDiscovery": { "type": "object", "title": "DashboardRefreshDiscovery", "properties": { "count": { "type": "integer" }, "firstDashboard": { "anyOf": [ { "$ref": "#/components/schemas/DashboardRefreshReference" }, { "type": "null" } ] }, "refreshAction": { "anyOf": [ { "$ref": "#/components/schemas/DashboardRefreshAction" }, { "type": "null" } ] } }, "required": [ "count", "firstDashboard", "refreshAction" ], "description": "Dashboards selecting results of this workflow, whether already refreshed or still pinned. List them with `list` (kind dashboard) with workflow_id; use `update` (kind dashboard) with refresh_from_execution_id only for dashboards the analyst wants updated." }, "DashboardRefreshReference": { "type": "object", "title": "DashboardRefreshReference", "description": "A saved dashboard selecting results of this workflow. Refresh only when requested; it may intentionally be historical.", "properties": { "id": { "type": "string", "description": "Pass as dashboard_id to `get` or `update` (kind dashboard)." }, "name": { "type": "string" }, "url": { "type": "string", "description": "The existing dashboard link, unchanged by refresh." }, "showsExecution": { "type": "boolean", "description": "Whether this workflow's selected results all come from the reported execution. False means the dashboard link still shows a different run; rerunning did not refresh it." } }, "required": [ "id", "name", "showsExecution" ] }, "DataSourceFields": { "description": "What every data source carries.", "properties": { "id": { "description": "The data source id (UUID)", "title": "Id", "type": "string" }, "name": { "description": "The data source's name, unique in its project. Its files keep their own names.", "title": "Name", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "url": { "description": "This data source's page, showing what was uploaded. Hand this to the person, and report the data source by its name with that name as the link \u2014 the id is for your next call and is not something to put in front of a reader. The address is whole (scheme, host and path) and the product composed it: never build one yourself out of an id and a host, and if this field is absent, say what was done and name the data source without a link.", "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "fileCount": { "description": "How many files the data source holds.", "minimum": 0, "type": "integer" } }, "required": [ "id", "name", "fileCount", "createdAt", "updatedAt" ], "type": "object" }, "DataSourceKind": { "description": "What a data source is for.\n\n``tabular`` sources carry rows and columns and can feed a workflow.\n``document`` sources are reference prose \u2014 assumptions, methodology,\nresults write-ups \u2014 stored verbatim and read, never parsed.", "enum": [ "tabular", "document" ], "title": "DataSourceKind", "type": "string" }, "DataSourceListResponse": { "description": "Response model for listing data sources.", "properties": { "dataSources": { "items": { "$ref": "#/components/schemas/DataSourceResponse" }, "title": "Data Sources", "type": "array" }, "total": { "description": "Total number of data sources", "title": "Total", "type": "integer" }, "unfinishedUploads": { "description": "Uploads that hold a file name in this project and are not files yet, whatever `kind` asks for. A name one of them holds is refused to every other upload until it finishes or is cancelled.", "items": { "$ref": "#/components/schemas/UnfinishedUpload" }, "title": "Unfinished Uploads", "type": "array" } }, "required": [ "dataSources", "total", "unfinishedUploads" ], "title": "DataSourceListResponse", "type": "object" }, "DataSourceOrigin": { "description": "How a data source was created.", "enum": [ "upload", "workflow", "assistant" ], "title": "DataSourceOrigin", "type": "string" }, "DataSourceResponse": { "allOf": [ { "$ref": "#/components/schemas/DataSourceFields" }, { "properties": { "latestFile": { "$ref": "#/components/schemas/FileResponse", "description": "Its newest file: what a workflow reading the latest reads, and whose columns a mapping offers. Absent while the data source holds no file." }, "savedBy": { "additionalProperties": false, "description": "Present when a workflow's Save Data step writes this data source: each run adds a file, and no upload can.", "properties": { "nodeId": { "type": "string" }, "workflowId": { "format": "uuid", "type": "string" } }, "required": [ "workflowId", "nodeId" ], "type": "object" } }, "type": "object" } ], "description": "A data source: a named set of files, shown by its latest file. A workflow's Import Data node reads its latest file or one file of it.", "title": "DataSourceResponse", "type": "object" }, "DataSourceType": { "description": "File format of a stored data source, keyed off its extension.", "enum": [ "csv", "xlsx", "xls", "md", "txt" ], "title": "DataSourceType", "type": "string" }, "DataSourceUploadDestination": { "description": "Where a data-source upload's file goes: an existing data source, or the name of the one it creates. A scenario bundle's session carries neither.", "properties": { "dataSourceId": { "description": "The data source the file goes into or joined.", "format": "uuid", "type": "string" }, "newDataSourceName": { "description": "Until the file is published: the name of the new data source it creates.", "type": "string" } }, "type": "object" }, "DataSourceUploadLinks": { "description": "Where a person can finish a data-source upload the agent's own environment could not send, and the guide that says which client setting lets it through. Only a data-source upload carries them.", "properties": { "guideUrl": { "description": "The guide section that says, for each agent client, which network setting lets its PUTs reach the target host, and how a person uploads in the app instead. Hand it to the person with the refused host when your PUT is blocked. Whole, composed by the product, absent when no address can be given.", "type": "string" }, "url": { "description": "Where a person finishes this upload in the app: the project's data-source page until the upload is ready, then the data source itself. Uploading the same file there, under the same name, completes this session. Hand it to the person when your own PUT cannot reach the target host, with the data source's name as the link text. The address is whole (scheme, host and path) and the product composed it: never build one yourself out of an id and a host, and if this field is absent, name the project without a link. A scenario bundle's session carries neither link.", "type": "string" } }, "type": "object" }, "DataSourceUploadSession": { "allOf": [ { "$ref": "#/components/schemas/UploadSession" }, { "$ref": "#/components/schemas/DataSourceUploadLinks" }, { "$ref": "#/components/schemas/DataSourceUploadDestination" } ], "description": "An upload session, with the links a data-source upload adds.", "type": "object" }, "DataSourceUploadSessionInProgress": { "allOf": [ { "$ref": "#/components/schemas/UploadSessionInProgress" }, { "$ref": "#/components/schemas/DataSourceUploadLinks" }, { "$ref": "#/components/schemas/DataSourceUploadDestination" } ], "description": "A data-source upload in progress, with the links a person or agent finishes it by.", "type": "object" }, "DeleteConfirmation": { "description": "Confirmation that a resource was deleted.", "properties": { "deleted": { "description": "UUID of the deleted resource.", "format": "uuid", "type": "string" } }, "required": [ "deleted" ], "title": "DeleteConfirmation", "type": "object" }, "Diagnostic": { "description": "One structured finding. Its kind, category, label and evidence contract come from a core or installed package declaration.", "properties": { "category": { "enum": [ "data_quality", "configuration", "validation", "model_feasibility", "runtime" ], "type": "string" }, "cause": { "description": "Why, where it is knowable.", "type": "string" }, "details": { "description": "Evidence. `data_quality` findings carry `subject` naming what in the data is at fault; `configuration` findings carry none, because there is no data to point at (\u00a73). The kinds with a typed evidence builder have a contract shape here \u2014 `unmatched_join_keys` is `subject.{table, keys}`. `documentation` is a repair guide: `url` opens it for a person; with a `node_type`, `describe` (kind node_type) with `section` = `label` reads it.", "properties": { "subject": { "description": "Where the finding lives \u2014 \u00a74's closed list of refs, and it is a **list** because every emitter and renderer can name multiple locations. At least one locator field per ref; `source_file` (the uploaded file a row came from) and `source` (the record's own semantic origin) are provenance and neither substitutes for the other. Lists truncate at 100 entries with the true count carried alongside. Absent on `configuration` and `runtime` findings, which have no data to point at.", "items": { "additionalProperties": false, "dependentRequired": { "columns": [ "column_count" ], "keys": [ "key_count" ], "rows": [ "row_count" ] }, "minProperties": 1, "properties": { "column_count": { "description": "How many columns the finding names; `columns` lists at most the first 100. Written whenever `columns` is.", "minimum": 0, "type": "integer" }, "columns": { "description": "Columns by 1-based position, for findings raised before a column has a usable name.", "items": { "type": "integer" }, "type": "array" }, "fields": { "description": "Columns by name.", "items": { "type": "string" }, "type": "array" }, "key_count": { "description": "How many offending values the finding names; `keys` lists at most the first 100. Written whenever `keys` is.", "minimum": 0, "type": "integer" }, "keys": { "description": "The offending *values*, when the finding is about values rather than positions.", "items": { "type": "string" }, "type": "array" }, "row_count": { "description": "How many rows the finding names, unreadable row numbers included; `rows` lists at most the first 100. Written whenever `rows` is.", "minimum": 0, "type": "integer" }, "rows": { "description": "1-based source row numbers.", "items": { "type": "integer" }, "type": "array" }, "source": { "description": "The record's own semantic origin.", "type": "string" }, "source_file": { "description": "The uploaded file a row came from.", "type": "string" }, "table": { "description": "The collection: a scenario table, a record type, or an upstream input's label.", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "kind": { "description": "A core or installed package diagnostic identifier.", "type": [ "string", "null" ] }, "label": { "description": "Display label from the emitting diagnostic declaration.", "type": [ "string", "null" ] }, "message": { "description": "What is wrong.", "type": "string" }, "node_id": { "description": "The workflow node identifier for a graph-shaped finding. Matches the node.id in the workflow document so the app or agent can locate the affected node. Omitted when the finding does not refer to a node.", "type": "string" }, "repair_guidance": { "description": "Repair guidance from the emitting package or core declaration.", "type": [ "string", "null" ] }, "severity": { "enum": [ "error", "warning", "info" ], "type": "string" }, "suggestions": { "description": "How to repair it.", "items": { "type": "string" }, "type": "array" } }, "required": [ "kind", "severity", "category", "message" ], "type": "object" }, "ExecutionDataSource": { "description": "A file this run saved, and the data source it joined.", "properties": { "id": { "description": "The data source. Pass as data_source_id to read the saved table.", "format": "uuid", "title": "Data Source ID", "type": "string" }, "name": { "description": "The data source's name.", "title": "Name", "type": "string" }, "url": { "description": "The data source's page. Hand this to the person, and report the data source by its name with that name as the link \u2014 the id is for your next call and is not something to put in front of a reader. The address is whole (scheme, host and path) and the product composed it: never build one yourself out of an id and a host, and if this field is absent, say what was done and name the data source without a link.", "type": "string" }, "fileId": { "description": "The file this run saved, its latest unless a later run added another.", "format": "uuid", "type": "string" }, "fileName": { "description": "That file's name, `name [version N].ext`.", "type": "string" } }, "required": [ "id", "name", "fileId", "fileName" ], "title": "ExecutionDataSource", "type": "object" }, "ExecutionScenario": { "description": "A scenario this run published.", "properties": { "id": { "description": "Pass as `scenario_id`, or in a dashboard's `scenario_ids`.", "format": "uuid", "title": "Scenario ID", "type": "string" }, "name": { "description": "The saved name, including any suffix assigned on repeat runs. It tells a baseline from a variant.", "title": "Name", "type": "string" }, "url": { "description": "This scenario, open in the Viewer. Hand this to the person, and report the scenario by its name with that name as the link \u2014 the id is for your next call and is not something to put in front of a reader. The address is whole (scheme, host and path) and the product composed it: never build one yourself out of an id and a host, and if this field is absent, say what was done and name the scenario without a link.", "type": "string" } }, "required": [ "id", "name" ], "title": "ExecutionScenario", "type": "object" }, "ExecutionStatus": { "enum": [ "pending", "running", "completed", "failed", "cancelled" ], "title": "ExecutionStatus", "type": "string" }, "FileFields": { "description": "What every file of a data source carries, whoever wrote it.", "properties": { "columns": { "description": "Column names from the file", "items": { "type": "string" }, "title": "Columns", "type": "array" }, "dataSourceId": { "description": "The data source this file belongs to.", "format": "uuid", "type": "string" }, "id": { "description": "The file id (UUID)", "title": "Id", "type": "string" }, "isLatest": { "description": "Whether this is the data source's latest file, the one a workflow reading the latest reads.", "type": "boolean" }, "kind": { "$ref": "#/components/schemas/DataSourceKind", "description": "Derived from ``type`` \u2014 a stored copy could contradict the file.", "readOnly": true, "title": "Kind" }, "name": { "description": "The file's name. It is never given to another file", "title": "Name", "type": "string" }, "number": { "description": "The file's place in its data source, counted from 1 in the order files arrived.", "minimum": 1, "type": "integer" }, "origin": { "$ref": "#/components/schemas/DataSourceOrigin", "default": "upload", "description": "How this data source was created.", "title": "Origin" }, "rowCount": { "description": "Total table rows; zero for a document", "title": "Row Count", "type": "integer" }, "sha256": { "description": "Hex SHA-256 of the stored file's bytes, hashed as they were received \u2014 compare it against the file on disk to prove the upload arrived unaltered.", "title": "Sha256", "type": "string" }, "sizeBytes": { "description": "File size in bytes", "title": "Size Bytes", "type": "integer" }, "type": { "$ref": "#/components/schemas/DataSourceType", "description": "File type", "title": "Type" }, "updatedAt": { "description": "When the file record last changed", "format": "date-time", "title": "Updated At", "type": "string" }, "uploadedAt": { "description": "When the file arrived", "format": "date-time", "title": "Uploaded At", "type": "string" }, "uploadedBy": { "description": "The user who uploaded the file or requested the run that wrote it.", "title": "Uploaded By", "type": "string" }, "url": { "description": "The page of the data source this file belongs to. Hand this to the person, and report the data source by its name with that name as the link \u2014 the id is for your next call and is not something to put in front of a reader. The address is whole (scheme, host and path) and the product composed it: never build one yourself out of an id and a host, and if this field is absent, say what was done and name the data source without a link.", "type": "string" }, "warnings": { "description": "What reading the uploaded file could not do faithfully: a header that merged or was blank, a workbook sheet that was not read, numbers whose decimal mark the file leaves open. Absent when there is nothing to say. Tell the person before they build on this source.", "items": { "$ref": "#/components/schemas/UploadDiagnostic" }, "title": "Warnings", "type": "array" } }, "required": [ "id", "name", "type", "sizeBytes", "columns", "rowCount", "uploadedAt", "updatedAt", "kind", "sha256", "uploadedBy", "dataSourceId", "number", "isLatest" ], "type": "object" }, "FileResponse": { "allOf": [ { "$ref": "#/components/schemas/FileFields" }, { "properties": { "originExecutionId": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "The run that wrote this source, if created by a workflow.", "title": "Origin Execution ID" }, "originNodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The Save Table node that wrote this source.", "title": "Origin Node ID" }, "restoredFromNumber": { "description": "Present on a file restored from an earlier one: that file's number.", "minimum": 1, "type": "integer" } }, "type": "object" } ], "description": "One file of a data source: bytes received once, under a name no other file in the project has.", "title": "FileResponse", "type": "object" }, "FindingCounts": { "description": "Findings per severity.", "properties": { "error": { "minimum": 0, "type": "integer" }, "info": { "minimum": 0, "type": "integer" }, "warning": { "minimum": 0, "type": "integer" } }, "required": [ "error", "warning", "info" ], "title": "FindingCounts", "type": "object" }, "NodeActivity": { "description": "The computation currently running inside a workflow node.", "properties": { "phase": { "title": "Phase", "type": "string" }, "message": { "title": "Message", "type": "string" }, "startedAt": { "format": "date-time", "title": "Started At", "type": "string" }, "timeLimitSeconds": { "title": "Time Limit Seconds", "type": "number" }, "finishedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "default": null, "title": "Finished At" }, "elapsedSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Elapsed Seconds" } }, "required": [ "phase", "message", "startedAt", "timeLimitSeconds" ], "title": "NodeActivity", "type": "object" }, "NodeProgress": { "description": "Progress of a single workflow node during execution", "properties": { "nodeId": { "title": "Node ID", "type": "string" }, "startedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "When the node was first reported running; absent for a node that has not started, and on runs from before it was recorded." }, "status": { "$ref": "#/components/schemas/ExecutionStatus", "title": "Status" }, "activity": { "anyOf": [ { "$ref": "#/components/schemas/NodeActivity" }, { "type": "null" } ], "default": null, "title": "Activity" } }, "required": [ "nodeId", "status" ], "title": "NodeProgress", "type": "object" }, "ProjectListItem": { "properties": { "briefVersion": { "description": "Raised by every change to the brief. Send it back as `baseBriefVersion` when you rewrite the brief.", "minimum": 1, "title": "Brief Version", "type": "integer" }, "createdAt": { "format": "date-time", "title": "Created At", "type": "string" }, "id": { "title": "Id", "type": "string" }, "isDemo": { "default": false, "title": "Is Demo", "type": "boolean" }, "name": { "title": "Name", "type": "string" }, "querySlug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The former query-link slug, present only when it identifies one project globally. Canonical browser paths use slug.", "title": "Query Slug" }, "resourceCounts": { "anyOf": [ { "$ref": "#/components/schemas/ResourceCounts" }, { "type": "null" } ], "title": "Resource Counts" }, "slug": { "title": "Slug", "type": "string" }, "summary": { "anyOf": [ { "maxLength": 280, "type": "string" }, { "type": "null" } ], "description": "The brief's opening paragraph, headings skipped, cut at a word and marked with an ellipsis past 280 characters; null when the brief has none.", "title": "Summary" }, "updatedAt": { "format": "date-time", "title": "Updated At", "type": "string" }, "uploadUrl": { "description": "The project's Data Sources page, where a person drops files into this project. When a file the person gave you cannot reach SCMotif through `upload` \u2014 you cannot compute its SHA-256 or send its bytes from where you run \u2014 hand the person this link and wait until `list` (kind data_source) shows the file; never copy a file's rows into a workflow instead. Whole and composed by the product, like `url`; absent when `url` is.", "type": "string" }, "url": { "description": "The project's own page, opened with that project selected. Hand this to the person, and report the project by its name with that name as the link \u2014 the id is for your next call and is not something to put in front of a reader. The address is whole (scheme, host and path) and the product composed it: never build one yourself out of an id and a host, and if this field is absent, say what was done and name the project without a link.", "type": "string" }, "userId": { "title": "User Id", "type": "string" } }, "required": [ "id", "slug", "userId", "name", "createdAt", "updatedAt", "briefVersion", "summary" ], "title": "ProjectListItem", "type": "object" }, "ResourceCounts": { "description": "Per-project counts of each resource kind.", "properties": { "dashboards": { "default": 0, "title": "Dashboards", "type": "integer" }, "dataSources": { "default": 0, "title": "Data Sources", "type": "integer" }, "scenarios": { "default": 0, "title": "Scenarios", "type": "integer" }, "workflows": { "default": 0, "title": "Workflows", "type": "integer" } }, "title": "ResourceCounts", "type": "object" }, "RunWaiting": { "description": "Why a run has not started yet. Present only while it is `pending`: a run the service has taken is no longer waiting for it.", "properties": { "aheadOwn": { "description": "How many of the runs ahead of this one belong to this same account. This is the half of the wait the caller can shorten, by cancelling one of their own.", "minimum": 0, "title": "Ahead Own", "type": "integer" }, "explanation": { "description": "Why this run is waiting, in one sentence, as the product says it. Say this to the user rather than composing your own: a queued run that says nothing is indistinguishable from a stuck one, and both surfaces state the wait the same way on purpose.", "title": "Explanation", "type": "string" }, "position": { "description": "This run's place in line for a solver slot, counting itself, so `1` is the run a freeing slot takes next. The service divides itself between accounts rather than starting arrivals in order, so this is not simply how long the run has been queued.", "minimum": 1, "title": "Position", "type": "integer" }, "slots": { "description": "How many solver slots could take this run at all. `0` means none can, and the run will be reported as failed rather than left waiting.", "minimum": 0, "title": "Slots", "type": "integer" } }, "required": [ "explanation", "position", "aheadOwn", "slots" ], "title": "RunWaiting", "type": "object" }, "ScenarioImportReady": { "allOf": [ { "$ref": "#/components/schemas/UploadSessionBase" }, { "properties": { "diagnostics": { "items": { "$ref": "#/components/schemas/UploadDiagnostic" }, "type": "array" }, "scenarioId": { "format": "uuid", "type": "string" }, "state": { "enum": [ "ready" ], "type": "string" } }, "required": [ "state", "diagnostics", "scenarioId" ], "type": "object" } ], "type": "object" }, "StorageUsage": { "description": "How much this account has stored and how much it may. One figure for the whole account, not per project: the limit spans them and survives deleting one. Both halves are counted \u2014 uploaded data sources and the result tables runs write \u2014 because both are stored.", "properties": { "limitBytes": { "description": "The ceiling for this account. A write that would cross it is refused with a `storage_limit_reached` diagnostic; nothing already stored is affected, and every read keeps working.", "title": "Limit Bytes", "type": "integer" }, "nearLimit": { "description": "Whether the account is close enough to its ceiling to say so. Tell the user when this is true \u2014 they cannot see it otherwise, and the alternative is finding out at a refusal.", "title": "Near Limit", "type": "boolean" }, "percentUsed": { "description": "`usedBytes` as a percentage of `limitBytes`, 0\u2013100.", "maximum": 100, "minimum": 0, "title": "Percent Used", "type": "integer" }, "remainingBytes": { "description": "What is left after stored bytes and active upload reservations, never below zero. A file larger than this will be refused.", "title": "Remaining Bytes", "type": "integer" }, "reservedBytes": { "description": "Bytes promised to active upload sessions but not yet represented by ready data sources. Reservations prevent concurrent large uploads from overcommitting the account.", "title": "Reserved Bytes", "type": "integer" }, "scenariosBytes": { "description": "The half stored as scenario result tables. Runs add to it, and deleting a scenario or its project takes it back.", "title": "Scenarios Bytes", "type": "integer" }, "uploadsBytes": { "description": "The half stored as uploaded data sources.", "title": "Uploads Bytes", "type": "integer" }, "usedBytes": { "description": "Bytes stored, both halves together. This is the number the limit is compared against.", "title": "Used Bytes", "type": "integer" } }, "required": [ "usedBytes", "limitBytes", "remainingBytes", "percentUsed", "nearLimit", "uploadsBytes", "scenariosBytes", "reservedBytes" ], "title": "StorageUsage", "type": "object" }, "UnfinishedUpload": { "description": "A file upload that holds its name in the project but is not a file yet.", "properties": { "confirmedBytes": { "description": "Bytes object storage has confirmed so far.", "minimum": 0, "type": "integer" }, "declaredSize": { "minimum": 1, "type": "integer" }, "expiresAt": { "description": "When a transfer that has not finished lets go of the name by itself. An upload whose file has arrived is being read and does not expire.", "format": "date-time", "type": "string" }, "id": { "description": "The upload_session_id to resume, read or cancel it by.", "format": "uuid", "type": "string" }, "name": { "type": "string" }, "state": { "description": "`created` or `uploading` while the transfer is unfinished, which `cancel` (kind upload_session) releases; `uploaded` or `ingesting` once the file has arrived and is being read.", "enum": [ "created", "uploading", "uploaded", "ingesting" ], "type": "string" }, "dataSourceId": { "description": "The data source the file is going into, when it is an existing one.", "format": "uuid", "type": "string" }, "newDataSourceName": { "description": "The name of the data source the file creates, when it is a new one.", "type": "string" } }, "required": [ "id", "name", "state", "declaredSize", "confirmedBytes", "expiresAt" ], "title": "UnfinishedUpload", "type": "object" }, "UploadBlankHeaderDiagnostic": { "additionalProperties": false, "description": "A ready upload's warning that one or more header cells were blank.", "properties": { "category": { "enum": [ "data_quality" ], "type": "string" }, "cause": { "type": "string" }, "details": { "additionalProperties": false, "properties": { "subject": { "items": { "additionalProperties": false, "properties": { "columns": { "items": { "type": "integer" }, "type": "array" }, "column_count": { "type": "integer" } }, "required": [ "columns", "column_count" ], "type": "object" }, "type": "array" } }, "required": [ "subject" ], "type": "object" }, "kind": { "enum": [ "blank_header" ], "type": "string" }, "message": { "type": "string" }, "node_id": { "enum": [ "file_upload" ], "type": "string" }, "severity": { "enum": [ "warning" ], "type": "string" }, "suggestions": { "items": { "type": "string" }, "type": "array" }, "label": { "type": "string" } }, "required": [ "kind", "severity", "category", "message", "cause", "suggestions", "node_id", "details", "label" ], "type": "object" }, "UploadConfigurationDiagnostic": { "additionalProperties": false, "description": "A rejected upload's actionable ingestion problem.", "properties": { "category": { "enum": [ "configuration", "runtime" ], "type": "string" }, "details": { "additionalProperties": false, "type": "object" }, "kind": { "enum": [ "data_source_name_used", "storage_limit_reached", "uploaded_bytes_mismatch", "uploaded_file_too_large", "uploaded_file_unreadable" ], "type": "string" }, "message": { "type": "string" }, "severity": { "enum": [ "error" ], "type": "string" }, "suggestions": { "items": { "type": "string" }, "type": "array" } }, "required": [ "kind", "severity", "category", "message", "suggestions", "details" ], "type": "object" }, "UploadDiagnostic": { "description": "One exact upload-parser warning shape.", "oneOf": [ { "$ref": "#/components/schemas/UploadBlankHeaderDiagnostic" }, { "$ref": "#/components/schemas/UploadHeaderCollapseDiagnostic" }, { "$ref": "#/components/schemas/UploadUnreadSheetsDiagnostic" }, { "$ref": "#/components/schemas/UploadUnsettledDecimalMarkDiagnostic" } ] }, "UploadHeaderCollapseDiagnostic": { "additionalProperties": false, "description": "A ready upload's warning that headers collapsed onto one normalized name.", "properties": { "category": { "enum": [ "data_quality" ], "type": "string" }, "cause": { "type": "string" }, "details": { "additionalProperties": false, "properties": { "collapsed": { "items": { "additionalProperties": false, "properties": { "column": { "type": "string" }, "headers": { "items": { "type": "string" }, "type": "array" } }, "required": [ "column", "headers" ], "type": "object" }, "type": "array" }, "subject": { "items": { "additionalProperties": false, "properties": { "fields": { "items": { "type": "string" }, "type": "array" } }, "required": [ "fields" ], "type": "object" }, "type": "array" } }, "required": [ "subject", "collapsed" ], "type": "object" }, "kind": { "enum": [ "header_collapse" ], "type": "string" }, "message": { "type": "string" }, "node_id": { "enum": [ "file_upload" ], "type": "string" }, "severity": { "enum": [ "warning" ], "type": "string" }, "suggestions": { "items": { "type": "string" }, "type": "array" }, "label": { "type": "string" } }, "required": [ "kind", "severity", "category", "message", "cause", "suggestions", "node_id", "details", "label" ], "type": "object" }, "UploadPartTarget": { "description": "A short-lived, capability-bearing HTTP target for one exact slice of the file. Repeating the same PUT safely replaces that part; callers must never construct or persist the URL.", "properties": { "expiresAt": { "format": "date-time", "type": "string" }, "headers": { "additionalProperties": { "type": "string" }, "description": "Headers for this PUT, keyed by name. Non-browser clients must send them, including User-Agent; browser clients retain their own User-Agent and send the remaining headers.", "type": "object" }, "partNumber": { "minimum": 1, "type": "integer" }, "url": { "description": "Absolute PUT URL composed by the product. It contains a short-lived capability, not durable storage credentials.", "type": "string" } }, "required": [ "partNumber", "expiresAt", "headers", "url" ], "title": "UploadPartTarget", "type": "object" }, "UploadSession": { "description": "The durable upload record, discriminated by state. Only the ready branch exposes a DataSource id; rejected and ready branches carry the exact diagnostics those states can produce.", "oneOf": [ { "$ref": "#/components/schemas/UploadSessionInProgress" }, { "$ref": "#/components/schemas/UploadSessionReady" }, { "$ref": "#/components/schemas/UploadSessionRejected" }, { "$ref": "#/components/schemas/UploadSessionExpired" }, { "$ref": "#/components/schemas/ScenarioImportReady" } ], "title": "UploadSession", "type": "object" }, "UploadSessionBase": { "description": "Fields every durable upload state returns.", "properties": { "confirmedBytes": { "minimum": 0, "type": "integer" }, "confirmedParts": { "minimum": 0, "type": "integer" }, "declaredSize": { "minimum": 1, "type": "integer" }, "expiresAt": { "description": "When an incomplete session expires and releases its reservation.", "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "name": { "type": "string", "description": "The file's name." }, "partSize": { "description": "Bytes in every part except the final part, which contains the remainder.", "type": "integer" }, "projectId": { "format": "uuid", "type": "string" }, "sha256": { "pattern": "^[0-9a-f]{64}$", "type": "string" }, "storage": { "$ref": "#/components/schemas/StorageUsage" }, "targets": { "description": "At most the next bounded batch of missing part targets. Empty while ingesting or terminal; call resume again after sending a full batch.", "items": { "$ref": "#/components/schemas/UploadPartTarget" }, "type": "array" }, "totalParts": { "minimum": 1, "type": "integer" } }, "required": [ "id", "projectId", "name", "declaredSize", "sha256", "partSize", "totalParts", "confirmedParts", "confirmedBytes", "expiresAt", "targets", "storage" ], "type": "object" }, "UploadSessionExpired": { "allOf": [ { "$ref": "#/components/schemas/UploadSessionBase" }, { "properties": { "diagnostics": { "maxItems": 0, "type": "array" }, "state": { "enum": [ "expired" ], "type": "string" } }, "required": [ "state", "diagnostics" ], "type": "object" } ], "type": "object" }, "UploadSessionInProgress": { "allOf": [ { "$ref": "#/components/schemas/UploadSessionBase" }, { "properties": { "diagnostics": { "maxItems": 0, "type": "array" }, "state": { "enum": [ "created", "uploading", "uploaded", "ingesting" ], "type": "string" } }, "required": [ "state", "diagnostics" ], "type": "object" } ], "type": "object" }, "UploadSessionReady": { "allOf": [ { "$ref": "#/components/schemas/UploadSessionBase" }, { "properties": { "dataSourceId": { "description": "The data source the file joined.", "format": "uuid", "type": "string" }, "diagnostics": { "items": { "$ref": "#/components/schemas/UploadDiagnostic" }, "type": "array" }, "state": { "enum": [ "ready" ], "type": "string" }, "fileId": { "description": "The file this upload published.", "format": "uuid", "type": "string" } }, "required": [ "state", "diagnostics", "dataSourceId", "fileId" ], "type": "object" } ], "type": "object" }, "UploadSessionRejected": { "allOf": [ { "$ref": "#/components/schemas/UploadSessionBase" }, { "properties": { "diagnostics": { "items": { "$ref": "#/components/schemas/UploadConfigurationDiagnostic" }, "minItems": 1, "type": "array" }, "state": { "enum": [ "rejected" ], "type": "string" } }, "required": [ "state", "diagnostics" ], "type": "object" } ], "type": "object" }, "UploadUnreadSheetsDiagnostic": { "additionalProperties": false, "description": "A ready upload's warning that the workbook holds values on sheets the data source does not: `details.sheet` is the sheet read, and each `details.subject` entry's `table` names a sheet that was not read.", "properties": { "category": { "enum": [ "data_quality" ], "type": "string" }, "cause": { "type": "string" }, "details": { "additionalProperties": false, "properties": { "sheet": { "type": "string" }, "subject": { "items": { "additionalProperties": false, "properties": { "table": { "type": "string" } }, "required": [ "table" ], "type": "object" }, "type": "array" } }, "required": [ "subject", "sheet" ], "type": "object" }, "kind": { "enum": [ "unread_sheets" ], "type": "string" }, "message": { "type": "string" }, "node_id": { "enum": [ "file_upload" ], "type": "string" }, "severity": { "enum": [ "warning" ], "type": "string" }, "suggestions": { "items": { "type": "string" }, "type": "array" }, "label": { "type": "string" } }, "required": [ "kind", "severity", "category", "message", "cause", "suggestions", "node_id", "details", "label" ], "type": "object" }, "UploadUnsettledDecimalMarkDiagnostic": { "additionalProperties": false, "description": "A ready upload's warning that a ';'-separated file's numbers do not settle whether ',' marks decimals, so they were kept as written: `details.value` is one such cell, in the column `details.subject[0].fields` names.", "properties": { "category": { "enum": [ "data_quality" ], "type": "string" }, "cause": { "type": "string" }, "details": { "additionalProperties": false, "properties": { "subject": { "items": { "additionalProperties": false, "properties": { "fields": { "items": { "type": "string" }, "type": "array" } }, "required": [ "fields" ], "type": "object" }, "type": "array" }, "value": { "type": "string" } }, "required": [ "subject", "value" ], "type": "object" }, "kind": { "enum": [ "unsettled_decimal_mark" ], "type": "string" }, "message": { "type": "string" }, "node_id": { "enum": [ "file_upload" ], "type": "string" }, "severity": { "enum": [ "warning" ], "type": "string" }, "suggestions": { "items": { "type": "string" }, "type": "array" }, "label": { "type": "string" } }, "required": [ "kind", "severity", "category", "message", "cause", "suggestions", "node_id", "details", "label" ], "type": "object" }, "WorkflowExecutionResponse": { "description": "Response model for workflow execution", "properties": { "executionId": { "description": "This run's execution id. Pass it as `execution_id` to `get` (kind execution), `cancel` (kind execution) and `list_execution_diagnostics`.", "title": "Execution ID", "type": "string" }, "status": { "$ref": "#/components/schemas/ExecutionStatus", "title": "Status" }, "storage": { "allOf": [ { "$ref": "#/components/schemas/StorageUsage" } ], "description": "The account's storage when this run was enqueued. Poll `get` (kind execution) for the post-publication figure.", "title": "Storage" }, "url": { "description": "This run's page, under the workflow it is a run of. Hand this to the person, and report the run by its name with that name as the link \u2014 the id is for your next call and is not something to put in front of a reader. The address is whole (scheme, host and path) and the product composed it: never build one yourself out of an id and a host, and if this field is absent, say what was done and name the run without a link.", "type": "string" }, "workflowId": { "title": "Workflow ID", "type": "string" } }, "required": [ "status", "workflowId", "storage", "executionId" ], "title": "WorkflowExecutionResponse", "type": "object" }, "WorkflowExecutionStatus": { "description": "Status of a workflow execution", "properties": { "completedAt": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Completed At" }, "dataSources": { "description": "Every data source this run wrote, identified without a project-wide list or a name guess.", "items": { "$ref": "#/components/schemas/ExecutionDataSource" }, "title": "Data Sources", "type": "array" }, "executionId": { "description": "This run's execution id. Pass it as `execution_id` to `get` (kind execution), `cancel` (kind execution) and `list_execution_diagnostics`.", "title": "Execution ID", "type": "string" }, "findingCounts": { "allOf": [ { "$ref": "#/components/schemas/FindingCounts" } ], "description": "How many findings this run filed, per severity. `list_execution_diagnostics` reads them, a page at a time and narrowed by `severity` if asked.", "title": "Finding Counts" }, "firstFinding": { "anyOf": [ { "$ref": "#/components/schemas/Diagnostic" }, { "type": "null" } ], "description": "The run's first error, or its first finding of any severity when it filed no error; null when it filed none. The rest are in `list_execution_diagnostics`.", "title": "First Finding" }, "nodeProgress": { "description": "The durable progress last reported by the currently fenced execution attempt.", "items": { "$ref": "#/components/schemas/NodeProgress" }, "title": "Node Progress", "type": "array" }, "reproductionManifest": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "description": "The immutable inputs, build, packages and effective solver configuration recorded for this run. Present only when `include_provenance` is true; null for runs created before provenance manifests were recorded." }, "scenarios": { "description": "Every scenario this run published, in the order it published them, each with its name and page. `get` (kind scenario) reads one scenario's whole record.", "items": { "$ref": "#/components/schemas/ExecutionScenario" }, "title": "Scenarios", "type": "array" }, "startedAt": { "format": "date-time", "title": "Started At", "type": "string" }, "status": { "$ref": "#/components/schemas/ExecutionStatus", "title": "Status" }, "storage": { "allOf": [ { "$ref": "#/components/schemas/StorageUsage" } ], "description": "The account's storage at this poll. After completion this includes the run's published result tables; tell the user when `nearLimit` is true.", "title": "Storage" }, "url": { "description": "This run's page, under the workflow it is a run of. Hand this to the person, and report the run by its name with that name as the link \u2014 the id is for your next call and is not something to put in front of a reader. The address is whole (scheme, host and path) and the product composed it: never build one yourself out of an id and a host, and if this field is absent, say what was done and name the run without a link.", "type": "string" }, "waiting": { "anyOf": [ { "$ref": "#/components/schemas/RunWaiting" }, { "type": "null" } ], "description": "Why this run has not started, while it is still `pending`; null once it has, or once it is over. Tell the user what it says \u2014 a run reported only as pending gives them no way to tell a busy service from a stuck one.", "title": "Waiting" }, "workflowArchived": { "description": "Whether the source workflow is archived and unavailable to Run again.", "type": "boolean" }, "workflowId": { "title": "Workflow ID", "type": "string" }, "workflowName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The workflow name captured when this run was accepted. Null for runs created before execution snapshots were recorded." }, "workflowSnapshot": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "description": "The immutable accepted workflow document dispatched for this run, including its canvas layout. Present only when `include_provenance` is true; null for older runs whose accepted document cannot be reconstructed truthfully." }, "dashboardRefresh": { "anyOf": [ { "$ref": "#/components/schemas/DashboardRefreshDiscovery" }, { "type": "null" } ] } }, "required": [ "workflowId", "workflowName", "workflowArchived", "status", "startedAt", "storage", "waiting", "executionId", "dataSources", "scenarios", "findingCounts", "firstFinding" ], "title": "WorkflowExecutionStatus", "type": "object" }, "WorkflowListResponse": { "description": "Lightweight response model for workflow list (no full node/edge arrays)", "properties": { "createdAt": { "format": "date-time", "title": "Created At", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "edgeCount": { "title": "Edge Count", "type": "integer" }, "id": { "title": "Id", "type": "string" }, "name": { "title": "Name", "type": "string" }, "nodeCount": { "title": "Node Count", "type": "integer" }, "updatedAt": { "format": "date-time", "title": "Updated At", "type": "string" }, "url": { "description": "This workflow's page, showing the graph as it now stands. Hand this to the person, and report the workflow by its name with that name as the link \u2014 the id is for your next call and is not something to put in front of a reader. The address is whole (scheme, host and path) and the product composed it: never build one yourself out of an id and a host, and if this field is absent, say what was done and name the workflow without a link.", "type": "string" }, "userId": { "title": "User ID", "type": "string" } }, "required": [ "id", "userId", "name", "nodeCount", "edgeCount", "createdAt", "updatedAt" ], "title": "WorkflowListResponse", "type": "object" } }, "responses": { "Unauthorized": { "description": "No integration key was sent, or the key was revoked, replaced by a rotation, or never issued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ReadOnlyKey": { "description": "The key may only read and download, and this operation changes data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Nothing this key reaches has that id. A project outside the key's projects answers exactly as one that does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unprocessable": { "description": "An input is missing or cannot be read, or the operation refused the request and says why.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/Refusal" } ] } } } } }, "securitySchemes": { "integrationKey": { "type": "http", "scheme": "bearer", "description": "An integration key from Settings." } } }, "security": [ { "integrationKey": [] } ] }