App Sources

App sources are pre-parsed records from business applications: emails, chat messages, tickets, wiki pages, CRM objects, comments, and attachments. Use them when your connector already extracted the item’s text and structured fields. App sources are ingested through POST /context/ingest with the app_knowledge multipart field. The app-source payload is not a generic top-level content object. It uses the same app-native model as v1: kind, provider, external_id, fields, metadata, attachments, comments, and typed relations.

App sources land in the Knowledge store. Query them with POST /query, type: "knowledge" or type: "all", and query_apps: true. Use mode: "thinking" when you want app relation expansion and connected context.

1. What it is

	App source	File upload
Content	Pre-extracted app fields: Slack message body, Jira description, Notion page body, email body, etc.	Binary or text file (PDF, DOCX, MD, CSV, TXT)
Sent in	`app_knowledge` as a stringified JSON object or array	`documents` plus optional `document_metadata`
HydraDB does	Normalizes app identity, extracts searchable text from `fields`, indexes attachments/comments, and builds app graph links	Parses the file, chunks extracted text, and indexes it
Best for	Connectors and live app syncs	Documents in their original file format

Both paths eventually feed the same Knowledge retrieval stack, but app sources give HydraDB extra structure for app-aware recall: provider IDs, object kinds, actors, threads, parents, and explicit relations.

2. The mental model

Every app-source item becomes one HydraDB Knowledge source. The identity of the item comes from id, kind, provider, and external_id. The searchable app content lives in fields.

Category	Fields	Why it matters
Ingestion envelope	`id`, `database` (formerly `tenant_id`), `collection` (formerly `sub_tenant_id`)	Routes the item and gives it a stable upsert/delete/status ID.
Display / source metadata	`title`, `type`, `url`, `timestamp`	Improves citations, display, chronology, and source rendering.
App identity	`kind`, `provider`, `external_id`	Enables exact ID lookup, provider scoping, and relation resolution.
Searchable structure	`fields`	Holds the app-native body and typed fields: message body, ticket description, email actors, status, parent IDs, etc.
Filtering / bookkeeping	`metadata`, `additional_metadata`	Deterministic scoping and free-form display metadata.
Connected context	`relations`, `attachments`, `comments`	Adds explicit links and extra searchable text connected to the parent app item.

Do not put the primary app text in a top-level content object for app-native ingestion. Top-level content is the older generic knowledge payload; app sources should put text in the correct typed field:

`kind`	Main searchable text field
`email`	`fields.subject`, `fields.body`
`message`	`fields.body`
`ticket`	`fields.title`, `fields.description`
`knowledge_base`	`fields.title`, `fields.body`
`comment`	`fields.body`
`custom`	`fields.data`

3. Ingest an app source

Send app_knowledge as a JSON-stringified form value. Each item should include the request-level scope fields inside the item too; if supplied, they must match the form-level database and collection.

import json

result = client.context.ingest(
    type="knowledge",
    database="acme_corp",
    collection="default",
    app_knowledge=json.dumps([
        {
            "id": "slack_C01_1716213600_000100",
            "database": "acme_corp",
            "collection": "default",
            "title": "Auth rollback - thread root",
            "type": "slack",
            "kind": "message",
            "provider": "slack",
            "external_id": "1716213600.000100",
            "url": "https://acme.slack.com/archives/C01/p1716213600000100",
            "timestamp": "2026-05-20T10:00:00Z",
            "fields": {
                "kind": "message",
                "body": "The auth rollback notes are attached here.",
                "author": "alice",
                "thread_id": "1716213600.000100",
                "created_at": "2026-05-20T10:00:00Z",
                "url": "https://acme.slack.com/archives/C01/p1716213600000100",
            },
            "metadata": {"channel": "engineering", "workspace": "acme"},
            "additional_metadata": {"slack_ts": "1716213600.000100"},
            "attachments": [
                {
                    "id": "F012AUTH",
                    "title": "auth-rollback-notes.md",
                    "url": "https://files.slack.com/files-pri/T01-F012AUTH/auth-rollback-notes.md",
                    "content_type": "text/markdown",
                    "content": {
                        "markdown": "# Auth rollback\nRollback starts by disabling the new token refresh path."
                    },
                }
            ],
        }
    ]),
)

