List Storage Connections

curl --request POST \
  --url https://api.mixpeek.com/v1/organizations/connections/list \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "provider_type": "google_drive",
  "status": "PENDING",
  "is_active": true
}
'

{
  "results": [
    {
      "internal_id": "<string>",
      "provider_type": "google_drive",
      "provider_config": {
        "credentials": {
          "client_email": "[email protected]",
          "client_id": "123456789012345678901",
          "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
          "private_key_id": "a1b2c3d4e5f6...",
          "project_id": "mixpeek-prod-456",
          "type": "service_account"
        },
        "description": "Service account accessing shared drive",
        "provider_type": "google_drive",
        "shared_drive_id": "0AH-Xabc123def456"
      },
      "name": "<string>",
      "created_by_user_id": "<string>",
      "connection_id": "<string>",
      "description": "Shared drive for marketing team assets and campaign materials",
      "status": "ACTIVE",
      "is_active": true,
      "last_used_at": "2023-11-07T05:31:56Z",
      "last_error": "Authentication failed: Invalid credentials",
      "consecutive_failures": 0,
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "metadata": {}
    }
  ],
  "pagination": {
    "total": 123,
    "page": 123,
    "page_size": 123,
    "total_pages": 123,
    "next_page": "<string>",
    "previous_page": "<string>"
  },
  "total": 1
}

Connections

List Storage Connections

List storage connections for the authenticated organization.

Returns paginated results with optional filters for provider type, status, and active flag. Results are sorted by creation date (newest first).

Use Cases:

List all active Google Drive connections
Find failed connections that need attention
Filter by provider type for sync configuration

Example:

curl -X POST "http://localhost:8000/v1/organizations/connections/list" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_type": "google_drive",
    "is_active": true
  }'

POST

organizations

connections

list

List Storage Connections

curl --request POST \
  --url https://api.mixpeek.com/v1/organizations/connections/list \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "provider_type": "google_drive",
  "status": "PENDING",
  "is_active": true
}
'

{
  "results": [
    {
      "internal_id": "<string>",
      "provider_type": "google_drive",
      "provider_config": {
        "credentials": {
          "client_email": "[email protected]",
          "client_id": "123456789012345678901",
          "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
          "private_key_id": "a1b2c3d4e5f6...",
          "project_id": "mixpeek-prod-456",
          "type": "service_account"
        },
        "description": "Service account accessing shared drive",
        "provider_type": "google_drive",
        "shared_drive_id": "0AH-Xabc123def456"
      },
      "name": "<string>",
      "created_by_user_id": "<string>",
      "connection_id": "<string>",
      "description": "Shared drive for marketing team assets and campaign materials",
      "status": "ACTIVE",
      "is_active": true,
      "last_used_at": "2023-11-07T05:31:56Z",
      "last_error": "Authentication failed: Invalid credentials",
      "consecutive_failures": 0,
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "metadata": {}
    }
  ],
  "pagination": {
    "total": 123,
    "page": 123,
    "page_size": 123,
    "total_pages": 123,
    "next_page": "<string>",
    "previous_page": "<string>"
  },
  "total": 1
}

Headers

Authorization

string

required

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

Query Parameters

limit

integer | null

offset

integer | null

Body

application/json

Request payload for listing storage connections with filters.

Use this to filter connections by provider type, status, or active flag. Results are paginated automatically.

Use Cases:

List all active Google Drive connections
Find failed connections that need attention
Filter by provider type for sync configuration

Examples:

# List all active Google Drive connections
{
    "provider_type": "google_drive",
    "is_active": True
}

# Find failed connections
{
    "status": "failed"
}

provider_type

enum<string> | null

OPTIONAL. Filter connections by provider type. Must be one of: google_drive, s3. If not provided, returns connections of all types.

Available options:

google_drive,

s3

Example:

"google_drive"

status

enum<string> | null

OPTIONAL. Filter connections by operational status. ACTIVE: Healthy and ready for use. SUSPENDED: Temporarily disabled. FAILED: Health checks failing. ARCHIVED: Permanently retired.

Available options:

PENDING,

IN_PROGRESS,

PROCESSING,

COMPLETED,

COMPLETED_WITH_ERRORS,

