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

> Mantén los archivos de un bucket de Google Cloud Storage disponibles para búsqueda en un namespace.

Una fuente de Google Cloud Storage mantiene un bucket, o prefijos de él, en un namespace. Cada archivo se lee igual que una [subida](https://docs.conare.ai/es/files.md), y un archivo eliminado del bucket pierde sus documentos.

**1. Concede acceso**

Conare lee los buckets como una única cuenta de servicio de Google, así que no se intercambia ninguna clave. Concédele Storage Object Viewer y crea el objeto vacío `.conare/<organization id>`, que demuestra que el bucket es tuyo:

```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. Previsualiza el 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. Conéctalo**

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

## La cuenta

`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`: la cuenta y el rol que debes concederle en tu bucket.
* Una fuente deja de sincronizarse cuando se elimina `.conare/<organization id>`; `gcs_not_verified` indica el objeto que hay que crear.

Esquema completo: [The account to grant a bucket to](https://docs.conare.ai/es/api-reference/sources/get-the-bucket-service-account.md).

## Previsualizar un bucket

`POST /sources/gcs/preview`

Lista lo que leería una fuente del bucket; no se almacena nada.

```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
}
```

| Opción | Tipo | Qué hace |
| - | - | - |
| `bucket` | string, obligatorio | El nombre del bucket |
| `prefixes` | array | Hasta 20 prefijos, cada uno de hasta 1.024 caracteres; sin ninguno se lee todo el bucket |

| Campo | Significado |
| - | - |
| `objects`, `bytes` | Archivos que leería una fuente, y su tamaño |
| `types` | Archivos por tipo; `other` para aquellos cuyo tipo solo revelarán sus bytes |
| `skipped`, `unsupported`, `too_large` | Carpetas y objetos vacíos; archivos que Conare no lee; archivos de más de 512 MiB |
| `sample` | Hasta 20 nombres de archivo |
| `complete` | `false` cuando el bucket tenía más de 10.000 objetos o tardó más de 10 segundos en listarse |

Esquema completo: [Preview a bucket](https://docs.conare.ai/es/api-reference/sources/preview-a-bucket.md).

## Conectar un bucket

Envía `"type": "gcs"` a [`POST /sources`](https://docs.conare.ai/es/sources#conectar-una-fuente); la primera sincronización empieza de inmediato, y una clave limitada al namespace puede conectarlo.

```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"
}
```

| Opción | Tipo | Qué hace |
| - | - | - |
| `type` | string, obligatorio | `gcs` |
| `namespace` | string, obligatorio | El namespace en el que guardar los archivos |
| `bucket` | string, obligatorio | El nombre del bucket |
| `prefixes` | array | Hasta 20 prefijos, cada uno de hasta 1.024 caracteres |
| `name` | string | Un nombre visible, de hasta 200 caracteres; por defecto `gs://bucket/prefix` |
| `sync_interval_s` | integer, predeterminado 3600 | Segundos entre sincronizaciones, de 900 a 604.800 (7 días) |

| Campo | Significado |
| - | - |
| `health` | `ok`; `degraded` cuando la última sincronización retuvo sus eliminaciones; `failing` cuando la cuenta perdió su permiso o fallaron las 3 últimas sincronizaciones |
| `sync` | `state` (`idle`, `queued` o `running`), `last_success_at`, `last_failure_at`, `next_run_at`, `last_error` |
| `documents`, `failures` | Documentos que mantiene, y archivos que no pudo mantener ([más abajo](#fallos)) |
| `config` | El bucket, los prefijos, la cuenta y el intervalo |

## Sincronizar y desconectar

| Acción | Ruta | Respuesta |
| - | - | - |
| Sincronizar ahora | `POST /sources/:id/sync` | `202` con el `run` de la sincronización, o `409 run_active` mientras haya una en cola o en curso |
| Desconectar | `DELETE /sources/:id` | `202` con el `run` que elimina sus documentos; la fuente pasa a `deleting` y luego a `deleted` |

* Cada sincronización lista el bucket y lee los archivos nuevos y modificados.
* Una sincronización que eliminaría más de 1.000 documentos y una décima parte de la fuente espera 24 horas a que una segunda sincronización lo confirme.

## Documentos

Cada archivo es un documento, con el id y las ubicaciones [de una subida](https://docs.conare.ai/es/files.md#documentos-almacenados), además de `source_url` (`gs://bucket/name`), `bucket`, `object` y `generation` en sus metadatos.

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

`GET /sources/:id/documents` lista sus archivos.

## Fallos

`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
}
```

| Opción | Tipo | Qué hace |
| - | - | - |
| `limit` | integer, predeterminado 1000 | Fallos por página, hasta 1.000 |
| `cursor` | string | El `next_cursor` de la página anterior, `null` en la última página |

| `code` | Significado |
| - | - |
| `unsupported_file` | Conare no lee el tipo del archivo |
| `too_large` | Más de 512 MiB |
| `pages_unread` | El OCR no pudo leer las páginas que indica el mensaje; el resto se puede buscar |
| Otros | El error del análisis, como `type_mismatch` o `unreadable_file` |

* Un fallo nunca detiene una sincronización.
* Un archivo que falló de forma definitiva solo se vuelve a leer cuando cambia.
* Uno que falló por un motivo pasajero se reintenta en las 3 sincronizaciones siguientes, y después a diario.

Esquema completo: [List the objects a source could not keep](https://docs.conare.ai/es/api-reference/sources/list-a-sources-failures.md).

## Errores

| Error | Cuándo |
| - | - |
| `422 gcs_access_denied` | La cuenta no puede listar el bucket; el mensaje indica la cuenta y el rol |
| `422 gcs_not_verified` | El bucket no tiene `.conare/<organization id>`; el mensaje indica el objeto |
| `422 gcs_bucket_not_found` | No existe ningún bucket con ese nombre |
| `503 gcs_auth_failed`, `503 gcs_unavailable` | No se pudo contactar con Google Cloud Storage; reinténtalo después de `Retry-After` |


## Related topics

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


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