const result = await client.context.ingest({
  type: "knowledge",
  database: "acme_corp",
  collection: "default",
  appKnowledge: JSON.stringify([
    {
      id: "slack_C01_1716213600_000100",
      database: "acme_corp",
      collection: "default",
      title: "Auth rollback - thread root",
      type: "slack",
      kind: "message",
      provider: "slack",
      external_id: "1716213600.000100",
      url: "https://acme.slack.com/archives/C01/p1716213600000100",
      timestamp: "2026-05-20T10:00:00Z",
      fields: {
        kind: "message",
        body: "The auth rollback notes are attached here.",
        author: "alice",
        thread_id: "1716213600.000100",
        created_at: "2026-05-20T10:00:00Z",
        url: "https://acme.slack.com/archives/C01/p1716213600000100",
      },
      metadata: { channel: "engineering", workspace: "acme" },
      additional_metadata: { slack_ts: "1716213600.000100" },
      attachments: [
        {
          id: "F012AUTH",
          title: "auth-rollback-notes.md",
          url: "https://files.slack.com/files-pri/T01-F012AUTH/auth-rollback-notes.md",
          content_type: "text/markdown",
          content: {
            markdown: "# Auth rollback\nRollback starts by disabling the new token refresh path.",
          },
        },
      ],
    },
  ]),
});

curl -X POST 'https://api.hydradb.com/context/ingest' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  -F "type=knowledge" \
  -F "database=acme_corp" \
  -F "collection=default" \
  -F 'app_knowledge=[
    {
      "id": "slack_C01_1716213600_000100",
      "database": "acme_corp",
      "collection": "default",
      "title": "Auth rollback - thread root",
      "type": "slack",
      "kind": "message",
      "provider": "slack",
      "external_id": "1716213600.000100",
      "url": "https://acme.slack.com/archives/C01/p1716213600000100",
      "timestamp": "2026-05-20T10:00:00Z",
      "fields": {
        "kind": "message",
        "body": "The auth rollback notes are attached here.",
        "author": "alice",
        "thread_id": "1716213600.000100",
        "created_at": "2026-05-20T10:00:00Z",
        "url": "https://acme.slack.com/archives/C01/p1716213600000100"
      },
      "metadata": { "channel": "engineering", "workspace": "acme" },
      "additional_metadata": { "slack_ts": "1716213600.000100" },
      "attachments": [
        {
          "id": "F012AUTH",
          "title": "auth-rollback-notes.md",
          "url": "https://files.slack.com/files-pri/T01-F012AUTH/auth-rollback-notes.md",
          "content_type": "text/markdown",
          "content": { "markdown": "# Auth rollback\nRollback starts by disabling the new token refresh path." }
        }
      ]
    }
  ]'

Response:

{
  "success": true,
  "data": {
    "success": true,
    "message": "Knowledge uploaded successfully",
    "results": [
      { "id": "slack_C01_1716213600_000100", "filename": null, "status": "queued", "error": null }
    ],
    "success_count": 1,
    "failed_count": 0
  },
  "error": null,
  "meta": { "request_id": "...", "latency_ms": 8.4 }
}

The call returns 202 Accepted; the source is not queryable until GET /context/status reports indexing_status: "graph_creation" or "completed".

Multipart, not JSON. app_knowledge is nested JSON inside a multipart/form-data request. Stringify the object or array before sending it.

4. Incremental ingestion

Use the same endpoint for initial backfill and live updates. The important modeling choice is whether the provider event updates an existing source or creates a new source.

