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

# Sorgenti

> Collega un'app come HubSpot, Gmail o GitHub a un namespace, poi ottieni, elenca, sincronizza, cambia l'intervallo o disconnetti ogni sorgente.

Una sorgente sincronizza un'app in un namespace: i record nuovi e modificati vengono scritti, quelli eliminati vengono eliminati. Le sorgenti richiedono una [chiave](https://docs.conare.ai/it/console.md#chiavi) con accesso completo; per un bucket, consulta [Google Cloud Storage](https://docs.conare.ai/it/gcs.md).

## Collegare una sorgente

`POST /sources`

```bash curl theme={null}
curl https://api.conare.ai/sources \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "hubspot", "namespace": "crm", "redirect_url": "https://yourapp.com/settings"}'
```

```ts TypeScript theme={null}
const { source, connectUrl } = await conare.sources.connect({
  type: "hubspot",
  namespace: "crm",
  redirectUrl: "https://yourapp.com/settings",
});
```

```json Response theme={null}
{
  "source": {
    "id": "src_1cff2c6ea888bbc8343b6e38",
    "type": "hubspot",
    "name": "HubSpot",
    "namespace": "crm",
    "status": "connecting",
    "error": null,
    "documents": 0,
    "last_synced_at": null,
    "created_at": "2026-10-21T21:40:39.704618Z",
    "sync_interval_s": null,
    "sync_interval_auto": true,
    "next_sync_at": null,
    "cost": { "rows_billed": true, "usd_per_million_rows": 100, "options": [ ... ] }
  },
  "connect_url": "https://..."
}
```

Invia il proprietario dell'app a `connect_url` (valido per 7 giorni); la prima sincronizzazione parte quando si collega.

| Opzione | Tipo | Cosa fa |
| - | - | - |
| `type` | string, obbligatorio | L'app, dalla [lista](#elencare-le-app) |
| `namespace` | string, obbligatorio | Il namespace in cui sincronizzare |
| `name` | string | Un nome visualizzato, fino a 100 caratteri |
| `redirect_url` | string | Dove inviare l'utente dopo il collegamento |
| `sync_interval_s` | integer | Secondi tra le sincronizzazioni, da 300 a 2.592.000 (30 giorni); se omesso lo sceglie Conare |
| `config` | object | Per le app che si collegano con una chiave (Twenty, Granola, GitHub): `api_key`, e `base_url` per un Twenty self-hosted; queste si sincronizzano subito, senza `connect_url` |

Per collegare le app dei tuoi utenti, assegna a ciascuno un namespace, come `user-42`. Schema completo: [Collegare una sorgente](https://docs.conare.ai/it/api-reference/sources/connect-a-source.md).

## Documenti sincronizzati

| | |
| - | - |
| Id | `<source id>:<schema>:<record key>` |
| Metadati | `source`, `source_id`, `schema`, `title`, e `url`, `author`, `created_at`, `updated_at` quando il record li ha |
| Cercare in una sorgente | [Filtra](https://docs.conare.ai/it/filters.md) su `source_id` |

## Ottenere una sorgente

`GET /sources/:id`

```bash curl theme={null}
curl https://api.conare.ai/sources/src_1cff2c6ea888bbc8343b6e38 \
  -H "Authorization: Bearer $CONARE_API_KEY"
```

| Campo | Significato |
| - | - |
| `id`, `type`, `name`, `namespace` | Come al collegamento |
| `status` | `connecting` (in attesa dell'accesso), `syncing`, `ready` o `error` |
| `error` | Cosa non è andato a buon fine, oppure `null` |
| `documents` | Documenti sincronizzati |
| `progress` | Durante la sincronizzazione, `records_pulled` finora |
| `created_at`, `last_synced_at`, `next_sync_at` | Quando è stata collegata, l'ultima sincronizzazione e la prossima |
| `sync_interval_s`, `sync_interval_auto` | Secondi tra le sincronizzazioni, e se li sceglie Conare |
| `cost` | Cosa legge una sincronizzazione, e quanto costa al mese ogni frequenza |

Schema completo: [Ottenere una sorgente](https://docs.conare.ai/it/api-reference/sources/get-a-source.md).

## Elencare le sorgenti

`GET /sources`

Restituisce `sources`, ciascuna come la restituisce Get; una sorgente con un `kind`, come `files` o `gcs`, ha invece un oggetto `sync`.

| Opzione | Tipo | Cosa fa |
| - | - | - |
| `namespace`, `user`, `type` | string | Solo le sorgenti il cui campo è uguale al valore, come `?namespace=crm&type=hubspot` |

Schema completo: [Elencare le sorgenti](https://docs.conare.ai/it/api-reference/sources/list-sources.md).

## Sincronizzare ora

`POST /sources/:id/sync`

Avvia una sincronizzazione entro pochi secondi e restituisce la sorgente; una sorgente ancora `connecting` restituisce `409 conflict`.

| Opzione | Tipo | Cosa fa |
| - | - | - |
| `full` | boolean, predefinito `false` | Rilegge tutto, non solo le modifiche (Gmail, Twenty, Granola, GitHub); una sincronizzazione completa di Gmail è fatturata come la prima, e `resync` lo indica |

Schema completo: [Sincronizzare ora una sorgente](https://docs.conare.ai/it/api-reference/sources/sync-a-source-now.md).

## Modificare l'intervallo di sincronizzazione

`PATCH /sources/:id`

| Opzione | Tipo | Cosa fa |
| - | - | - |
| `sync_interval_s` | integer o null | Da 300 a 2.592.000 secondi; `null` lascia scegliere a Conare |

Restituisce la sorgente. Schema completo: [Impostare la frequenza di sincronizzazione](https://docs.conare.ai/it/api-reference/sources/set-how-often-a-source-syncs.md).

## Scollegare una sorgente

`DELETE /sources/:id`

Interrompe la sincronizzazione e restituisce `{ "deleted": true }`.

| Opzione | Tipo | Cosa fa |
| - | - | - |
| `delete_documents` | boolean, predefinito `false` | Elimina anche i documenti sincronizzati |

Schema completo: [Scollegare una sorgente](https://docs.conare.ai/it/api-reference/sources/disconnect-a-source.md).

## Elencare le app

`GET /sources/types`

```json Response theme={null}
{
  "types": [
    { "type": "affinity", "name": "Affinity", "logo_url": "https://..." },
    { "type": "airtable", "name": "Airtable", "logo_url": "https://..." }
  ]
}
```

* Ognuna ha il `type` da collegare, il suo `name` e `logo_url`, e `auth: "api_key"` per le app che si collegano con `config`.
* `partial` è `true` quando è stato possibile elencare solo quelle app: riprova più tardi.

Schema completo: [Elencare i tipi di sorgente](https://docs.conare.ai/it/api-reference/sources/list-source-types.md).


## Related topics

- [Connect a source](https://docs.conare.ai/it/api-reference/sources/connect-a-source.md)
- [Disconnect a source](https://docs.conare.ai/it/api-reference/sources/disconnect-a-source.md)
- [List sources](https://docs.conare.ai/it/api-reference/sources/list-sources.md)
- [Preview a bucket](https://docs.conare.ai/it/api-reference/sources/preview-a-bucket.md)
- [Get a source](https://docs.conare.ai/it/api-reference/sources/get-a-source.md)


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