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

# Sources

> Connect an app once. Conare keeps it in sync with a namespace.

A source is an app connected to Conare, like HubSpot or Gmail. It syncs into one namespace on a
schedule (Gmail every 15 minutes, other apps every hour, or now with `sources.sync(id)`): new and
changed records are written, and records deleted in the app are deleted.

Each record becomes one document:

* `id`: `<source id>:<schema>:<record key>`, for example `src_1a2b3c:contacts:1042`, so two
  sources in one namespace never overwrite each other
* `text`: the record as readable text
* `metadata`: `source` (the app), `source_id`, `schema`, and useful fields such as title, url,
  author and dates

So you can query a source like any other namespace, and filter by `schema` or `source_id`.

## Connect an app

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

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

`connectUrl` is a hosted page where the person who owns the app account signs in. It works for
7 days. After that they return to `redirectUrl` and the first sync starts.

| Status | Means |
| - | - |
| `connecting` | Waiting for the app owner to sign in. |
| `syncing` | A sync is running. |
| `ready` | Synced. The next sync runs on schedule. |
| `error` | Something failed. `error` says what. |

`sources.types()` (`GET /sources/types`) lists the apps you can connect and the `type` to pass.

## Connect your users' apps

To give each user of your app search over their own apps, connect each user's apps into that
user's namespace:

```ts theme={null}
// In your "Connect HubSpot" button handler, on your server:
const { connectUrl } = await conare.sources.connect({
  type: "hubspot",
  namespace: `user-${user.id}`,
  redirectUrl: "https://yourapp.com/settings/connections",
});
return redirect(connectUrl);

// Later, when that user asks your AI something:
const context = await conare.namespace(`user-${user.id}`).query(question);
```

Each user signs in to their own account. Their records land only in their namespace.

## Manage sources

<CodeGroup>
  ```ts TypeScript theme={null}
  await conare.sources.list();                                   // every source
  await conare.sources.get("src_2b9c1f");                        // status, documents, lastSyncedAt
  await conare.sources.sync("src_2b9c1f");                       // sync now
  await conare.sources.delete("src_2b9c1f", { deleteDocuments: true });
  ```

  ```bash curl theme={null}
  curl https://api.conare.ai/sources -H "Authorization: Bearer $CONARE_API_KEY"
  curl -X POST https://api.conare.ai/sources/src_2b9c1f/sync -H "Authorization: Bearer $CONARE_API_KEY"
  curl -X DELETE "https://api.conare.ai/sources/src_2b9c1f?delete_documents=true" -H "Authorization: Bearer $CONARE_API_KEY"
  ```
</CodeGroup>

Deleting a source stops syncing and removes the connection. Its documents stay unless you pass
`deleteDocuments: true`.

You can also connect, watch and disconnect sources in the [console](/console).