Provider event	What to send	Why
Ticket title/description/status changed	Re-ingest the same `kind: "ticket"` item with the same `id` and `external_id`, `upsert: true`	The ticket snapshot changed.
New Linear/Jira/Zendesk ticket comment	Ingest a new `kind: "comment"` source with its own `id` and `external_id`; put the parent ticket provider ID in `fields.parent_id`	The comment is a distinct provider object.
Edited ticket comment	Re-ingest the comment source with the same `id` and `external_id`	Same comment changed.
Deleted ticket comment	Call `DELETE /context` with the comment source `id`	The comment should no longer surface.
New Slack/Teams message	Ingest a new `kind: "message"` source with `fields.thread_id` and, when available, `fields.parent_id`	Messages are standalone events linked by provider IDs.
New email reply	Ingest a new `kind: "email"` source with `fields.thread_id` and `fields.reply_to_id`	Email replies have their own provider IDs, actors, body, and timestamp.
New Notion/Confluence page	Ingest a new `kind: "knowledge_base"` source	A page is a standalone document; the space belongs in metadata.
Existing Notion/Confluence page edited	Re-ingest the same page source with the same `id` and `external_id`	The page document changed.

upsert: true replaces the existing source with the same id. Do not upsert a parent ticket/page with only a new comments[] item unless you intend to replace the whole snapshot. For live webhook events, model each new comment as its own kind: "comment" source.

5. Per-app patterns

Slack message with thread reply and attachment

A Slack thread is multiple message sources connected by thread_id, parent_id, and optional explicit relations.

{
  "id": "slack_C01_1716213600_000100",
  "database": "acme_corp",
  "collection": "default",
  "title": "Auth rollback - thread root",
  "type": "slack",
  "kind": "message",
  "provider": "slack",
  "external_id": "1716213600.000100",
  "url": "https://acme.slack.com/archives/C01/p1716213600000100",
  "timestamp": "2026-05-20T10:00:00Z",
  "fields": {
    "kind": "message",
    "body": "The auth rollback notes are attached here.",
    "author": "alice",
    "thread_id": "1716213600.000100",
    "created_at": "2026-05-20T10:00:00Z",
    "url": "https://acme.slack.com/archives/C01/p1716213600000100"
  },
  "metadata": { "channel": "engineering", "workspace": "acme" },
  "attachments": [
    {
      "id": "F012AUTH",
      "title": "auth-rollback-notes.md",
      "url": "https://files.slack.com/files-pri/T01-F012AUTH/auth-rollback-notes.md",
      "content_type": "text/markdown",
      "content": { "markdown": "# Auth rollback\nRollback starts by disabling the new token refresh path." }
    }
  ]
}

For a reply, ingest a second source. fields.parent_id points to the parent message’s provider external_id; an explicit relation can point to either the parent HydraDB ID or the provider ID.

{
  "id": "slack_C01_1716213700_000200",
  "database": "acme_corp",
  "collection": "default",
  "title": "Re: Auth rollback - reply",
  "type": "slack",
  "kind": "message",
  "provider": "slack",
  "external_id": "1716213700.000200",
  "timestamp": "2026-05-20T10:01:40Z",
  "fields": {
    "kind": "message",
    "body": "Looking now - will pair with Bob in 10.",
    "author": "carol",
    "thread_id": "1716213600.000100",
    "parent_id": "1716213600.000100",
    "created_at": "2026-05-20T10:01:40Z"
  },
  "metadata": { "channel": "engineering", "workspace": "acme" },
  "relations": [
    {
      "predicate": "reply_to",
      "target": { "external_id": "1716213600.000100", "provider": "slack" }
    }
  ]
}

Jira ticket with linked issues

The ticket body lives in fields.description. Workflow fields belong in fields; scope/filter values like project and environment belong in metadata.

