Data, Files, and Connectors API¶

The data APIs cover two related layers: Catalog stores governed AI Studio assets, while connectors and transfer tasks move data between external systems and Catalog targets. A connector that validates successfully has not yet imported data.

Catalog hierarchy¶

Catalog resources follow the hierarchy catalog → database → volume/table → folder/file. Most Catalog routes use POST even for reads because identifiers, paths, pagination, or filters are carried in a JSON body.

Route family	Supported operations
`/newmoi/catalog`	Health, tree, list, create, info, update, reference list, and delete
`/newmoi/catalog/database`	List, children, table leaves, create, info, update, references, and delete
`/newmoi/catalog/volume`	Create, info, update, full path, workflow references, and delete
`/newmoi/catalog/table`	Create, info, data, preview, overview, load, download, truncate, references, and delete
`/newmoi/catalog/folder`	Create, update, clean, reference list, and delete
`/newmoi/catalog/file`	List, create, upload, info, update, preview, download, trigger workflow, and delete
`/newmoi/catalog/tag`	List, create, update, and delete

Before deleting, truncating, or cleaning an object, read its reference list and inspect downstream workflows, knowledge sources, exports, and lineage. A successful upload may still require parsing or a workflow before the file becomes a usable downstream asset.

File responses vary by operation. /newmoi/catalog/file/preview_link returns a preview location, while preview-stream and download routes can return streams. /newmoi/catalog/data-assets/:id and /newmoi/catalog/file-artifacts/:file_id resolve governed asset and artifact metadata.

Connector lifecycle¶

Method and route	Purpose
`GET /newmoi/connectors/list`	List connectors in the workspace
`POST /newmoi/connectors/get`	Read one connector
`POST /newmoi/connectors`	Create a connector
`PUT /newmoi/connectors/:id`	Update a connector
`DELETE /newmoi/connectors/:id`	Delete a connector
`POST /newmoi/connectors/validate`	Test networking and credentials without importing data

Available source types and their configuration fields are deployment-defined. The registered API families include local files, structured source discovery, database/schema/table browsing, MatrixOne target browsing, column mapping, and file preview/download/stream operations. Never copy connector passwords into logs or reuse a browser-only secret in a server integration.

Validate from the deployment’s network path. A test from the developer laptop does not prove that worker nodes can resolve DNS, reach the port, negotiate TLS, or pass an allowlist.

Import and export tasks¶

Import tasks use /newmoi/task; their contract covers create, list, detail, update, files, runs, pause, resume, retry selected files, and delete. Export tasks use /newmoi/export/task; they cover create, list, info, files, state, rerun, and delete.

A robust transfer flow is:

Create and validate the connector.
Browse the source schema or files and resolve the Catalog target.
Submit a task using the exact deployed schema.
Retain the task ID and poll its detail, runs, files, or state.
At terminal success, verify the target object and row/file counts. At failure, retain the task ID, failed stage, and failed-file list.

Do not automatically retry an entire import when only selected files failed; use the file retry operation when supported. Before retrying an export, check whether the destination already contains a partial object and apply the configured overwrite policy.

For queryable table metadata and SQL execution, continue to SQL. For artifact dependencies, see Workflows and lineage.