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

> ## Agent Instructions
> Conare's API is at https://api.conare.ai. Authenticate with `Authorization: Bearer $CONARE_API_KEY`.
> The full OpenAPI spec is at https://api.conare.ai/openapi.yaml; each endpoint has a page under /api-reference, and appending .md to any page URL returns its Markdown.
> Embed with model conare-embed-1; send input_type "query" for search queries. Rerank with conare-rerank-1.
> Prefer the TypeScript SDK (`npm install conare`) or plain HTTP in examples.
> Install the Conare skill with `npx skills add https://docs.conare.ai`; search these docs over MCP at https://docs.conare.ai/mcp; the whole site is at https://docs.conare.ai/llms-full.txt.

# Google Cloud Storage

> Google Cloud Storage バケット内のファイルを namespace で検索可能な状態に保ちます。

Google Cloud Storage ソースは、バケットまたはそのプレフィックスを 1 つの namespace に保ちます。各ファイルは[アップロード](https://docs.conare.ai/ja/files.md)と同じように読み取られ、バケットから削除されたファイルはそのドキュメントも失われます。

**1. アクセスを許可する**

Conare は 1 つの Google サービスアカウントとしてバケットを読み取るため、キーを受け渡す必要はありません。このアカウントに Storage Object Viewer を付与し、バケットがあなたのものであることを示す空のオブジェクト `.conare/<organization id>` を作成します。

```bash gcloud theme={null}
gcloud storage buckets add-iam-policy-binding gs://acme-reports \
  --member=serviceAccount:conare-ingest@strong-ward-488314-c4.iam.gserviceaccount.com \
  --role=roles/storage.objectViewer
gcloud storage cp /dev/null gs://acme-reports/.conare/ORG_ID
```

**2. バケットをプレビューする**

```bash curl theme={null}
curl https://api.conare.ai/sources/gcs/preview \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bucket": "acme-reports", "prefixes": ["2024/"]}'
```

**3. 接続する**

```bash curl theme={null}
curl https://api.conare.ai/sources \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "gcs", "namespace": "reports", "bucket": "acme-reports", "prefixes": ["2024/"]}'
```

## アカウント

`GET /sources/gcs`

```json Response theme={null}
{
  "configured": true,
  "role": "roles/storage.objectViewer",
  "service_account": "conare-ingest@strong-ward-488314-c4.iam.gserviceaccount.com"
}
```

* `service_account`、`role`：アカウントと、バケットでそのアカウントに付与するロールです。
* `.conare/<organization id>` が削除されるとソースの同期は停止します。`gcs_not_verified` は作成すべきオブジェクトを示します。

完全なスキーマ：[バケットへのアクセスを付与するアカウント](https://docs.conare.ai/ja/api-reference/sources/get-the-bucket-service-account.md)。

## バケットをプレビューする

`POST /sources/gcs/preview`

そのバケットのソースが読み取る内容を一覧表示します。何も保存されません。

```json Response theme={null}
{
  "bucket": "acme-reports",
  "bytes": 74,
  "complete": true,
  "objects": 2,
  "prefixes": ["2024/"],
  "sample": ["2024/prices.csv", "2024/site-7.txt"],
  "service_account": "conare-ingest@strong-ward-488314-c4.iam.gserviceaccount.com",
  "skipped": 0,
  "too_large": 0,
  "types": { "csv": 1, "txt": 1 },
  "unsupported": 0
}
```

| オプション | 型 | 内容 |
| - | - | - |
| `bucket` | string、必須 | バケット名 |
| `prefixes` | array | 最大 20 個のプレフィックス。各 1,024 文字までです。指定しない場合はバケット全体を読み取ります |

| フィールド | 意味 |
| - | - |
| `objects`, `bytes` | ソースが読み取るファイルとそのサイズ |
| `types` | 形式ごとのファイル数。バイトからしか判定できないものは `other` |
| `skipped`, `unsupported`, `too_large` | フォルダーと空のオブジェクト、Conare が読み取らないファイル、512 MiB を超えるファイル |
| `sample` | 最大 20 個のファイル名 |
| `complete` | バケットに 10,000 個を超えるオブジェクトがあった場合、または一覧表示に 10 秒を超えた場合は `false` |

完全なスキーマ：[バケットをプレビューする](https://docs.conare.ai/ja/api-reference/sources/preview-a-bucket.md)。

## バケットを接続する

[`POST /sources`](https://docs.conare.ai/ja/sources#ソースを接続する) に `"type": "gcs"` を送信します。最初の同期はすぐに始まり、その namespace にスコープされたキーでも接続できます。

```json Response theme={null}
{
  "id": "src_4e4abfd7ac248dce3668ef76",
  "kind": "gcs",
  "type": "gcs",
  "namespace": "reports",
  "user": null,
  "name": "gs://acme-reports/2024/",
  "status": "active",
  "health": "ok",
  "display": { "state": "ok" },
  "sync": {
    "state": "queued",
    "run_id": null,
    "phase": null,
    "last_success_at": null,
    "last_failure_at": null,
    "next_run_at": "2026-10-21T22:41:44.768045Z",
    "last_error": null
  },
  "documents": 0,
  "documents_verified_at": null,
  "config": {
    "bucket": "acme-reports",
    "prefixes": ["2024/"],
    "service_account": "conare-ingest@strong-ward-488314-c4.iam.gserviceaccount.com",
    "sync_interval_s": 3600
  },
  "failures": 0,
  "created_at": "2026-10-21T21:41:44.768045Z",
  "updated_at": "2026-10-21T21:41:44.768045Z"
}
```

| オプション | 型 | 内容 |
| - | - | - |
| `type` | string、必須 | `gcs` |
| `namespace` | string、必須 | ファイルを保つ namespace |
| `bucket` | string、必須 | バケット名 |
| `prefixes` | array | 最大 20 個のプレフィックス。各 1,024 文字まで |
| `name` | string | 表示名。最大 200 文字です。デフォルトは `gs://bucket/prefix` |
| `sync_interval_s` | integer、デフォルト 3600 | 同期の間隔（秒）。900〜604,800（7 日） |

| フィールド | 意味 |
| - | - |
| `health` | `ok`。前回の同期が削除を保留した場合は `degraded`。アカウントが権限を失った場合や直近 3 回の同期が失敗した場合は `failing` |
| `sync` | `state`（`idle`、`queued`、`running`）、`last_success_at`、`last_failure_at`、`next_run_at`、`last_error` |
| `documents`, `failures` | 保持しているドキュメントと、保持できなかったファイル（[後述](#失敗)） |
| `config` | バケット、プレフィックス、アカウント、間隔 |

## 同期と切断

| 操作 | ルート | 応答 |
| - | - | - |
| 今すぐ同期 | `POST /sources/:id/sync` | 同期の `run` とともに `202`。キュー中または実行中の同期がある場合は `409 run_active` |
| 切断 | `DELETE /sources/:id` | ドキュメントを削除する `run` とともに `202`。ソースは `deleting`、次に `deleted` になります |

* 各同期はバケットを一覧表示し、新規および変更されたファイルを読み取ります。
* 1,000 件を超え、かつソースの 10 分の 1 を超えるドキュメントを削除する同期は、2 回目の同期による確認を 24 時間待ちます。

## ドキュメント

各ファイルは 1 つのドキュメントで、[アップロード](https://docs.conare.ai/ja/files.md#保存されるドキュメント)と同じ id と位置があり、メタデータに `source_url`（`gs://bucket/name`）、`bucket`、`object`、`generation` が加わります。

```json theme={null}
{ "source_url": "gs://acme-reports/2024/prices.csv" }
```

`GET /sources/:id/documents` はソースのファイルを一覧表示します。

## 失敗

`GET /sources/:id/failures`

```bash curl theme={null}
curl https://api.conare.ai/sources/src_b805954930e968fe8d4a89f6/failures \
  -H "Authorization: Bearer $CONARE_API_KEY"
```

```json Response theme={null}
{
  "data": [
    {
      "external_id": "gs://acme-reports/2024/minutes.pdf",
      "key": "minutes.pdf-69578779b32368c6",
      "version": "md5:0HKRGpcwGcvjCA5k1+5AFA==;type=pdf",
      "code": "type_mismatch",
      "message": "type_mismatch: the file is not the type declared: declared pdf, but the bytes are text",
      "run_id": "run_1a20d9cdd1b2092406b048ae",
      "attempts": 1,
      "failed_at": "2026-10-21T21:55:33.56975Z"
    }
  ],
  "next_cursor": null
}
```

| オプション | 型 | 内容 |
| - | - | - |
| `limit` | integer、デフォルト 1000 | ページあたりの失敗数。最大 1,000 |
| `cursor` | string | 前のページの `next_cursor`。最後のページでは `null` |

| `code` | 意味 |
| - | - |
| `unsupported_file` | Conare はそのファイル形式を読み取りません |
| `too_large` | 512 MiB を超えています |
| `pages_unread` | メッセージに示されたページを OCR で読み取れませんでした。残りは検索できます |
| その他 | `type_mismatch` や `unreadable_file` などの解析エラー |

* 失敗によって同期が止まることはありません。
* 恒久的に失敗したファイルは、変更されたときにのみ再度読み取られます。
* 一時的な理由で失敗したファイルは、次の 3 回の同期で再試行され、その後は毎日再試行されます。

完全なスキーマ：[ソースが保持できなかったオブジェクトを一覧表示する](https://docs.conare.ai/ja/api-reference/sources/list-a-sources-failures.md)。

## エラー

| エラー | 発生条件 |
| - | - |
| `422 gcs_access_denied` | アカウントがバケットを一覧表示できません。メッセージにアカウントとロールが示されます |
| `422 gcs_not_verified` | バケットに `.conare/<organization id>` がありません。メッセージにオブジェクトが示されます |
| `422 gcs_bucket_not_found` | その名前のバケットはありません |
| `503 gcs_auth_failed`, `503 gcs_unavailable` | Google Cloud Storage に接続できませんでした。`Retry-After` の後に再試行してください |


## Related topics

- [Get the bucket service account](https://docs.conare.ai/ja/api-reference/sources/get-the-bucket-service-account.md)
- [Preview a bucket](https://docs.conare.ai/ja/api-reference/sources/preview-a-bucket.md)
- [List a source's failures](https://docs.conare.ai/ja/api-reference/sources/list-a-sources-failures.md)
- [Sync a source now](https://docs.conare.ai/ja/api-reference/sources/sync-a-source-now.md)
- [Connect a source](https://docs.conare.ai/ja/api-reference/sources/connect-a-source.md)


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