{
  "id": "jira_AUTH-123",
  "database": "acme_corp",
  "collection": "default",
  "title": "Login page returns 500",
  "type": "jira",
  "kind": "ticket",
  "provider": "jira",
  "external_id": "AUTH-123",
  "url": "https://jira.example.com/browse/AUTH-123",
  "timestamp": "2026-05-20T10:00:00Z",
  "fields": {
    "kind": "ticket",
    "title": "Login page returns 500",
    "description": "Invalid credentials return HTTP 500 instead of 401. Reproduces on staging and prod.",
    "status": "open",
    "priority": "high",
    "assignee": "alice",
    "reporter": "bob",
    "parent_id": "AUTH-100",
    "linked_issue_ids": ["AUTH-124", "AUTH-125"],
    "created_at": "2026-05-20T10:00:00Z",
    "url": "https://jira.example.com/browse/AUTH-123"
  },
  "metadata": { "project": "AUTH", "environment": "production" },
  "relations": [
    { "predicate": "child_of", "target": { "external_id": "AUTH-100", "provider": "jira" } },
    { "predicate": "linked_to", "target": { "external_id": "AUTH-124", "provider": "jira" } },
    { "predicate": "linked_to", "target": { "external_id": "AUTH-125", "provider": "jira" } }
  ]
}

Linear ticket comment

Comments are first-class app sources. Use fields.parent_id for the parent ticket’s provider ID. Use relations[] when you need a cross-provider link or want to declare the relation explicitly.

{
  "id": "linear_comment_c123",
  "database": "acme_corp",
  "collection": "default",
  "title": "Comment on AUTH-123",
  "type": "linear_comment",
  "kind": "comment",
  "provider": "linear",
  "external_id": "c123",
  "url": "https://linear.app/acme/issue/AUTH-123#comment-c123",
  "timestamp": "2026-05-25T07:00:00Z",
  "fields": {
    "kind": "comment",
    "body": "I found the repro steps. Attaching HAR.",
    "author": "[email protected]",
    "parent_id": "AUTH-123",
    "thread_id": "AUTH-123",
    "created_at": "2026-05-25T07:00:00Z",
    "url": "https://linear.app/acme/issue/AUTH-123#comment-c123"
  },
  "metadata": { "project": "AUTH" },
  "relations": [
    {
      "predicate": "comment_on",
      "target": { "external_id": "AUTH-123", "provider": "linear" }
    }
  ]
}

Notion / Confluence page

A page is one knowledge_base source. Space/workspace/database values belong in metadata, not in external_id.

{
  "id": "notion_page_abc",
  "database": "acme_corp",
  "collection": "default",
  "title": "Incident response runbook",
  "type": "notion",
  "kind": "knowledge_base",
  "provider": "notion",
  "external_id": "page_abc",
  "url": "https://notion.so/page_abc",
  "timestamp": "2026-05-25T07:00:00Z",
  "fields": {
    "kind": "knowledge_base",
    "title": "Incident response runbook",
    "body": "Steps to triage production incidents...",
    "parent_id": "space_eng_root",
    "created_by": "[email protected]",
    "updated_by": "[email protected]",
    "created_at": "2026-05-25T07:00:00Z",
    "updated_at": "2026-05-25T07:00:00Z",
    "url": "https://notion.so/page_abc"
  },
  "metadata": { "space": "Engineering", "doc_type": "runbook" }
}

Gmail email with reply

Each email message is its own email source. Link replies with fields.reply_to_id and, when useful, a reply_to relation.

{
  "id": "gmail_msg_19a2b3c",
  "database": "acme_corp",
  "collection": "default",
  "title": "Q4 launch plan",
  "type": "gmail",
  "kind": "email",
  "provider": "gmail",
  "external_id": "19a2b3c",
  "url": "https://mail.google.com/mail/u/0/#inbox/19a2b3c",
  "timestamp": "2026-05-20T09:00:00Z",
  "fields": {
    "kind": "email",
    "subject": "Q4 launch plan",
    "body": "Here is the updated plan...",
    "from": "[email protected]",
    "to": ["[email protected]"],
    "cc": ["[email protected]"],
    "thread_id": "thread_19a2",
    "reply_to_id": "19a1a00",
    "created_at": "2026-05-20T09:00:00Z",
    "url": "https://mail.google.com/mail/u/0/#inbox/19a2b3c"
  },
  "metadata": { "mailbox": "[email protected]" },
  "relations": [
    {
      "predicate": "reply_to",
      "target": { "external_id": "19a1a00", "provider": "gmail" }
    }
  ]
}

