> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Cloud Storage

> Connect Mixpeek to your Google Cloud Storage buckets to ingest and process your data.

> [!NOTE]
>
> This guide explains how to connect your Google Cloud Storage (GCS) buckets to Mixpeek, enabling automated data ingestion and processing.

## Prerequisites

* An active Google Cloud project.
* A GCS bucket containing the data you want Mixpeek to process.
* Permissions to create service accounts and manage IAM policies in your Google Cloud project.

## Configuration Steps

Connecting Mixpeek to GCS requires granting Mixpeek read access to your bucket. We recommend using a service account with appropriate IAM roles for enhanced security.

**1. Create Service Account**

First, create a service account that Mixpeek will use to access your GCS bucket.

1. Navigate to the IAM & Admin > Service Accounts section in your Google Cloud Console.
2. Click **Create Service Account**.
3. Enter a name for the service account (e.g., `mixpeek-gcs-access`).
4. Click **Create and Continue**.
5. Grant the service account the following roles:
   * `Storage Object Viewer` (roles/storage.objectViewer)
   * `Storage Legacy Bucket Reader` (roles/storage.legacyBucketReader)
6. Click **Done**.

**2. Create and Download Service Account Key**

To authenticate with GCS, you'll need to create and download a service account key.

1. Find your newly created service account in the list and click on it.
2. Go to the **Keys** tab.
3. Click **Add Key** > **Create new key**.
4. Choose **JSON** as the key type.
5. Click **Create**.
6. **Important:** The JSON key file will be downloaded to your computer. Store this file securely as you'll need it to configure the connection in Mixpeek.

**3. Add GCS Connection in Mixpeek**

In Studio, go to **Settings > Connections > New Connection** and pick **Google Cloud Storage**.

1. Paste the service account JSON key you downloaded.
2. Enter the **bucket** name. Omit the `gs://` prefix.
3. Optionally set a **prefix** to scope the sync to one folder.
4. Save. Mixpeek tests the credentials before storing them.

To create the same connection over the API, `POST /v1/organizations/connections`:

```bash cURL theme={null}
curl -X POST https://api.mixpeek.com/v1/organizations/connections \
  -H "Authorization: Bearer mxp_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "gcs-media",
    "provider_type": "gcs",
    "provider_config": {
      "provider_type": "gcs",
      "bucket": "YOUR_BUCKET_NAME",
      "prefix": "media/",
      "credentials": {
        "type": "service_account",
        "service_account_json": { "type": "service_account", "project_id": "..." }
      }
    },
    "test_before_save": true
  }'
```

```python Python theme={null}
import requests

requests.post(
    "https://api.mixpeek.com/v1/organizations/connections",
    headers={"Authorization": "Bearer mxp_sk_..."},
    json={
        "name": "gcs-media",
        "provider_type": "gcs",
        "provider_config": {
            "provider_type": "gcs",
            "bucket": "YOUR_BUCKET_NAME",
            "prefix": "media/",
            "credentials": {
                "type": "service_account",
                "service_account_json": service_account_key_dict,
            },
        },
        "test_before_save": True,
    },
)
```

```javascript JavaScript theme={null}
await fetch("https://api.mixpeek.com/v1/organizations/connections", {
  method: "POST",
  headers: {
    Authorization: "Bearer mxp_sk_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "gcs-media",
    provider_type: "gcs",
    provider_config: {
      provider_type: "gcs",
      bucket: "YOUR_BUCKET_NAME",
      prefix: "media/",
      credentials: {
        type: "service_account",
        service_account_json: serviceAccountKey,
      },
    },
    test_before_save: true,
  }),
});
```

> [!NOTE]
>
> Mixpeek uses the native `google-cloud-storage` SDK, not the S3-compatible XML API, so
> you do not need to mint HMAC interoperability keys. `service_account_json` takes the
> whole key object. `private_key` is redacted when you read the connection back.

## Optional: allow writes for export destinations

Read access is all Mixpeek needs to ingest from your bucket. Add write access only if you
want to use this connection as an **export destination**, where Mixpeek writes a dataset
export and its `manifest.json` into your bucket.

Grant the service account one more permission on the bucket, `storage.objects.create`.
The predefined role **Storage Object Creator** (`roles/storage.objectCreator`) carries it,
and **Storage Object Admin** carries it along with delete:

```bash theme={null}
gsutil iam ch \
  serviceAccount:YOUR_SERVICE_ACCOUNT@YOUR_PROJECT.iam.gserviceaccount.com:objectCreator \
  gs://YOUR_BUCKET_NAME
```

Then turn the capability on for that connection, which is off by default:

```bash theme={null}
curl -X PATCH https://api.mixpeek.com/v1/organizations/connections/conn_xxx \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"write_enabled": true}'
```

Both are required, and they are independent: `write_enabled` is your permission for
Mixpeek to try, and the IAM role is Google letting it succeed. An export naming a
connection without the flag is refused before anything is written, and the error names the
permission to add. Connections you never enable stay read-only.

## Verification

Once connected, Mixpeek should start discovering files in your specified GCS bucket (and prefix, if provided). You can monitor the ingestion status within the Mixpeek Studio. Depending on your pipeline configuration, feature extraction and indexing will begin automatically for supported file types.

If you encounter issues, double-check the service account permissions and the credentials provided in Mixpeek. Ensure the bucket name and project ID are correct.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.