FAILED,

CANCELED,

UNKNOWN,

SKIPPED,

DRAFT,

ACTIVE,

ARCHIVED,

SUSPENDED

is_active

boolean | null

OPTIONAL. Filter by active flag. True: Returns only active connections (status=ACTIVE). False: Returns only inactive connections (SUSPENDED/FAILED/ARCHIVED). If not provided, returns connections of all active states.

Response

Successful Response

Response envelope for listing storage connections.

Contains paginated results and metadata about the listing operation.

results

StorageConnectionModel · object[]

required

List of storage connections matching the request filters. Results are paginated according to the pagination parameters. SECURITY: Sensitive credential fields are automatically redacted.

Show child attributes

results.internal_id

string

required

REQUIRED. Organization internal identifier for multi-tenancy scoping. All connection operations are scoped to this organization. Format: int_{24-character secure token}.

results.provider_type

enum<string>

required

REQUIRED. Storage provider implementation to use. Determines which client adapter is loaded for sync operations. Must be one of: google_drive, s3. See StorageProvider enum for full list.

Available options:

google_drive,

s3

results.provider_config

GoogleDriveConfig · object

required

REQUIRED. Provider-specific configuration payload including credentials. Type depends on provider_type (GoogleDriveConfig, S3Config, etc.). SECURITY: Sensitive credential fields are encrypted at rest via MongoDB client-side field level encryption (CSFLE). Credentials never appear in API responses or logs. See provider_configs.py for detailed schemas.

GoogleDriveConfig
S3Config
Provider Config

Show child attributes

results.provider_config.credentials

GoogleDriveServiceAccountCredentials · object

required

REQUIRED. Authentication credentials for Google Drive API access. Choose service_account for production (recommended) or oauth for personal access. The 'type' field determines which credential type is used.

GoogleDriveServiceAccountCredentials
GoogleDriveOAuthCredentials

Show child attributes

results.provider_config.credentials.project_id

string

required

REQUIRED. Google Cloud project ID where the service account was created. Found in the JSON key file as 'project_id'. Format: lowercase alphanumeric with hyphens (e.g., 'my-project-123').

results.provider_config.credentials.private_key_id

string

required

REQUIRED. Unique identifier for the private key. Found in the JSON key file as 'private_key_id'. Format: 40-character hexadecimal string.

results.provider_config.credentials.private_key

string

required

REQUIRED. PEM-encoded RSA private key for authentication. Found in the JSON key file as 'private_key'. SECURITY: This field is encrypted at rest. Never log or expose this value. Format: Must include BEGIN/END PRIVATE KEY markers.

results.provider_config.credentials.client_email

string

required

REQUIRED. Service account email address. Found in the JSON key file as 'client_email'. Share Drive files/folders with this email to grant access. Format: {account-name}@{project-id}.iam.gserviceaccount.com

results.provider_config.credentials.client_id

string

required

REQUIRED. Numeric service account identifier. Found in the JSON key file as 'client_id'. Format: 21-digit numeric string.

results.provider_config.credentials.type

string

default:service_account

Allowed value: "service_account"

results.provider_config.provider_type

string

default:google_drive

Allowed value: "google_drive"

results.provider_config.shared_drive_id

string | null

NOT REQUIRED. Google Workspace shared drive (Team Drive) identifier. When provided, sync operations are scoped to this shared drive only. When omitted, syncs from 'My Drive' of the authenticated account. Find ID: Open shared drive in browser, copy ID from URL. Format: 0A{alphanumeric-string}

Example:

"0AH-Xabc123def456"

results.provider_config.impersonate_user

string | null

NOT REQUIRED. Email address to impersonate when using service account credentials. Requires domain-wide delegation to be enabled for the service account. Used in G Suite environments to access files as a specific user. When omitted, uses the service account's own access. Format: Valid email address in the G Suite domain.

Example:

"[email protected]"

Example:

{
  "credentials": {
    "client_email": "[email protected]",
    "client_id": "123456789012345678901",
    "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
    "private_key_id": "a1b2c3d4e5f6...",
    "project_id": "mixpeek-prod-456",
    "type": "service_account"
  },
  "description": "Service account accessing shared drive",
  "provider_type": "google_drive",
  "shared_drive_id": "0AH-Xabc123def456"
}