Salesforce opportunity linked to a support ticket

CRM records usually use kind: "custom". Use fields.parent_id for same-provider hierarchy, and relations[] for cross-app context.

{
  "id": "salesforce_opp_789",
  "database": "acme_corp",
  "collection": "default",
  "title": "Acme enterprise renewal",
  "type": "salesforce",
  "kind": "custom",
  "provider": "salesforce",
  "external_id": "opp_789",
  "url": "https://acme.lightning.force.com/lightning/r/Opportunity/opp_789/view",
  "timestamp": "2026-05-21T08:45:00Z",
  "fields": {
    "kind": "custom",
    "parent_id": "account_456",
    "thread_id": "opp_789_activity",
    "data": {
      "record_type": "opportunity",
      "name": "Acme enterprise renewal",
      "stage": "negotiation",
      "amount": "50000",
      "owner": "morgan"
    }
  },
  "metadata": { "pipeline": "enterprise-renewals", "region": "north-america" },
  "relations": [
    {
      "predicate": "linked_to",
      "target": { "external_id": "AUTH-123", "provider": "linear" },
      "properties": { "reason": "Customer renewal depends on auth fix" }
    }
  ]
}

6. Relations

Use relations[] to declare explicit source-to-source connections when the relationship matters for search and cannot be safely inferred from text alone.

{
  "relations": [
    {
      "predicate": "blocks",
      "target": {
        "external_id": "RELEASE-2026-05",
        "provider": "jira"
      },
      "properties": {
        "reason": "release blocker"
      }
    },
    {
      "predicate": "related_to",
      "target": {
        "id": "src_existing_source"
      }
    }
  ]
}

The target can use either shape:

Target shape	Use when
`{ "id": "..." }`	You already know the HydraDB ID.
`{ "external_id": "...", "provider": "..." }`	You know the provider ID and want HydraDB to resolve it in the provider namespace.

Useful predicates include:

Predicate	Direction
`reply_to`	reply/message/email → parent message/email
`comment_on`	comment → parent ticket/page/source
`forwarded_from`	forwarded email → original email
`child_of`	child ticket/page/custom record → parent
`linked_to`	source → related peer source
`blocks`	blocker → blocked item
`caused_by`	effect → cause
`related_to`	generic association

If you use target.external_id, include target.provider. External IDs are only unique inside a provider namespace.

For app sources, prefer the app-native relations[] shape above. relations.ids is the file/legacy forceful-relation shortcut and does not carry predicate or provider information.

7. Attachments and comments

Attachments and embedded comments[] add searchable child content connected to the app source. Use attachments[].content only when you already extracted the attachment text. HydraDB treats an attachment URL as metadata; it does not fetch arbitrary URLs from app-source payloads.

{
  "attachments": [
    {
      "id": "att-har-1",
      "title": "staging-login.har",
      "url": "https://...",
      "content_type": "application/json",
      "content": { "text": "HAR trace shows repeated 302 redirects after token refresh." },
      "properties": { "source": "linear", "comment_id": "c123" }
    }
  ],
  "comments": [
    {
      "id": "c-1",
      "author": "carol",
      "body": "Confirmed on staging.",
      "created_at": "2026-05-20T11:00:00Z"
    }
  ]
}

Use embedded comments[] for full backfill snapshots. For live incremental webhooks, prefer first-class kind: "comment" sources so a single new/edited/deleted comment can be handled without replacing the parent ticket or page.

8. Metadata: scoping vs display

For v2 Knowledge ingestion, metadata is the canonical filterable metadata field and additional_metadata is the canonical free-form metadata field.

