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

> Mantenha os arquivos de um bucket do Google Cloud Storage pesquisáveis em um namespace.

Uma fonte do Google Cloud Storage mantém um bucket, ou prefixos dele, em um namespace. Cada arquivo é lido como um [upload](https://docs.conare.ai/pt-BR/files.md), e um arquivo excluído do bucket perde seus documentos.

**1. Conceder acesso**

O Conare lê buckets como uma única conta de serviço do Google, então nenhuma chave muda de mãos. Conceda a ela o papel Storage Object Viewer e crie o objeto vazio `.conare/<organization id>`, que mostra que o bucket é seu:

```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. Visualizar o 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. Conectá-lo**

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

## A conta

`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`: a conta e o papel a conceder a ela no seu bucket.
* Uma fonte para de sincronizar quando `.conare/<organization id>` é removido; `gcs_not_verified` indica o objeto a criar.

Schema completo: [A conta à qual conceder um bucket](https://docs.conare.ai/pt-br/api-reference/sources/get-the-bucket-service-account.md).

## Visualizar um bucket

`POST /sources/gcs/preview`

Lista o que uma fonte do bucket leria; nada é armazenado.

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

| Opção | Tipo | O que faz |
| - | - | - |
| `bucket` | string, obrigatório | O nome do bucket |
| `prefixes` | array | Até 20 prefixos, cada um com até 1.024 caracteres; sem nenhum, lê o bucket inteiro |

| Campo | Significado |
| - | - |
| `objects`, `bytes` | Arquivos que uma fonte leria e seu tamanho |
| `types` | Arquivos por tipo; `other` para aqueles cujo tipo só os bytes revelarão |
| `skipped`, `unsupported`, `too_large` | Pastas e objetos vazios; arquivos que o Conare não lê; arquivos acima de 512 MiB |
| `sample` | Até 20 nomes de arquivo |
| `complete` | `false` quando o bucket tinha mais de 10.000 objetos ou levou mais de 10 segundos para ser listado |

Schema completo: [Visualizar um bucket](https://docs.conare.ai/pt-br/api-reference/sources/preview-a-bucket.md).

## Conectar um bucket

Envie `"type": "gcs"` para [`POST /sources`](https://docs.conare.ai/pt-BR/sources#conectar-uma-fonte); a primeira sincronização começa imediatamente, e uma chave restrita ao namespace pode conectá-lo.

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

| Opção | Tipo | O que faz |
| - | - | - |
| `type` | string, obrigatório | `gcs` |
| `namespace` | string, obrigatório | O namespace onde manter os arquivos |
| `bucket` | string, obrigatório | O nome do bucket |
| `prefixes` | array | Até 20 prefixos, cada um com até 1.024 caracteres |
| `name` | string | Um nome de exibição, até 200 caracteres; o padrão é `gs://bucket/prefix` |
| `sync_interval_s` | integer, padrão 3600 | Segundos entre sincronizações, de 900 a 604.800 (7 dias) |

| Campo | Significado |
| - | - |
| `health` | `ok`; `degraded` quando a última sincronização reteve suas exclusões; `failing` quando a conta perdeu sua permissão ou as 3 últimas sincronizações falharam |
| `sync` | `state` (`idle`, `queued` ou `running`), `last_success_at`, `last_failure_at`, `next_run_at`, `last_error` |
| `documents`, `failures` | Documentos que ela mantém e arquivos que não conseguiu manter ([abaixo](#falhas)) |
| `config` | O bucket, os prefixos, a conta e o intervalo |

## Sincronizar e desconectar

| Ação | Rota | Resposta |
| - | - | - |
| Sincronizar agora | `POST /sources/:id/sync` | `202` com o `run` da sincronização, ou `409 run_active` enquanto uma estiver na fila ou em execução |
| Desconectar | `DELETE /sources/:id` | `202` com o `run` que exclui seus documentos; a fonte fica `deleting`, depois `deleted` |

* Cada sincronização lista o bucket e lê arquivos novos e alterados.
* Uma sincronização que excluiria mais de 1.000 documentos e um décimo da fonte aguarda 24 horas até que uma segunda sincronização confirme.

## Documentos

Cada arquivo é um documento, com o id e as localizações [de um upload](https://docs.conare.ai/pt-BR/files.md#documentos-armazenados), além de `source_url` (`gs://bucket/name`), `bucket`, `object` e `generation` em seus metadados.

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

`GET /sources/:id/documents` lista seus arquivos.

## Falhas

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

| Opção | Tipo | O que faz |
| - | - | - |
| `limit` | integer, padrão 1000 | Falhas por página, até 1.000 |
| `cursor` | string | O `next_cursor` da página anterior, `null` na última página |

| `code` | Significado |
| - | - |
| `unsupported_file` | O Conare não lê o tipo do arquivo |
| `too_large` | Acima de 512 MiB |
| `pages_unread` | O OCR não conseguiu ler as páginas indicadas na mensagem; o restante é pesquisável |
| Outros | O erro da conversão, como `type_mismatch` ou `unreadable_file` |

* Uma falha nunca interrompe uma sincronização.
* Um arquivo que falhou definitivamente só é lido de novo quando muda.
* Um que falhou por um motivo passageiro é tentado novamente nas 3 sincronizações seguintes, depois diariamente.

Schema completo: [Listar os objetos que uma fonte não conseguiu manter](https://docs.conare.ai/pt-br/api-reference/sources/list-a-sources-failures.md).

## Erros

| Erro | Quando |
| - | - |
| `422 gcs_access_denied` | A conta não consegue listar o bucket; a mensagem indica a conta e o papel |
| `422 gcs_not_verified` | O bucket não tem `.conare/<organization id>`; a mensagem indica o objeto |
| `422 gcs_bucket_not_found` | Nenhum bucket tem esse nome |
| `503 gcs_auth_failed`, `503 gcs_unavailable` | Não foi possível acessar o Google Cloud Storage; tente novamente após `Retry-After` |


## Related topics

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


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