docs: context is the ingest list field everywhere, regenerate the v2 spec (PRO-1618)

api-reference/v2/endpoint/add-connector-resource.mdx

@@ -19,7 +19,7 @@ curl -X POST 'https://api.hydradb.com/connectors/{id}/resources' \
     "resource_id": "{resource_id}",
     "resource_type": "channel",
     "display_name": "general",
-    "sub_tenant_id_override": "all-hands"
+    "collection_override": "all-hands"
   }'
 ```
 
@@ -38,7 +38,8 @@ curl -X POST 'https://api.hydradb.com/connectors/{id}/resources' \
 | <Field name="resource_id" type="string" required /> | Resource identifier from `GET /connectors/:id/discover`. |
 | <Field name="resource_type" type="string" required /> | Resource type from `GET /connectors/:id/discover`. |
 | <Field name="display_name" type="string" /> | Human-readable name for this resource. |
-| <Field name="sub_tenant_id_override" type="string" /> | Routes synced objects from this resource into a specific sub-tenant partition. |
+| <Field name="collection_override" type="string" /> | Routes synced objects from this resource into a specific collection. (deprecated alias: `sub_tenant_id_override`) |
+| <Field name="database_override" type="string" /> | Routes synced objects from this resource into a different database. (deprecated alias: `tenant_id_override`) |
 
 <ResponseExample>
 
@@ -52,6 +53,8 @@ curl -X POST 'https://api.hydradb.com/connectors/{id}/resources' \
   "provider_cursor": "",
   "tenant_id_override": "",
   "sub_tenant_id_override": "all-hands",
+  "database_override": "",
+  "collection_override": "all-hands",
   "provider_metadata": null,
   "filters": null
 }
@@ -63,6 +66,6 @@ curl -X POST 'https://api.hydradb.com/connectors/{id}/resources' \
 
 ## Related Resources
 
-- [List Connector Resources](/api-reference/v2/endpoint/connector-resources)  -  view all resources and sync state
-- [Delete Connector Resource](/api-reference/v2/endpoint/delete-connector-resource)  -  remove a resource
-- [Configure Connector](/api-reference/v2/endpoint/configure-connector)  -  add multiple resources with metadata and lookback settings
+- [List Connector Resources](/api-reference/v2/endpoint/connector-resources): view all resources and sync state
+- [Delete Connector Resource](/api-reference/v2/endpoint/delete-connector-resource): remove a resource
+- [Configure Connector](/api-reference/v2/endpoint/configure-connector): add multiple resources with metadata and lookback settings

api-reference/v2/endpoint/configure-connector.mdx

@@ -6,7 +6,7 @@ openapi: "api-reference/v2/openapi.json POST /connectors/{id}/configure"
 
 import { Field } from "/snippets/field.jsx";
 
-Activates one or more resources and sets sync options. This is the step between discovery and the first sync. You can call configure again at any time to add resources, change `sub_tenant_id`, or update metadata  -  the cursor is preserved on reconfigure.
+Activates one or more resources and sets sync options, then starts a sync right away unless the connector is paused. You can call configure again at any time to add resources, change `collection`, or update metadata; the cursor is preserved on reconfigure.
 
 <RequestExample>
 
@@ -22,15 +22,15 @@ curl -X POST 'https://api.hydradb.com/connectors/{connector_id}/configure' \
         "resource_id": "{resource_id}",
         "resource_type": "channel",
         "name": "general",
-        "sub_tenant_id": "all-hands",
+        "collection": "all-hands",
         "metadata": { "department": "all-hands" },
         "additional_metadata": { "internal_label": "general-slack" }
       },
       {
         "resource_id": "{resource_id_2}",
         "resource_type": "channel",
         "name": "engineering",
-        "sub_tenant_id": "engineering",
+        "collection": "engineering",
         "metadata": { "department": "engineering" }
       }
     ]
@@ -49,41 +49,43 @@ curl -X POST 'https://api.hydradb.com/connectors/{connector_id}/configure' \
 
 | Name | Description |
 | --- | --- |
-| <Field name="resources" type="array" required /> | Resources to activate. Each item corresponds to one entry from [Discover](/api-reference/v2/endpoint/discover-connector-resources). |
-| <Field name="lookback_days" type="integer" /> | How far back the first sync fetches historical data. Only applies to the initial sync  -  subsequent syncs are incremental from the last cursor. (default: `30`) |
+| <Field name="resources" type="array" required /> | Resources to activate. Each entry corresponds to one entry from [Discover](/api-reference/v2/endpoint/discover-connector-resources). |
+| <Field name="lookback_days" type="integer" /> | History the first sync fetches; later syncs are incremental. Above `30`, some providers backfill in the background (`backfill: true`). (default: `30`) |
 
-### Resource item fields
+### Resource entry fields
 
 | Name | Description |
 | --- | --- |
 | <Field name="resource_id" type="string" required /> | Resource identifier from `GET /connectors/:id/discover`. |
 | <Field name="resource_type" type="string" required /> | Resource type from `GET /connectors/:id/discover` (e.g. `channel`, `repo`, `linear_team`). |
 | <Field name="name" type="string" /> | Display name for this resource. |
-| <Field name="sub_tenant_id" type="string" /> | Routes synced objects from this resource into a specific sub-tenant partition. Overrides the connector-level `sub_tenant_id`. |
-| <Field name="metadata" type="object" /> | Key-value pairs merged into tenant metadata on every synced object from this resource. Undeclared keys are accepted and stored, but only keys declared in `database_metadata_schema` are indexed for filtering. |
-| <Field name="additional_metadata" type="object" /> | Key-value pairs merged into document metadata on every synced object from this resource. Free-form, no schema required. |
+| <Field name="collection" type="string" /> | Routes synced objects from this resource into a specific collection. Overrides the connector-level `collection`. (deprecated alias: `sub_tenant_id`) |
+| <Field name="metadata" type="object" /> | Key-value pairs merged into the attributes of every synced object from this resource. Only keys in `database_metadata_schema` are filterable. |
+| <Field name="additional_metadata" type="object" /> | Key-value pairs merged into the custom attributes of every synced object from this resource. Free-form, no schema required. |
 
-See [Connectors - Overview](/api-reference/v2/endpoint/connectors-overview) for how these merge with system-generated fields.
+See [Connectors: Overview](/api-reference/v2/endpoint/connectors-overview) for how these merge with system-generated fields.
 
 <ResponseExample>
 
 ```json 200
 {
-  "backfill": false,
+  "connector_id": "{connector_id}",
   "configured": 2,
-  "connector_id": "{connector_id}"
+  "backfill": false,
+  "first_sync_at": "2026-06-01T13:05:00Z",
+  "message": "First sync is running. Data usually appears within a few minutes; the connector reports lifecycle 'ingesting' until data has synced."
 }
 ```
 
 </ResponseExample>
 
-`configured` is the count of resources successfully activated.
+`configured` is the count of resources successfully activated. `message` says whether the first sync started now or when the scheduled one runs. `warnings`, when present, names resources that were saved but returned nothing when probed.
 
 <div className="api-before-related-resources" />
 
 ## Related Resources
 
-- **Next:** [Sync Connector](/api-reference/v2/endpoint/sync-connector)  -  trigger an on-demand sync (the scheduler also runs hourly automatically)
-- **Next:** [Connector Resources](/api-reference/v2/endpoint/connector-resources)  -  poll `provider_cursor` to confirm sync ran
-- [Discover Resources](/api-reference/v2/endpoint/discover-connector-resources)  -  find resource IDs before configuring
-- [Connectors - Overview](/api-reference/v2/endpoint/connectors-overview)
+- **Next:** [Sync Connector](/api-reference/v2/endpoint/sync-connector): trigger another sync on demand (the scheduler runs hourly by default)
+- **Next:** [List Connector Resources](/api-reference/v2/endpoint/connector-resources): poll `provider_cursor` to confirm sync ran
+- [Discover Resources](/api-reference/v2/endpoint/discover-connector-resources): find resource IDs before configuring
+- [Connectors: Overview](/api-reference/v2/endpoint/connectors-overview)

api-reference/v2/endpoint/connector-resources.mdx

@@ -6,7 +6,7 @@ openapi: "api-reference/v2/openapi.json GET /connectors/{id}/resources"
 
 import { Field } from "/snippets/field.jsx";
 
-Returns all resources configured on a connector and their current sync state. Poll `provider_cursor` after triggering a sync  -  a non-empty value confirms the sync ran.
+Returns all resources configured on a connector and their current sync state. Poll `provider_cursor` after triggering a sync: a non-empty value confirms the sync ran.
 
 <RequestExample>
 
@@ -38,6 +38,8 @@ curl 'https://api.hydradb.com/connectors/{id}/resources' \
       "provider_cursor": "{cursor}",
       "tenant_id_override": "",
       "sub_tenant_id_override": "all-hands",
+      "database_override": "",
+      "collection_override": "all-hands",
       "provider_metadata": null,
       "filters": {
         "lookback_days": 30
@@ -49,13 +51,13 @@ curl 'https://api.hydradb.com/connectors/{id}/resources' \
 
 </ResponseExample>
 
-Use `status` and `provider_cursor` to track sync state. A non-empty `provider_cursor` confirms the first sync has run.
+Use `status` and `provider_cursor` to track sync state. `database_override` and `collection_override` show where the resource's objects are routed (empty means the connector's own); `tenant_id_override` and `sub_tenant_id_override` are deprecated aliases.
 
 <div className="api-before-related-resources" />
 
 ## Related Resources
 
-- [Add Connector Resource](/api-reference/v2/endpoint/add-connector-resource)  -  add a single resource
-- [Delete Connector Resource](/api-reference/v2/endpoint/delete-connector-resource)  -  remove a resource
-- [Configure Connector](/api-reference/v2/endpoint/configure-connector)  -  activate multiple resources with metadata and lookback settings
-- [Sync Connector](/api-reference/v2/endpoint/sync-connector)  -  trigger a sync
+- [Add Connector Resource](/api-reference/v2/endpoint/add-connector-resource): add a single resource
+- [Delete Connector Resource](/api-reference/v2/endpoint/delete-connector-resource): remove a resource
+- [Configure Connector](/api-reference/v2/endpoint/configure-connector): activate multiple resources with metadata and lookback settings
+- [Sync Connector](/api-reference/v2/endpoint/sync-connector): trigger a sync

api-reference/v2/endpoint/connectors-overview.mdx

@@ -1,9 +1,9 @@
 ---
-title: "Connectors - Overview"
+title: "Connectors: Overview"
 description: "Quick reference for all connector endpoints, their lifecycle, and when to call each."
 ---
 
-Connectors continuously sync external app data (Slack, GitHub, Linear, Notion, Gmail) into your database without manual ingestion.
+Connectors continuously sync external app data (for example Slack, GitHub, Linear, Notion or Gmail) into your database without manual ingestion.
 
 ## Endpoint references
 
@@ -45,30 +45,30 @@ API-Version: 2
 
 ## Key concepts
 
-- **Connector**  -  An authenticated connection to one external provider account. A single connector manages all resources synced from that account.
-- **Resource**  -  A syncable unit within a provider: a Slack channel, GitHub repo, Linear team/project, Notion database/page, or Gmail label. You activate resources individually via `/configure`.
-- **Cursor**  -  A per-resource bookmark of the last synced position. Sync is incremental: only content newer than the cursor is fetched on each run.
-- **provider_account_scope**  -  An identifier for the external account (e.g. Slack workspace ID, GitHub org). Used as part of the deduplication key  -  two connectors for the same provider must have distinct `provider_account_scope` values.
+- **Connector**: an authenticated connection to one external provider account. A single connector manages all resources synced from that account.
+- **Resource**: a syncable unit within a provider, such as a Slack channel, GitHub repo, Linear team or project, Notion database or page, or Gmail label. You activate resources individually via `/configure`.
+- **Cursor**: a per-resource bookmark of the last synced position. Sync is incremental: only content newer than the cursor is fetched on each run.
+- **provider_account_scope**: an identifier for the external account (for example a Slack workspace ID or GitHub org). It is part of every synced context's ID, so two connectors for the same provider need distinct values.
 
 ## Metadata on synced objects
 
 Every object synced by a connector has two metadata layers.
 
-### Tenant metadata (`metadata`)
+### Attributes (`metadata`)
 
-Tenant metadata is the **schema-declared** layer. Fields are defined per tenant through `database_metadata_schema` and are indexed for fast, exact-match filtering. Use it for stable fields you filter on often, such as `department`, `region`, `status`, or `priority`.
+Attributes are the **schema-declared** layer. Fields are declared once per database in `database_metadata_schema` and indexed for exact-match filtering. Use it for stable fields you filter on often, such as `department`, `region`, `status`, or `priority`.
 
-HydraDB writes `provider` into tenant metadata for every synced object. You can add fields through `metadata` on each resource in [Configure Connector](/api-reference/v2/endpoint/configure-connector). User-supplied fields are merged first; `provider` takes precedence.
+HydraDB writes `provider` and `connector_id` into the attributes of every synced object. You can add fields through `metadata` on each resource in [Configure Connector](/api-reference/v2/endpoint/configure-connector). User-supplied fields are merged first; `provider` and `connector_id` take precedence.
 
-### Document metadata (`additional_metadata`)
+### Custom attributes (`additional_metadata`)
 
-Document metadata is the **free-form** layer and needs no schema. Connectors automatically populate provider-specific fields including connector ID, resource ID, provider account scope, and provider-native identifiers.
+Custom attributes are the **free-form** layer and need no schema. Connectors automatically populate provider-specific fields including connector ID, resource ID, provider account scope, and provider-native identifiers.
 
 You can add fields through `additional_metadata` on each resource in [Configure Connector](/api-reference/v2/endpoint/configure-connector). User-supplied fields are merged first; provider-generated fields take precedence.
 
-Use document metadata to scope a query to a connector, channel, repository, or inbox:
+Use custom attributes to scope a query to a connector, channel, repository, or inbox. [`attributes`](/essentials/v2/attributes) on `/query` does not reach them, so these filters use `metadata_filters`:
 
-```json Querying with document metadata filter
+```json Querying with a custom attribute filter
 {
   "database": "acme_corp",
   "query": "deployment checklist",
@@ -93,13 +93,13 @@ You can create more than one connector for the same provider, such as two Slack
 
 Set a distinct `provider_account_scope` for each account. It is part of every object's deduplication key; without it, objects from two accounts of the same provider can collide.
 
-You can also route resources from one connector to different sub-tenants with [Configure Connector](/api-reference/v2/endpoint/configure-connector):
+You can also route resources from one connector to different collections with [Configure Connector](/api-reference/v2/endpoint/configure-connector):
 
 ```json
 {
   "resources": [
-    { "resource_id": "C_GENERAL", "name": "general", "sub_tenant_id": "all-hands" },
-    { "resource_id": "C_ENG", "name": "engineering", "sub_tenant_id": "engineering" }
+    { "resource_id": "C_GENERAL", "name": "general", "collection": "all-hands" },
+    { "resource_id": "C_ENG", "name": "engineering", "collection": "engineering" }
   ]
 }
 ```

api-reference/v2/endpoint/create-connector.mdx

@@ -33,26 +33,34 @@ curl -X POST 'https://api.hydradb.com/connectors' \
 
 | Name | Description |
 | --- | --- |
-| <Field name="provider" type="string" required /> | Provider to connect. One of `slack`, `github`, `linear`, `notion`, `gmail`. |
-| <Field name="name" type="string" required /> | Human-readable label for this connector. |
+| <Field name="provider" type="string" required /> | Provider to connect: a `provider` value from [List Connector Providers](/api-reference/v2/endpoint/list-connector-providers). |
+| <Field name="name" type="string" /> | Human-readable label for this connector. |
 | <Field name="database" type="string" required /> | Which database receives the synced data. (deprecated alias: `tenant_id`) |
 | <Field name="collection" type="string" /> | Default collection partition for synced objects. Individual resources can override this. (deprecated alias: `sub_tenant_id`; default: `""`) |
-| <Field name="provider_account_scope" type="string" /> | Identifier for the external account (e.g. Slack workspace ID, GitHub org name). Used in deduplication  -  must be distinct across connectors for the same provider. |
-| <Field name="credentials" type="object" required /> | Provider-specific credentials. Typically `{ "api_token": "..." }` or `{ "access_token": "..." }`. |
+| <Field name="provider_account_scope" type="string" /> | External account id, such as a Slack workspace ID. Part of every synced context's ID, so keep it distinct per connector. |
+| <Field name="credentials" type="object" required /> | Credentials matching the provider's `credential_schema` from [Get Connector Provider](/api-reference/v2/endpoint/get-connector-provider). |
+| <Field name="sync_interval_seconds" type="integer" /> | Seconds between scheduled syncs. From `300` to `604800`; a few providers set a higher minimum or a lower maximum. (default: `3600`) |
+| <Field name="custom_instructions" type="string" /> | Instructions that steer how this connector's synced documents are ingested and indexed. Up to 4000 characters. |
 
 <ResponseExample>
 
 ```json 201
 {
   "connector_id": "{connector_id}",
-  "provider": "slack",
-  "name": "acme-engineering",
   "tenant_id": "acme_corp",
   "sub_tenant_id": "engineering",
+  "database": "acme_corp",
+  "collection": "engineering",
+  "name": "acme-engineering",
+  "provider": "slack",
   "provider_account_scope": "T12345ACME",
+  "auth_type": "",
   "status": "active",
-  "next_sync_at": "2026-06-01T13:00:00Z",
-  "sync_interval_seconds": 3600
+  "next_sync_at": "2026-06-01T13:05:00Z",
+  "sync_interval_seconds": 3600,
+  "lifecycle": "active",
+  "first_sync_at": "2026-06-01T13:05:00Z",
+  "message": "Connector created. Configure resources to start syncing; the first scheduled sync runs in about 5 minutes."
 }
 ```
 
@@ -62,7 +70,7 @@ curl -X POST 'https://api.hydradb.com/connectors' \
 
 ## Related Resources
 
-- **Next:** [Discover Resources](/api-reference/v2/endpoint/discover-connector-resources)  -  inspect what's available before activating
-- **Next:** [Configure Connector](/api-reference/v2/endpoint/configure-connector)  -  activate resources for sync
+- **Next:** [Discover Resources](/api-reference/v2/endpoint/discover-connector-resources): inspect what's available before activating
+- **Next:** [Configure Connector](/api-reference/v2/endpoint/configure-connector): activate resources for sync
 - **Teardown:** [Delete Connector](/api-reference/v2/endpoint/delete-connector)
-- **Read more:** [Connectors - Overview](/api-reference/v2/endpoint/connectors-overview)
+- **Read more:** [Connectors: Overview](/api-reference/v2/endpoint/connectors-overview)