Create and query connections

Create a connection to a database or app, query it over the API, and attach it to an agent.

Agent

(message with connection_ids)

metadata

Central Hub

(connector service)

encrypted

PostgreSQL

Snowflake

Slack, ...

Endpoints

• Every request sends X-Space-Slug. A bearer-only route answers an API key with 401 {"detail": "Not authenticated"}.
• Creating an OAuth connection needs a signed-in user for auth/init and auth/callback; every other route here takes an API key or a bearer token.
• credential-fields takes an auth_type from the connector's credential_details.auth_strategies[].type; another value returns 400 Invalid auth type '<value>'. Must be one of: ….

Supported connectors

The connector list returns category; a connection gets connector_type from its connector.

Credentials

Send every field as a string. Optional fields are in parentheses.

Create request fields

Query body and response

• SQL must be read-only: it starts with SELECT, WITH, SHOW, DESCRIBE or EXPLAIN and contains no write keyword.
• When the connection's semantic layer lists tables, only tables with is_included: true can be queried.
• timeout_seconds is optional: default 30, maximum 300.

Create a connection

1. Pick connector_key and auth_type from Supported connectors and fill credentials from Credentials.

2. Create it. Central Hub validates the fields, tests the connection and stores the credentials encrypted:

   curl -X POST "$CENTRAL_HUB_URL/api/v1/data-sources/connections/" \
     -H "X-API-Key: $ALO_API_KEY" \
     -H "X-Space-Slug: $WORKSPACE_SLUG" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Analytics DB",
       "connector_key": "postgresql",
       "auth_type": "basic",
       "credentials": {
         "host": "db.example.com",
         "port": "5432",
         "dbname": "analytics",
         "user": "readonly_user",
         "password": "…"
       }
     }'

3. Keep the id from the 201 response (abridged). Sensitive fields come back as [REDACTED]:

   {
     "id": 123,
     "name": "Analytics DB",
     "connector_key": "postgresql",
     "auth_type": "basic",
     "credentials": {"host": "db.example.com", "port": "5432", "dbname": "analytics", "user": "readonly_user", "password": "[REDACTED]"},
     "category": "data_source",
     "connector_type": "database",
     "scope_visibility": "private",
     "is_owner": true,
     "semantic_layer": {"tables": [], "relationships": [], "definitions": [], "kpis": [], "status": "generating", "generated_at": "2026-10-13T19:34:51.683117+00:00"}
   }

   A database connection with category data_source generates its semantic layer in the background.

Create an OAuth connection

Bearer only: run these steps as the signed-in user who will own the connection.

1. Start the flow with your redirect_uri. Put connector config in credentials when the connector needs it, such as Snowflake account, database and warehouse, or your own OAuth app's client_id and client_secret:

   curl -X POST "$CENTRAL_HUB_URL/api/v1/data-sources/connectors/google_drive/auth/init/" \
     -H "Authorization: Bearer $ALO_TOKEN" \
     -H "X-Space-Slug: $WORKSPACE_SLUG" \
     -H "Content-Type: application/json" \
     -d '{"redirect_uri": "https://your-app.example.com/oauth/callback"}'

2. Keep both values of the response, {"auth_url": "…", "state": "…"}, and send the user to auth_url.

3. When the provider redirects back, exchange its code with the state from step 2, within 15 minutes and as the same user:

   curl -X POST "$CENTRAL_HUB_URL/api/v1/data-sources/connectors/google_drive/auth/callback/" \
     -H "Authorization: Bearer $ALO_TOKEN" \
     -H "X-Space-Slug: $WORKSPACE_SLUG" \
     -H "Content-Type: application/json" \
     -d '{"code": "<code from the redirect>", "state": "<state from init>"}'

4. Create the connection with "auth_type": "oauth2" and the returned object as credentials.

Other members of a space OAuth connection connect their own account.

List connections