Use `metadata` when	Use `additional_metadata` when
You want deterministic query-time filtering via `metadata_filters`	The field is for display, citation, debugging, or per-source bookkeeping
The key is declared in `database_metadata_schema` with `enable_match: true`	The key is unique or not worth adding to the database schema
Examples: `department`, `channel`, `project`, `space`, `pipeline`, `environment`, `region`	Examples: `slack_ts`, `ticket_key`, `comment_id`, `raw_provider_payload_id`, `golden_run`

Legacy aliases are accepted for compatibility in some request shapes:

Canonical v2 field	Legacy alias
`metadata`	`tenant_metadata`
`additional_metadata`	`document_metadata`

Filterable database metadata keys must be declared in the database schema with enable_match: true. Query-time filters use top-level keys for metadata and nested additional_metadata for free-form fields:

{
  "query": "auth rollback discussion",
  "metadata_filters": {
    "channel": "engineering",
    "additional_metadata": { "slack_ts": "1716213600.000100" }
  }
}

See Scoping using metadata for the full schema and filter rules.

9. How app sources affect query

When query_apps: true, HydraDB runs an app-aware retrieval lane alongside normal semantic and lexical retrieval. It can use app-specific signals that are not available from raw text alone.

Query signal	Uses
`kind`, `provider`	Routes queries such as “Slack messages”, “Jira tickets”, or “ticket comments”.
`external_id`	Exact ID lookup like `AUTH-123`, `1716213600.000100`, or `page_abc`.
Workflow fields	Uses `status`, `priority`, `assignee`, `reporter`, etc. when the query implies them.
Actors	Answers queries like “emails from Alice”, “tickets assigned to Bob”, or “comments by Carol”.
Thread and parent fields	Expands around replies, parents, children, epics, subtasks, accounts, deals, and pages.
`relations[]`	Traverses explicit links like `linked_to`, `blocks`, `comment_on`, `reply_to`, and `child_of`.
Attachments / comments	Searches extracted attachment text and embedded comment bodies.

Parent and child query

Parent/child query is based on provider-scoped external IDs. When a child source has fields.parent_id, HydraDB can match that value to another source’s external_id under the same provider. At recall time, query_apps: true lets the app-aware lane find an initial source by text, exact ID, actor, provider, or kind. In thinking mode, hierarchy language such as “parent”, “children”, “epic”, “subtask”, “account”, or “deal” can trigger expansion around the matched source.

{
  "database": "acme_corp",
  "query": "show me tickets linked to AUTH-123 and comments from Alice",
  "mode": "thinking",
  "query_apps": true,
  "max_results": 10
}

10. TLDR field reference

Top-level app source fields

Field	Why send it	Query / ingestion effect
	Stable HydraDB ID for this item.	Upsert key, delete/status/list ID, and direct relation target.
	Database that owns the item.	Must match the form-level `database` when present.
	Logical partition. Use `"default"` if you do not partition.	Must match the form-level `collection` when present.
	Human-readable subject, page name, ticket title, or message label.	Improves display, citations, and semantic matching.
	Source category such as `slack`, `gmail`, `jira`, `notion`, `salesforce`, or `linear_comment`.	Preserved for source rendering and analytics; not the app discriminator.
	App object kind.	Selects the app parser and query behavior.
	App namespace such as `slack`, `gmail`, `jira`, `notion`, `salesforce`, or `linear`.	Prevents ID collisions and scopes relation resolution.
	Stable provider ID for this exact item.	Exact lookup and relation/hierarchy resolution.
	Canonical link back to the provider item.	Improves citations and source navigation.
	Creation, sent, or last-updated time.	Helps chronology, display, and recency-aware ranking.
	Structured kind-specific content.	Primary app-native searchable payload.
	Schema-aligned filterable fields.	Queryable with top-level `metadata_filters` keys when declared in database schema.
	Free-form display/bookkeeping metadata.	Queryable under `metadata_filters.additional_metadata`.
	Explicit app-source links.	Enables connected-context retrieval and app graph expansion.
	Pre-extracted files attached to the item.	Attachment text is indexed and connected to the source.
	Embedded snapshot/backfill comments.	Comment text and authors become searchable.

