> ## Documentation Index
> Fetch the complete documentation index at: https://cortex-e852fafe-t3code-rewrite-docs-declutter.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Ingestion Instructions

> Tell a connector how to interpret the documents it syncs, for the whole connector or for one resource.

A custom ingestion instruction is free text that a [connector](/essentials/v2/connectors) reads at sync time and includes in the extraction and inference prompts for every document it syncs. Use one to explain what the documents do not spell out: a product rename, what a channel is for, or what an internal term means. Set it with `custom_instructions` on [`PATCH /connectors/{id}`](/api-reference/v2/endpoint/update-connector), or on one resource.

This guide builds up in order:

1. [Set an instruction on a connector](#1-set-an-instruction-on-a-connector): one request, shown with a product rename.
2. [Two levels: connector default and resource override](#2-two-levels-connector-default-and-resource-override).
3. [Clear an instruction and read it back](#3-clear-an-instruction-and-read-it-back).
4. [Limits](#4-limits): what instructions can and cannot do.
5. [Common mistakes](#common-mistakes) and [related pages](#related).

<a id="set-instructions-on-a-connector" />

## 1. Set an instruction on a connector

Suppose your product was rebranded from *Aurora* to *Nimbus*. Years of Slack threads and Confluence pages mention only the old name, none of them states the rename, and a search for "Nimbus" misses all of the pre-rebrand context. One instruction on the connector fixes the interpretation at ingestion time. Every connector supports instructions, and setting one is a single `PATCH` with no reconnection.

<Accordion title="Set a connector instruction: cURL">
  ```bash cURL theme={"dark"}
  curl -X PATCH 'https://api.hydradb.com/connectors/{id}' \
    -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
    -H "API-Version: 2" \
    -H "Content-Type: application/json" \
    -d '{
      "custom_instructions": "Aurora was renamed to Nimbus in January 2025; they are the same product. Index all Aurora content under the canonical name Nimbus and record Aurora as a former name."
    }'
  ```
</Accordion>

### What each property means

| Property | What it is |
| - | - |
| `{id}` | The `connector_id` returned when you [created the connector](/essentials/v2/connectors#1-set-up-a-connector). |
| `custom_instructions` | The instruction, up to 4,000 characters. Only the fields you send change, so the connector's credentials, interval, and resources stay as they are. |

The connector re-reads its configuration at the start of every sync, so the instruction applies from the next sync onward. From then on, documents that mention only Aurora are extracted under the Nimbus entity, with alias links to the old name, so new-name queries reach old-name content through the [knowledge graph](/essentials/v2/context-graphs).

The same mechanism works for focus ("prioritize decisions, owners, and deadlines; ignore social chatter"), interpretation ("threads in this workspace are incident retros; extract root cause and remediation"), and domain vocabulary ("SEV1 and SEV2 are incident severities, not product names").

You can also set the instruction at create time with `custom_instructions` on [`POST /connectors`](/api-reference/v2/endpoint/create-connector), or from the dashboard: the connect flow has an Instructions field, and an existing connector has an **Instructions** button.

## 2. Two levels: connector default and resource override

An instruction lives at one of two levels:

* **Connector level:** applies to every resource that has no instruction of its own. Set it with `custom_instructions` on `POST /connectors` or `PATCH /connectors/{id}`, as in section 1.
* **Resource level:** applies only to documents synced from that one resource, such as one Slack channel or one Jira project. Set it with `custom_instructions` on a resource in [configure](/api-reference/v2/endpoint/configure-connector), or afterwards with [`PATCH /connectors/{id}/resources/{resource_id}`](/api-reference/v2/endpoint/update-connector-resource).

A resource-level instruction **replaces** the connector default for that resource's documents. It does not add to it. A resource with no instruction of its own inherits the connector default, the same way a resource without its own `collection` inherits the connector's. Use a resource override when channels need different guidance, such as incident retrospectives and release notes.

<Accordion title="Set a default at create, then override one channel: cURL">
  <CodeGroup>
    ```bash Connector default at create theme={"dark"}
    curl -X POST 'https://api.hydradb.com/connectors' \
      -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
      -H "API-Version: 2" \
      -H "Content-Type: application/json" \
      -d '{
        "provider": "slack",
        "database": "acme_corp",
        "collection": "engineering",
        "provider_account_scope": "T12345ACME",
        "credentials": { "access_token": "xoxp-..." },
        "custom_instructions": "Prioritize decisions and owners; treat threads as engineering discussions."
      }'
    ```

    ```bash Resource override at configure theme={"dark"}
    curl -X POST 'https://api.hydradb.com/connectors/{id}/configure' \
      -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
      -H "API-Version: 2" \
      -H "Content-Type: application/json" \
      -d '{
        "resources": [
          {
            "resource_id": "C_INCIDENTS",
            "resource_type": "channel",
            "name": "incidents",
            "custom_instructions": "These are incident retros; extract root cause, impact, and owner."
          },
          { "resource_id": "C_RELEASES", "resource_type": "channel", "name": "releases" }
        ]
      }'
    ```

    ```bash Resource override later theme={"dark"}
    curl -X PATCH 'https://api.hydradb.com/connectors/{id}/resources/C_INCIDENTS' \
      -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
      -H "API-Version: 2" \
      -H "Content-Type: application/json" \
      -d '{ "custom_instructions": "These are incident retros; extract root cause, impact, and owner." }'
    ```
  </CodeGroup>

  In the configure call, `C_RELEASES` carries no instruction, so it inherits the connector default.
</Accordion>

In the dashboard, the **Instructions** dialog on a connector lists the connector default and every resource, each marked **override** or **inherits**, so you can see and edit both levels in one place.

## 3. Clear an instruction and read it back

To clear an instruction, send an explicit empty string. Omitting the field leaves the stored value unchanged; `""` removes it. Clearing a resource override returns that resource to the connector default.

<Accordion title="Clear a resource override: cURL">
  ```bash cURL theme={"dark"}
  curl -X PATCH 'https://api.hydradb.com/connectors/{id}/resources/C_INCIDENTS' \
    -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
    -H "API-Version: 2" \
    -H "Content-Type: application/json" \
    -d '{ "custom_instructions": "" }'
  ```
</Accordion>

Calling configure again without the field keeps an existing override, so routine reconfiguration never silently strips a tuned resource. Configure cannot clear an instruction; use the `PATCH` above.

To read instructions back, [`GET /connectors/{id}`](/api-reference/v2/endpoint/get-connector) returns the connector's `custom_instructions`, and [`GET /connectors/{id}/resources`](/api-reference/v2/endpoint/connector-resources) returns each resource's, absent when the resource inherits.

<a id="semantics-and-limits" />

## 4. Limits

* **Future syncs only:** instructions are read at sync time and stamped onto each document as it is ingested. Documents already indexed are not processed again; each keeps the instructions it was ingested under, recorded in its stored metadata.
* **4,000 characters:** counted in characters rather than bytes, so multi-byte scripts get the same budget. Longer values are rejected with a `400` and the stored value is left unchanged.
* **Cost:** the text rides the extraction and inference prompts for every synced document, so a long instruction on a high-volume connector is a recurring processing cost. Say what matters and stop.
* **Steering, not string rewriting:** instructions guide the language models that build the knowledge graph. Explicit, unambiguous instructions ("X was renamed to Y; they are the same product; index under Y") get the strongest adherence; vague guidance gets vague results. State each rule directly, name the exact terms, and keep unrelated rules as separate sentences.
* **No filtering or routing:** instructions do not change which documents sync, where they are stored, or who can read them. Use resource selection, [per-resource collections](/essentials/v2/multi-tenant), and [access rules](/essentials/v2/access-control) for those.

## Common mistakes

* **Expecting already-synced documents to change:** instructions apply from the next sync, and only to documents ingested from then on. Set them before the first sync when you can.
* **Expecting a resource instruction to add to the connector default:** it replaces it. Repeat anything from the default that the resource still needs.
* **Trying to clear an instruction through configure:** configure keeps an omitted `custom_instructions`. Send `""` with `PATCH /connectors/{id}/resources/{resource_id}` or `PATCH /connectors/{id}`.
* **Using an instruction to exclude content:** it steers interpretation only. Deselect the resource, or set an `acl`, instead.

## Related

* [Connectors](/essentials/v2/connectors): creating, configuring, and syncing connectors
* [Update Connector](/api-reference/v2/endpoint/update-connector) and [Update Connector Resource](/api-reference/v2/endpoint/update-connector-resource): the two endpoints that set instructions
* [App Sources](/essentials/v2/app-sources): the ingestion model connector objects use
* [Context Graphs](/essentials/v2/context-graphs): how extracted entities and relations are stored
* [Query](/essentials/v2/query): querying connector-synced data


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