results.name

string

required

REQUIRED. Human-readable connection name for identification. Displayed in dashboards, sync logs, and API responses. Must be unique within the organization for clarity. Format: 1-100 characters, descriptive of the connection's purpose.

Required string length: 1 - 100

results.created_by_user_id

string

required

REQUIRED. User identifier of the user who created this connection. Used for audit trails and permission checks. Format: usr_{15-character alphanumeric}. Immutable after creation.

results.connection_id

string

Unique identifier for the storage connection. Auto-generated with 'conn_' prefix followed by secure random token. Format: conn_{15-character alphanumeric}. Used for API operations and audit trails.

results.description

string | null

NOT REQUIRED. Optional description explaining the connection's purpose and scope. Helpful for team collaboration and documentation. Format: Up to 500 characters.

Maximum string length: 500

Example:

"Shared drive for marketing team assets and campaign materials"

results.status

enum<string>

default:ACTIVE

Operational status of the connection. ACTIVE: Connection is healthy and ready for use in sync operations. SUSPENDED: Temporarily disabled by user, credentials preserved but sync paused. FAILED: Health checks failing, credentials may be invalid or expired. ARCHIVED: Permanently retired, cannot be reactivated. Status transitions automatically based on health checks and user actions.

Available options:

PENDING,

IN_PROGRESS,

PROCESSING,

COMPLETED,

COMPLETED_WITH_ERRORS,

FAILED,

CANCELED,

UNKNOWN,

SKIPPED,

DRAFT,

ACTIVE,

ARCHIVED,

SUSPENDED

results.is_active

boolean

default:true

Quick boolean flag for filtering active connections in queries. True when status is ACTIVE, False for SUSPENDED/FAILED/ARCHIVED. Maintained automatically when status changes. Use for efficient filtering: db.connections.find({'is_active': True})

results.last_used_at

string<date-time> | null

NOT REQUIRED. UTC timestamp of the most recent successful sync operation. Updated automatically after each successful file sync/list operation. None if connection has never been used. Useful for identifying stale connections and usage analytics.

results.last_error

string | null

NOT REQUIRED. Most recent error message from failed health check or sync. Populated when authentication fails, network errors occur, or permissions denied. None when connection is healthy. Format: Error message truncated to 1000 characters. Used for diagnostics and troubleshooting.

Maximum string length: 1000

Example:

"Authentication failed: Invalid credentials"

results.consecutive_failures

integer

default:0

Counter tracking consecutive failed health checks or sync attempts. Incremented on each failure, reset to 0 on success. Used to implement automatic connection suspension. Auto-suspend after 5 consecutive failures to prevent account lockout. Range: 0 to infinity (typically 0-10).

Required range: x >= 0

results.created_at

string<date-time>

UTC timestamp when the connection was created. Auto-generated using shared.utilities.helpers.current_time(). Immutable after creation. Format: ISO 8601 datetime.

results.updated_at

string<date-time>

UTC timestamp of the most recent update to the connection. Updated automatically on any field modification. Tracks configuration changes, status updates, and credential refreshes. Format: ISO 8601 datetime.

results.metadata

Metadata · object

Arbitrary key-value metadata provided by the user. Useful for tagging, categorization, and custom annotations. NOT REQUIRED - defaults to empty dictionary. Common uses: team tags, cost center codes, project identifiers.

pagination

PaginationResponse · object

required

Pagination metadata including total count, page number, page size, and navigation links for next/previous pages.

Show child attributes

pagination.total

integer

required

pagination.page

integer

required

pagination.page_size

integer

required

pagination.total_pages

integer

required

pagination.next_page

string | null

pagination.previous_page

string | null

total

integer

required

Total number of connections matching the filters (before pagination). Use this to calculate total pages and display pagination controls.

Required range: x >= 0

Delete Api Key Create Storage Connection

⌘I

Health

Organizations

Namespaces

Buckets

Feature Extractors

Collections

Retrievers

Taxonomies

Clusters

Templates

Analytics

Resource Search

Inference

Agent Sessions

Tasks

Webhooks

Notifications

Triggers

List Storage Connections

Headers

Query Parameters

Body

Response