Datasource API

The datasource API stores complete connection objects in Querio's encrypted database. It does not require datasource TOML files or a notebook session.

Authentication and workspace

Use an authenticated request with the Querio-Workspace-Id header. Programmatic access tokens need workspaceRuntime:connect and datasource:read scopes. Scopes do not override workspace membership or datasource sharing permissions. Browser mutations also enforce same-origin authentication.

The API uses existing datasource permissions, including the existing rule that datasource read access governs connection replacement and deletion. It does not introduce separate mutation permissions.

Endpoints

Create and replace

Create a datasource with a slug and a complete connection:

{
  "slug": "warehouse",
  "name": "Warehouse",
  "connection": {
    "kind": "postgres",
    "connection_string": "postgresql://USER:PASSWORD@HOST/DATABASE",
    "schema": "public"
  },
  "testConnection": true
}

name is optional. testConnection defaults to false; set it to true to test before saving. Failed tests do not save or replace credentials. Store request bodies in a protected file or supply them through stdin rather than putting credentials in shell history.

Slugs are case-sensitive, up to 120 characters, and start with a letter or digit. They can contain letters, digits, dots, underscores, and hyphens.

Creation rejects an existing slug with 409. Replacement uses the slug in the URL and accepts connection, name, and testConnection, but not slug. It requires an existing datasource and the complete connection, not a partial credential patch. Omitting name preserves the display name; passing null clears it. Concurrent changes detected during mutation return 409. Replacement does not rotate credentials at the database provider.

Use the schema endpoint for connector-specific fields. It is generated from the same connection models used by execution and forms. Unknown fields and incomplete connections are rejected.

No credential readback

Create, replace, list, and detail responses expose only metadata:

{
  "id": "sec_example",
  "slug": "warehouse",
  "kind": "postgres",
  "name": "Warehouse",
  "revision": 1,
  "configured": true,
  "embedded": false
}

Stored credentials are never returned by these endpoints. There is no plaintext value endpoint. configured means a stored connection exists, not that its last connectivity test passed. Credential-bearing request values and native driver error messages are not echoed by connection-test responses.

Connection tests

Test an unsaved connection by posting { "connection": { ... } } to /api/v3/datasource-connections/test. This does not create a datasource. Testing a saved datasource requires no request body.

Successful tests return HTTP 200 with ok, message, and elapsedMs. A completed unsuccessful probe returns HTTP 400 with ok: false and a generic message. Upstream request failures can return other error statuses.

Tests use Querio's gateway and its network access to the database. For remote databases, a saved-connection test does not require a provisioned workspace directory. Files datasources still require their workspace files.

Deletion keeps files

Deleting a datasource removes its encrypted connection versions and exact resource grants. It does not delete catalogs, datasource context, uploaded data, memory, or any other workspace files. Files-datasource data directories are also retained.

Deletion returns { "slug": "warehouse", "deleted": true }. A missing datasource returns 404. The name can be reused, creating a new connection identity at revision 1. Recreating a connection does not erase retained files or restore its deleted grants.

Replaced routes

The following public routes are removed, rather than retained as aliases:

Creation and replacement no longer scaffold catalog directories or accept introspect and parallel. Catalog introspection remains a separate operation through the existing catalog API. Uploads, sharing, demo seeding, generic secrets, notebook execution, and Files APIs remain separate.