AimableDocs
DocsAPI Reference

Collection Connectors

Collection Connectors

Collection Connectors in the Aimable Platform API allow you to link external data sources (like Google Drive, Slack, GitHub, etc.) to a collection in a space. They enable automated syncing of content such as files, messages, or repositories into your Aimable workspace. Each connector is tied to a specific provider (via provider_slug) and includes authentication credentials, sync configuration, and status tracking.

Connectors are essential for keeping your collections up-to-date with real-time data from third-party services. You can manage their scope, trigger or cancel syncs, and browse available resources before connecting.

Key Concepts

  • Connector: A configured link between a collection and an external service. Identified by connector_id.
  • Provider Slug: A string identifier for the service (e.g., google-drive, slack, github).
  • Scope Config: Defines what data to sync (e.g., specific folders, channels).
  • Sync: A single execution of data import. Can be triggered manually or run on a schedule.
  • Idempotency-Key: Required header when creating a connector to prevent duplicate creations.

Common Workflows

1. Create and Configure a Connector

First, create a connector with credentials and optional scope:

curl -X POST 'https://api-proxy/v1/spaces/7a5f3b1d-8e2c-4f1a-b9c0-1d2e3f4a5b6c/collections/9c8d7e6f-5a4b-3c2d-1e0f-2a3b4c5d6e7f/connectors' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Idempotency-Key: abc123xyz' \
  -H 'Content-Type: application/json' \
  -d '{
    "provider_slug": "google-drive",
    "credential": {
      "access_token": "ya29.a0AfB_...",
      "refresh_token": "1//04..."
    },
    "scope_config": {
      "folder_ids": ["1A2B3C4D", "5E6F7G8H"]
    }
  }'

Response (201 Created):

{
  "data": {
    "id": "cc123abc-4d5e-6f7g-8h9i-jklmnopqrst",
    "collection_id": "9c8d7e6f-5a4b-3c2d-1e0f-2a3b4c5d6e7f",
    "provider_slug": "google-drive",
    "principal_id": "user123",
    "scope_config": {
      "folder_ids": ["1A2B3C4D", "5E6F7G8H"]
    },
    "status": "active",
    "created_at": "2023-10-01T12:00:00Z",
    "updated_at": "2023-10-01T12:00:00Z"
  }
}

2. Browse Available Resources

Before syncing, explore what’s available via the connector:

curl 'https://api-proxy/v1/spaces/7a5f3b1d-8e2c-4f1a-b9c0-1d2e3f4a5b6c/collections/9c8d7e6f-5a4b-3c2d-1e0f-2a3b4c5d6e7f/connectors/cc123abc-4d5e-6f7g-8h9i-jklmnopqrst/browse?parent_id=1A2B3C4D' \
  -H 'Authorization: Bearer <your-access-token>'

Returns a list of subfolders, files, or channels depending on the provider.

3. Trigger a Manual Sync

Start a sync job immediately:

curl -X POST 'https://api-proxy/v1/spaces/7a5f3b1d-8e2c-4f1a-b9c0-1d2e3f4a5b6c/collections/9c8d7e6f-5a4b-3c2d-1e0f-2a3b4c5d6e7f/connectors/cc123abc-4d5e-6f7g-8h9i-jklmnopqrst/sync' \
  -H 'Authorization: Bearer <your-access-token>'

Response (202 Accepted):

{
  "data": {
    "id": "sync456def-7g8h-9i1j-2k3l-mnopqrstuvw",
    "collection_connector_id": "cc123abc-4d5e-6f7g-8h9i-jklmnopqrst",
    "status": "running",
    "records_fetched": 0,
    "metadata": {},
    "created_at": "2023-10-01T12:05:00Z"
  }
}

4. Monitor Sync Progress

Retrieve details about a specific sync:

curl 'https://api-proxy/v1/spaces/7a5f3b1d-8e2c-4f1a-b9c0-1d2e3f4a5b6c/collections/9c8d7e6f-5a4b-3c2d-1e0f-2a3b4c5d6e7f/connectors/cc123abc-4d5e-6f7g-8h9i-jklmnopqrst/sync/sync456def-7g8h-9i1j-2k3l-mnopqrstuvw' \
  -H 'Authorization: Bearer <your-access-token>'

Use this to track status, records_fetched, and completed_at.

5. List All Syncs

Paginate through historical syncs:

curl 'https://api-proxy/v1/spaces/7a5f3b1d-8e2c-4f1a-b9c0-1d2e3f4a5b6c/collections/9c8d7e6f-5a4b-3c2d-1e0f-2a3b4c5d6e7f/connectors/cc123abc-4d5e-6f7g-8h9i-jklmnopqrst/sync?limit=5' \
  -H 'Authorization: Bearer <your-access-token>'

Returns an array of sync jobs with metadata.

Authentication & Errors

All endpoints require authentication via:

Authorization: Bearer <your-access-token>

Alternatively, use an API key:

X-API-Key: your_api_key_here

Common Errors

  • 401 Unauthorized: Missing or invalid access token.
  • 403 Forbidden: Insufficient permissions for the space or collection.
  • 422 Unprocessable Entity: Invalid parameters or request body. Check detail.loc and detail.msg.

Example error:

{
  "detail": [
    {
      "loc": ["query", "limit"],
      "msg": "Input should be less than or equal to 100",
      "type": "less_than_equal"
    }
  ]
}

Summary

Use Collection Connectors to integrate external data sources securely and programmatically. Typical flow:

  1. POST /connectors → create connector
  2. GET /connectors/{id}/browse → explore available data
  3. POST /sync → trigger sync
  4. GET /sync/{id} → monitor progress

All operations support pagination and filtering, enabling scalable integration across large datasets.

Related Endpoints