> ## 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 > Halten Sie die Dateien eines Google Cloud Storage-Buckets in einem Namespace durchsuchbar. Eine Google Cloud Storage-Quelle hält einen Bucket oder Präfixe davon in einem Namespace. Jede Datei wird wie ein [Upload](https://docs.conare.ai/de/files.md) gelesen, und eine aus dem Bucket gelöschte Datei verliert ihre Dokumente. **1. Zugriff gewähren** Conare liest Buckets als ein einziges Google-Dienstkonto, sodass kein Schlüssel weitergegeben wird. Erteilen Sie ihm Storage Object Viewer und erstellen Sie das leere Objekt `.conare/`, das zeigt, dass der Bucket Ihnen gehört: ```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. Bucket-Vorschau anzeigen** ```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. Verbinden** ```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/"]}' ``` ## Das Konto `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`: das Konto und die Rolle, die Sie ihm für Ihren Bucket erteilen. * Eine Quelle hört auf zu synchronisieren, wenn `.conare/` entfernt wird; `gcs_not_verified` nennt das zu erstellende Objekt. Vollständiges Schema: [Das Konto, dem ein Bucket freigegeben wird](https://docs.conare.ai/de/api-reference/sources/get-the-bucket-service-account.md). ## Vorschau eines Buckets `POST /sources/gcs/preview` Listet auf, was eine Quelle des Buckets lesen würde; nichts wird gespeichert. ```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 } ``` | Option | Typ | Funktion | | - | - | - | | `bucket` | string, erforderlich | Der Name des Buckets | | `prefixes` | array | Bis zu 20 Präfixe, jeweils bis zu 1.024 Zeichen; ohne Präfix wird der ganze Bucket gelesen | | Feld | Bedeutung | | - | - | | `objects`, `bytes` | Dateien, die eine Quelle lesen würde, und ihre Größe | | `types` | Dateien nach Typ; `other` für jene, deren Typ erst die Bytes verraten | | `skipped`, `unsupported`, `too_large` | Ordner und leere Objekte; Dateien, die Conare nicht liest; Dateien über 512 MiB | | `sample` | Bis zu 20 Dateinamen | | `complete` | `false`, wenn der Bucket über 10.000 Objekte enthielt oder das Auflisten über 10 Sekunden dauerte | Vollständiges Schema: [Vorschau eines Buckets](https://docs.conare.ai/de/api-reference/sources/preview-a-bucket.md). ## Einen Bucket verbinden Senden Sie `"type": "gcs"` an [`POST /sources`](https://docs.conare.ai/de/sources#eine-quelle-verbinden); die erste Synchronisierung startet sofort, und ein auf den Namespace beschränkter Schlüssel kann ihn verbinden. ```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" } ``` | Option | Typ | Funktion | | - | - | - | | `type` | string, erforderlich | `gcs` | | `namespace` | string, erforderlich | Der Namespace, in dem die Dateien gehalten werden | | `bucket` | string, erforderlich | Der Name des Buckets | | `prefixes` | array | Bis zu 20 Präfixe, jeweils bis zu 1.024 Zeichen | | `name` | string | Ein Anzeigename, bis zu 200 Zeichen; standardmäßig `gs://bucket/prefix` | | `sync_interval_s` | integer, Standard 3600 | Sekunden zwischen Synchronisierungen, 900 bis 604.800 (7 Tage) | | Feld | Bedeutung | | - | - | | `health` | `ok`; `degraded`, wenn die letzte Synchronisierung ihre Löschungen zurückgehalten hat; `failing`, wenn das Konto seine Berechtigung verloren hat oder die letzten 3 Synchronisierungen fehlgeschlagen sind | | `sync` | `state` (`idle`, `queued` oder `running`), `last_success_at`, `last_failure_at`, `next_run_at`, `last_error` | | `documents`, `failures` | Dokumente, die sie hält, und Dateien, die sie nicht halten konnte ([unten](#fehlschläge)) | | `config` | Bucket, Präfixe, Konto und Intervall | ## Synchronisieren und trennen | Aktion | Route | Antwort | | - | - | - | | Jetzt synchronisieren | `POST /sources/:id/sync` | `202` mit dem `run` der Synchronisierung, oder `409 run_active`, solange eine in der Warteschlange ist oder läuft | | Trennen | `DELETE /sources/:id` | `202` mit dem `run`, der ihre Dokumente löscht; die Quelle ist `deleting`, dann `deleted` | * Jede Synchronisierung listet den Bucket auf und liest neue und geänderte Dateien. * Eine Synchronisierung, die über 1.000 Dokumente und ein Zehntel der Quelle löschen würde, wartet 24 Stunden auf eine zweite Synchronisierung, die das bestätigt. ## Dokumente Jede Datei ist ein Dokument, mit der ID und den Positionen [eines Uploads](https://docs.conare.ai/de/files.md#gespeicherte-dokumente), dazu `source_url` (`gs://bucket/name`), `bucket`, `object` und `generation` in seinen Metadaten. ```json theme={null} { "source_url": "gs://acme-reports/2024/prices.csv" } ``` `GET /sources/:id/documents` listet ihre Dateien auf. ## Fehlschläge `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 } ``` | Option | Typ | Funktion | | - | - | - | | `limit` | integer, Standard 1000 | Fehlschläge pro Seite, bis zu 1.000 | | `cursor` | string | Der `next_cursor` der vorherigen Seite, `null` auf der letzten Seite | | `code` | Bedeutung | | - | - | | `unsupported_file` | Conare liest den Typ der Datei nicht | | `too_large` | Über 512 MiB | | `pages_unread` | OCR konnte die in der Meldung genannten Seiten nicht lesen; der Rest ist durchsuchbar | | Andere | Der Fehler beim Parsen, etwa `type_mismatch` oder `unreadable_file` | * Ein Fehlschlag stoppt nie eine Synchronisierung. * Eine endgültig fehlgeschlagene Datei wird erst wieder gelesen, wenn sie sich ändert. * Eine aus vorübergehendem Grund fehlgeschlagene Datei wird bei den nächsten 3 Synchronisierungen erneut versucht, danach täglich. Vollständiges Schema: [Die Objekte auflisten, die eine Quelle nicht halten konnte](https://docs.conare.ai/de/api-reference/sources/list-a-sources-failures.md). ## Fehler | Fehler | Wann | | - | - | | `422 gcs_access_denied` | Das Konto kann den Bucket nicht auflisten; die Meldung nennt Konto und Rolle | | `422 gcs_not_verified` | Der Bucket hat kein `.conare/`; die Meldung nennt das Objekt | | `422 gcs_bucket_not_found` | Kein Bucket hat diesen Namen | | `503 gcs_auth_failed`, `503 gcs_unavailable` | Google Cloud Storage war nicht erreichbar; versuchen Sie es nach `Retry-After` erneut | ## Related topics - [Get the bucket service account](https://docs.conare.ai/de/api-reference/sources/get-the-bucket-service-account.md) - [Quellen](https://docs.conare.ai/de/sources.md) - [Preview a bucket](https://docs.conare.ai/de/api-reference/sources/preview-a-bucket.md) - [List a source's failures](https://docs.conare.ai/de/api-reference/sources/list-a-sources-failures.md) - [Sync a source now](https://docs.conare.ai/de/api-reference/sources/sync-a-source-now.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.