`email` fields

Field	Why send it	Search / ingestion effect
	Discriminator inside `fields`.	Should match top-level `kind`.
	Email subject.	Improves title/snippet matching.
	Main email content.	Primary searchable text.
	Sender.	Actor queries like “emails from Alice”.
	Recipients.	Actor and recipient matching.
	CC recipients.	Additional actor context.
	Email thread ID.	Same-thread expansion.
	Parent email provider ID.	Reply traversal.
	Original forwarded email provider ID.	Forward traversal.
	Sent/created time.	Chronology and recency.
	Link back to the email.	Citations/navigation.

`message` fields

Field	Why send it	Search / ingestion effect
	Discriminator inside `fields`.	Should match top-level `kind`.
	Message text.	Primary searchable text.
	Sender.	Actor queries like “messages from Alice”.
	Thread/root conversation ID.	Same-thread expansion.
	Parent/replied-to message provider ID.	Reply/parent traversal.
	Mentioned people or handles.	Mention queries.
	Message timestamp.	Chronology and recency.
	Link back to the message.	Citations/navigation.

`ticket` fields

Field	Why send it	Search / ingestion effect
	Discriminator inside `fields`.	Should match top-level `kind`.
	Ticket title.	Display and matching.
	Ticket body.	Primary searchable text.
	Workflow state.	Queries like “open tickets”.
	Priority.	Priority-aware queries.
	Owner.	Actor queries.
	Reporter/creator.	Actor queries.
	Parent epic/ticket external ID.	Parent/child traversal.
	Related issue external IDs.	Linked-ticket context.
	Creation time.	Chronology.
	Last update time.	Freshness.
	Link back to the ticket.	Citations/navigation.

`knowledge_base` fields

Field	Why send it	Search / ingestion effect
	Discriminator inside `fields`.	Should match top-level `kind`.
	Page title.	Display and matching.
	Page body.	Primary searchable text.
	Parent page external ID.	Page hierarchy traversal.
	Creator.	Actor queries.
	Last editor.	Actor queries.
	Creation time.	Chronology.
	Last update time.	Freshness.
	Link back to the page.	Citations/navigation.

`comment` fields

Field	Why send it	Search / ingestion effect
	Discriminator inside `fields`.	Should match top-level `kind`.
	Comment body.	Primary searchable text.
	Comment author.	Actor queries.
	Parent source external ID in the same provider namespace.	`comment_on` relation derivation.
	Shared discussion/activity thread ID.	Same-thread expansion.
	Creation time.	Chronology.
	Last update time.	Freshness.
	Link back to the comment.	Citations/navigation.
	Provider-specific comment details.	Preserved in payload.

`custom` fields

Field	Why send it	Search / ingestion effect
	Discriminator inside `fields`.	Should match top-level `kind`.
	Parent external ID for same-provider hierarchy.	Parent/child traversal.
	Activity stream or conversation ID.	Same-thread expansion.
	App-specific structured payload.	Searchable business/system details.

Relation fields

Field	Why send it	Search / ingestion effect
	Relationship name such as `linked_to`, `blocks`, `child_of`, `reply_to`, or `comment_on`.	Lets query expansion understand relation type and direction.
	Direct HydraDB ID target.	Connects to a known source.
	Provider ID target.	Resolves by app namespace.
	Provider namespace for `external_id`.	Prevents false links across apps.
	Optional relation metadata.	Preserves why the link exists.

Attachment fields

Field	Why send it	Search / ingestion effect
	Stable attachment ID.	Deduplication and display.
	File name/title.	Matching and display.
	Link back to attachment.	Citations/navigation.
	MIME type.	Classification.
	Attachment size.	Display/debugging.
	Pre-extracted plain text.	Indexed as attachment text.
	Pre-extracted Markdown.	Indexed as attachment text.
	Provider-specific attachment metadata.	Preserved in payload.