1. Filter with any of category (data_source, app), connector_type (database, file, folder, app) and connector_key. With connector_key, action_key keeps only connections whose granted OAuth scopes cover that action:

   curl "$CENTRAL_HUB_URL/api/v1/data-sources/connections/?category=data_source&connector_type=database" \
     -H "X-API-Key: $ALO_API_KEY" \
     -H "X-Space-Slug: $WORKSPACE_SLUG"

2. Read the array: your private connections first, then the workspace's, each sorted by name.

Read, edit or delete a connection

• Only the connection's owner can edit or delete it.
• scope_visibility: "space" needs a second workspace member.

Run a query

1. Read the connection's query format and actions; instructions_prompt is guidance for the query, not a request body:

   curl "$CENTRAL_HUB_URL/api/v1/data-sources/connections/123/instructions/" \
     -H "X-API-Key: $ALO_API_KEY" \
     -H "X-Space-Slug: $WORKSPACE_SLUG"

2. Send the query, with no trailing slash:

   curl -X POST "$CENTRAL_HUB_URL/api/v1/data-sources/connections/123/query" \
     -H "X-API-Key: $ALO_API_KEY" \
     -H "X-Space-Slug: $WORKSPACE_SLUG" \
     -H "Content-Type: application/json" \
     -d '{"query": {"sql": "SELECT id, cust_id, amount FROM tbl_ord ORDER BY id LIMIT 2"}, "timeout_seconds": 30}'

   {
     "columns": ["id", "cust_id", "amount"],
     "rows": [
       {"id": 1, "cust_id": 1, "amount": "120.50"},
       {"id": 2, "cust_id": 2, "amount": "80.00"}
     ],
     "row_count": 2,
     "summary": "Query returned 2 row(s)."
   }

3. For an action, put its key in operation and its params beside it. Slack list_channels:

   {"query": {"operation": "list_channels", "limit": 20}}

   The response is {"success": true, "data": {"channels": [{"id": "…", "name": "…", "is_private": false, "num_members": 12, "topic": "…", "purpose": "…"}]}}.

Retrieve metadata

1. Send POST …/connections/{connection_id}/metadata, with no trailing slash and an optional timeout_seconds:

   curl -X POST "$CENTRAL_HUB_URL/api/v1/data-sources/connections/123/metadata" \
     -H "X-API-Key: $ALO_API_KEY" \
     -H "X-Space-Slug: $WORKSPACE_SLUG" \
     -H "Content-Type: application/json" \
     -d '{"timeout_seconds": 30}'

2. Read tables[]: each has name (schema-qualified for PostgreSQL, e.g. public.tbl_ord), columns[] with name, data_type and nullable, primary_key and foreign_keys. unavailable lists configured items your credentials could not read.

Connect your account to a shared OAuth connection

A space OAuth connection uses each member's own tokens. Until you connect, /query and /metadata return 428:

{
  "detail": "Per-user authentication required for connection 42 (snowflake): not_connected",
  "code": "PER_USER_AUTH_REQUIRED",
  "reason": "not_connected",
  "connector_key": "snowflake",
  "connection_id": 42
}

reason is not_connected or needs_reauth (your token expired). GET …/connections/{connection_id}/auth-status/ reports it as authenticated: false.

1. Start the flow; it needs the Create connections permission (connection:create):

   curl -X POST "$CENTRAL_HUB_URL/api/v1/data-sources/connections/42/authenticate/init/" \
     -H "X-API-Key: $ALO_API_KEY" \
     -H "X-Space-Slug: $WORKSPACE_SLUG" \
     -H "Content-Type: application/json" \
     -d '{"redirect_uri": "https://your-app.example.com/oauth/callback"}'

2. Keep state and send the user to auth_url.

3. Within 15 minutes and as the same user, send POST …/connections/42/authenticate/callback/ with {"code": "…", "state": "…"}. The response is the connection with user_authenticated: true.

Attach a connection to an agent

Add the connection ID to the agent's enabled_connection_ids: send PATCH /api/v1/agents-v2/agents/{agent_id}/ with {"enabled_connection_ids": [123]}, or set it in the bundle's agent.yaml and upload the bundle, as in Create and configure an agent:

enabled_connection_ids: [123]

Troubleshooting