> ## 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 버킷의 파일을 네임스페이스에서 검색 가능하게 유지하세요.

Google Cloud Storage 소스는 버킷 또는 버킷의 접두사를 하나의 네임스페이스에 유지합니다. 각 파일은 [업로드](https://docs.conare.ai/ko/files.md)와 같은 방식으로 읽히며, 버킷에서 삭제된 파일은 해당 문서도 사라집니다.

**1. 액세스 권한 부여**

Conare는 하나의 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/ko/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/ko/api-reference/sources/preview-a-bucket.md).

## 버킷 연결

[`POST /sources`](https://docs.conare.ai/ko/sources#소스-연결)에 `"type": "gcs"`를 보내세요. 첫 동기화가 즉시 시작되며, 네임스페이스 범위의 키로도 연결할 수 있습니다.

```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, 필수 | 파일을 보관할 네임스페이스 |
| `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이 넘는 문서를 삭제하려는 동기화는 두 번째 동기화가 확인할 때까지 24시간 기다립니다.

## 문서

각 파일은 문서 하나이며, [업로드](https://docs.conare.ai/ko/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/ko/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/ko/api-reference/sources/get-the-bucket-service-account.md)
- [Preview a bucket](https://docs.conare.ai/ko/api-reference/sources/preview-a-bucket.md)
- [List a source's failures](https://docs.conare.ai/ko/api-reference/sources/list-a-sources-failures.md)
- [Sync a source now](https://docs.conare.ai/ko/api-reference/sources/sync-a-source-now.md)
- [소스](https://docs.conare.ai/ko/sources.md)


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