11. Common mistakes

Mistake	Why it breaks	Fix
Sending a generic `content: { "text": "..." }` payload for app-native data	App-specific parsing cannot see `kind`, `provider`, `external_id`, actors, thread IDs, parent IDs, or typed body fields	Use `kind`, `provider`, `external_id`, and `fields`.
Putting the main text outside `fields`	App-source extraction and query expansion lose structure	Put text in `fields.body`, `fields.description`, `fields.title`, or `fields.data` depending on `kind`.
Using container IDs as `external_id`	Relations and exact lookup point to the channel/project/space instead of the item	Use the individual item ID as `external_id`; put channel/project/space in `metadata`.
Omitting `provider` on a relation target	External IDs collide across apps	Include `target.provider` whenever you use `target.external_id`.
Re-ingesting a whole Slack thread for every reply	Loses message-level authorship/timestamps and wastes indexing	Ingest each message as its own `kind: "message"` source with `thread_id` / `parent_id`.
Sending only a new ticket comment in `comments[]` during an upsert	Replaces the parent snapshot and may drop existing content	Ingest live comments as first-class `kind: "comment"` sources.
Putting filterable fields only in `additional_metadata`	Filters are slower and require nested filter syntax	Put hot filters in `metadata` and declare them in the database schema.
Forgetting `query_apps: true`	You only get normal text/vector retrieval, not app-aware ID/relation expansion	Set `query_apps: true`; use `mode: "thinking"` for relation-heavy queries.

Knowledge - the broader ingestion path
Memories - the per-user counterpart
Query - retrieving app-source context
Scoping using metadata - designing filterable metadata
Context Graphs - graph enrichment and traversal
Ingest Content - API Reference
Ingestion Status - API Reference

Get Started

Usage

Concepts

Plugins

For Agents

1. What it is

2. The mental model

3. Ingest an app source

4. Incremental ingestion

5. Per-app patterns

Slack message with thread reply and attachment

Jira ticket with linked issues

Linear ticket comment

Notion / Confluence page

Gmail email with reply

Salesforce opportunity linked to a support ticket

6. Relations

7. Attachments and comments

8. Metadata: scoping vs display

9. How app sources affect query

Parent and child query

10. TLDR field reference

Top-level app source fields

`email` fields

`message` fields

`ticket` fields

`knowledge_base` fields

`comment` fields

`custom` fields

Relation fields

Attachment fields

11. Common mistakes

​1. What it is

​2. The mental model

​3. Ingest an app source

​4. Incremental ingestion

​5. Per-app patterns

​Slack message with thread reply and attachment

​Jira ticket with linked issues

​Linear ticket comment

​Notion / Confluence page

​Gmail email with reply

​Salesforce opportunity linked to a support ticket

​6. Relations

​7. Attachments and comments

​8. Metadata: scoping vs display

​9. How app sources affect query

​Parent and child query

​10. TLDR field reference

​Top-level app source fields

​email fields

​message fields

​ticket fields

​knowledge_base fields

​comment fields

​custom fields

​Relation fields

​Attachment fields

​11. Common mistakes

​Related

1. What it is

2. The mental model

3. Ingest an app source

4. Incremental ingestion

5. Per-app patterns

Slack message with thread reply and attachment

Jira ticket with linked issues

Linear ticket comment

Notion / Confluence page

Gmail email with reply

Salesforce opportunity linked to a support ticket

6. Relations

7. Attachments and comments

8. Metadata: scoping vs display

9. How app sources affect query

Parent and child query

10. TLDR field reference

Top-level app source fields

`email` fields

`message` fields

`ticket` fields

`knowledge_base` fields

`comment` fields

`custom` fields

Relation fields

Attachment fields

11. Common mistakes

Related