> ## 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

> Gardez les fichiers d'un bucket Google Cloud Storage consultables dans un namespace.

Une source Google Cloud Storage synchronise un bucket, ou certains de ses préfixes, dans un namespace. Chaque fichier est lu comme lors d'un [import](https://docs.conare.ai/fr/files.md), et un fichier supprimé du bucket perd ses documents.

**1. Accorder l'accès**

Conare lit les buckets via un unique compte de service Google, donc aucune clé n'est échangée. Accordez-lui le rôle Storage Object Viewer et créez l'objet vide `.conare/<organization id>`, qui prouve que le bucket vous appartient :

```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. Prévisualiser le bucket**

```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. Le connecter**

```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/"]}'
```

## Le compte

`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` : le compte, et le rôle à lui accorder sur votre bucket.
* Une source cesse de se synchroniser lorsque `.conare/<organization id>` est supprimé ; `gcs_not_verified` indique l'objet à créer.

Schéma complet : [The account to grant a bucket to](https://docs.conare.ai/fr/api-reference/sources/get-the-bucket-service-account.md).

## Prévisualiser un bucket

`POST /sources/gcs/preview`

Liste ce qu'une source de ce bucket lirait ; rien n'est stocké.

```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 | Type | Ce qu'elle fait |
| - | - | - |
| `bucket` | chaîne, requis | Le nom du bucket |
| `prefixes` | tableau | Jusqu'à 20 préfixes, chacun jusqu'à 1 024 caractères ; sans préfixe, tout le bucket est lu |

| Champ | Signification |
| - | - |
| `objects`, `bytes` | Fichiers qu'une source lirait, et leur taille |
| `types` | Fichiers par type ; `other` pour ceux dont seuls les octets révéleront le type |
| `skipped`, `unsupported`, `too_large` | Dossiers et objets vides ; fichiers que Conare ne lit pas ; fichiers de plus de 512 Mio |
| `sample` | Jusqu'à 20 noms de fichiers |
| `complete` | `false` lorsque le bucket contenait plus de 10 000 objets ou que son listage a pris plus de 10 secondes |

Schéma complet : [Preview a bucket](https://docs.conare.ai/fr/api-reference/sources/preview-a-bucket.md).

## Connecter un bucket

Envoyez `"type": "gcs"` à [`POST /sources`](https://docs.conare.ai/fr/sources#connecter-une-source) ; la première synchronisation démarre immédiatement, et une clé limitée au namespace peut le connecter.

```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 | Type | Ce qu'elle fait |
| - | - | - |
| `type` | chaîne, requis | `gcs` |
| `namespace` | chaîne, requis | Le namespace où conserver les fichiers |
| `bucket` | chaîne, requis | Le nom du bucket |
| `prefixes` | tableau | Jusqu'à 20 préfixes, chacun jusqu'à 1 024 caractères |
| `name` | chaîne | Un nom d'affichage, jusqu'à 200 caractères ; par défaut `gs://bucket/prefix` |
| `sync_interval_s` | entier, 3600 par défaut | Secondes entre deux synchronisations, de 900 à 604 800 (7 jours) |

| Champ | Signification |
| - | - |
| `health` | `ok` ; `degraded` lorsque la dernière synchronisation a retenu ses suppressions ; `failing` lorsque le compte a perdu son autorisation ou que les 3 dernières synchronisations ont échoué |
| `sync` | `state` (`idle`, `queued` ou `running`), `last_success_at`, `last_failure_at`, `next_run_at`, `last_error` |
| `documents`, `failures` | Documents conservés, et fichiers qui n'ont pas pu l'être ([ci-dessous](#échecs)) |
| `config` | Le bucket, les préfixes, le compte et l'intervalle |

## Synchroniser et déconnecter

| Action | Route | Réponse |
| - | - | - |
| Synchroniser maintenant | `POST /sources/:id/sync` | `202` avec le `run` de la synchronisation, ou `409 run_active` tant qu'une synchronisation est en file ou en cours |
| Déconnecter | `DELETE /sources/:id` | `202` avec le `run` qui supprime ses documents ; la source passe à `deleting`, puis `deleted` |

* Chaque synchronisation liste le bucket et lit les fichiers nouveaux et modifiés.
* Une synchronisation qui supprimerait plus de 1 000 documents et un dixième de la source attend 24 heures qu'une seconde synchronisation la confirme.

## Documents

Chaque fichier est un document, avec l'id et les emplacements d'[un import](https://docs.conare.ai/fr/files.md#documents-stockés), plus `source_url` (`gs://bucket/name`), `bucket`, `object` et `generation` dans ses métadonnées.

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

`GET /sources/:id/documents` liste ses fichiers.

## Échecs

`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 | Type | Ce qu'elle fait |
| - | - | - |
| `limit` | entier, 1000 par défaut | Échecs par page, jusqu'à 1 000 |
| `cursor` | chaîne | Le `next_cursor` de la page précédente, `null` sur la dernière page |

| `code` | Signification |
| - | - |
| `unsupported_file` | Conare ne lit pas ce type de fichier |
| `too_large` | Plus de 512 Mio |
| `pages_unread` | L'OCR n'a pas pu lire les pages indiquées dans le message ; le reste est consultable |
| Autres | L'erreur de conversion, comme `type_mismatch` ou `unreadable_file` |

* Un échec n'arrête jamais une synchronisation.
* Un fichier en échec définitif n'est relu que s'il change.
* Un fichier en échec pour une raison passagère est retenté lors des 3 synchronisations suivantes, puis chaque jour.

Schéma complet : [List the objects a source could not keep](https://docs.conare.ai/fr/api-reference/sources/list-a-sources-failures.md).

## Erreurs

| Erreur | Quand |
| - | - |
| `422 gcs_access_denied` | Le compte ne peut pas lister le bucket ; le message indique le compte et le rôle |
| `422 gcs_not_verified` | Le bucket n'a pas de `.conare/<organization id>` ; le message indique l'objet |
| `422 gcs_bucket_not_found` | Aucun bucket ne porte ce nom |
| `503 gcs_auth_failed`, `503 gcs_unavailable` | Google Cloud Storage est injoignable ; réessayez après `Retry-After` |


## Related topics

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


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