---
canonical_url: "https://docs.composio.dev/toolkits/hydradb"
markdown_url: "https://docs.composio.dev/toolkits/hydradb.md"
product: "platform"
version: null
last_updated: null
---

# HydraDB

HydraDB is a hosted context layer for ingesting, connecting, and querying data for AI applications.

- **Category:** databases
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 43
- **Triggers:** 0
- **Slug:** `HYDRADB`
- **Version:** 00000000_00

## Tools

### Add Connector Resource

**Slug:** `HYDRADB_ADD_CONNECTOR_RESOURCE`

Add one discovered provider resource to an existing connector with optional routing, filters, metadata, instructions, and access control.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `acl` | array | No | Principals allowed to read objects synced from this resource. Omit for unrestricted access. |
| `filters` | object | No | Provider-specific sync filters, such as lookback_days. |
| `metadata` | object | No | Database-schema metadata merged into every synced object, up to 16 KiB of compact JSON. |
| `resource_id` | string | Yes | Provider resource identifier returned by Discover Connector Resources. |
| `connector_id` | string | Yes | Connector ID to receive the resource. |
| `display_name` | string | No | Human-readable name for this resource. |
| `resource_type` | string | No | Provider resource type returned by discovery, such as channel, repository, or linear_team. |
| `database_override` | string | No | Database for this resource's synced objects. Omit or send an empty string to use the connector database. |
| `additional_metadata` | object | No | Free-form metadata merged into every synced object, up to 1 KiB of compact JSON. |
| `collection_override` | string | No | Collection for this resource's synced objects. Omit or send an empty string to use the connector collection. |
| `custom_instructions` | string | No | Resource-specific ingestion and indexing instructions. An empty string inherits the connector instructions. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Add Metadata Schema Fields

**Slug:** `HYDRADB_ADD_METADATA_SCHEMA_FIELDS`

Add new fields to a database metadata schema; existing fields cannot be deleted, renamed, retyped, or reconfigured.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `fields` | array | Yes | New metadata fields to add. Existing fields cannot be deleted, renamed, retyped, or reconfigured. |
| `database` | string | Yes | Database whose metadata schema to extend. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Configure Connector Resources

**Slug:** `HYDRADB_CONFIGURE_CONNECTOR_RESOURCES`

Activate selected discovered resources on a connector and start their sync; unlisted existing resources remain unchanged.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `resources` | array | Yes | Discovered resources to activate. Existing resources omitted from this list remain unchanged. |
| `connector_id` | string | Yes | Connector ID to configure. |
| `lookback_days` | integer | No | Days of history for the first sync; ranges above 30 may continue as a background backfill. |
| `table_configs` | array | No | Per-table replication settings for table-sync connectors such as BigQuery; other connector types reject this field. |
| `full_visibility_roles` | array | No | HubSpot-only roles whose members can see every record. Omit to keep the setting; send an empty list to clear it. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Connector

**Slug:** `HYDRADB_CREATE_CONNECTOR`

Create a HydraDB connector and store the provider authorization required to sync one external account. Obtain the provider-specific shape from List Connector Providers.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Human-readable connector label. |
| `database` | string | Yes | Database that receives synchronized data. |
| `provider` | string | Yes | Provider ID returned by List Connector Providers. |
| `auth_type` | string | No | Provider authentication method, such as oauth. |
| `collection` | string | No | Default collection for synchronized data. |
| `custom_instructions` | string | No | Default ingestion instructions. |
| `sync_interval_seconds` | integer | No | Scheduled sync interval in seconds; omit or send 0 for the provider default. |
| `provider_account_scope` | string | No | External account identifier used to avoid collisions across provider accounts. |
| `provider_authorization` | object | No | Provider-specific authorization object matching the credential_schema returned by List Connector Providers. Sent to HydraDB as credentials, treated as secret, and never returned. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Database

**Slug:** `HYDRADB_CREATE_DATABASE`

Provision a HydraDB database asynchronously. This may create billable infrastructure; poll Get Database Status before ingestion.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `confirm` | boolean | Yes | Must be true to confirm this consequential operation. |
| `database` | string | Yes | Unique database name to provision. |
| `embeddings_dimension` | integer | No | Embedding vector dimension override. Omit to use HydraDB's default of 1536. |
| `database_metadata_schema` | array | No | Optional immutable metadata fields to create with the database. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Collection

**Slug:** `HYDRADB_DELETE_COLLECTION`

Permanently delete one HydraDB collection and all of its data while leaving the database intact.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `confirm` | boolean | Yes | Must be true to confirm this consequential operation. |
| `database` | string | Yes | Database containing the collection. |
| `collection` | string | Yes | Collection to permanently delete with all of its data. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Connector

**Slug:** `HYDRADB_DELETE_CONNECTOR`

Permanently delete a HydraDB connector, all resource mappings, and its stored provider authorization.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `confirm` | boolean | Yes | Must be true to confirm this consequential operation. |
| `connector_id` | string | Yes | Connector to permanently delete with its resource mappings and stored provider authorization. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Connector Resource

**Slug:** `HYDRADB_DELETE_CONNECTOR_RESOURCE`

Permanently remove one resource mapping from a HydraDB connector.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `confirm` | boolean | Yes | Must be true to confirm this consequential operation. |
| `resource_id` | string | Yes | Resource mapping to permanently remove. |
| `connector_id` | string | Yes | Connector containing the resource mapping. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Context

**Slug:** `HYDRADB_DELETE_CONTEXT`

Permanently delete specific HydraDB knowledge or memory contexts. Uses strict provider status handling so missing, indexing, and store failures cannot appear successful.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `ids` | array | Yes | Exact context IDs to permanently delete. |
| `type` | string ("knowledge" | "memory" | "all") | No | Corpus from which to delete the contexts. |
| `confirm` | boolean | Yes | Must be true to confirm this consequential operation. |
| `database` | string | Yes | Database containing the contexts. |
| `collection` | string | No | Collection containing the contexts; omit for the default. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Database

**Slug:** `HYDRADB_DELETE_DATABASE`

Permanently delete a HydraDB database and all associated data. This cannot be undone.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `confirm` | boolean | Yes | Must be true to confirm this consequential operation. |
| `database` | string | Yes | Database to permanently delete with all associated data. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Indexing Webhook

**Slug:** `HYDRADB_DELETE_INDEXING_WEBHOOK`

Unregister the account's indexing webhook and stop all future event deliveries.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `confirm` | boolean | Yes | Must be true to confirm this consequential operation. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Disable Webhook Signing

**Slug:** `HYDRADB_DISABLE_WEBHOOK_SIGNING`

Remove the indexing webhook signing secret. Future deliveries remain enabled but can no longer be authenticated with HydraDB signatures.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `confirm` | boolean | Yes | Must be true to confirm this consequential operation. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Discover Connector Resources

**Slug:** `HYDRADB_DISCOVER_CONNECTOR_RESOURCES`

List resources available through an existing connector's stored provider credentials. Discovery pagination is provider-dependent (currently Notion only); other providers may return the complete list despite limit. This may call the external provider.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Requested maximum resources for providers that support discovery pagination (currently Notion). Other providers may return the complete resource list. |
| `cursor` | string | No | Opaque next_cursor from a provider-paginated response; omit for the first page or for providers that return a complete list. |
| `connector_id` | string | Yes | Connector ID whose provider resources to discover. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Generate or Set Webhook Signing Secret

**Slug:** `HYDRADB_GENERATE_WEBHOOK_SIGNING_SECRET`

Generate or set and replace the indexing webhook signing secret. The previous secret stops working immediately and the active secret is returned only once.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `confirm` | boolean | Yes | Must be true to confirm this consequential operation. |
| `signing_secret` | string | No | Caller-owned signing secret of at least 16 characters. Omit to have HydraDB generate one. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Connector

**Slug:** `HYDRADB_GET_CONNECTOR`

Get one connector's configuration and lifecycle state by connector ID.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `connector_id` | string | Yes | Connector ID returned by List Connectors. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Connector Status

**Slug:** `HYDRADB_GET_CONNECTOR_STATUS`

Check a connector's overall health, sync state, errors, and per-resource health in one call.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `connector_id` | string | Yes | Connector ID to check. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Context Relations

**Slug:** `HYDRADB_GET_CONTEXT_RELATIONS`

Return extracted entity relations for one context or an entire collection, one page at a time.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `acl` | array | No | Principals to answer as; only relations visible to them are returned. Omit for no access scoping. |
| `type` | string ("knowledge" | "memory") | No | Corpus to read: knowledge or memory. |
| `limit` | integer | No | Maximum relation groups to return on this page. |
| `cursor` | string | No | Exact next_cursor from the previous page; pass numeric or string values back unchanged. |
| `database` | string | Yes | Database to read. |
| `collection` | string | No | Collection to read; omit it to use the database's default collection. |
| `context_id` | string | No | Context whose relations to return; omit it for the entire collection. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Context Status

**Slug:** `HYDRADB_GET_CONTEXT_STATUS`

Check processing status for one or more ingested or connector-synced context IDs.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `database` | string | Yes | Database containing the contexts. |
| `collection` | string | No | Collection containing the contexts; omit it to use the database's default collection. |
| `context_ids` | array | Yes | One or more context IDs to check, sent as one comma-separated ids query parameter. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Context Subgraph

**Slug:** `HYDRADB_GET_CONTEXT_SUBGRAPH`

Traverse context-level relations from one context and return reachable contexts and graph evidence up to bounded depth and size.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `acl` | array | No | Principals to answer as; visibility is checked at every hop. Omit for no access scoping. |
| `type` | string ("knowledge" | "memory") | No | Corpus to traverse: knowledge or memory. |
| `depth` | integer | No | Maximum relation hops from the starting context (1-10). |
| `database` | string | Yes | Database to traverse. |
| `collection` | string | No | Collection to traverse; omit it to use the database's default collection. |
| `context_id` | string | Yes | Starting context ID, including an ID containing slashes. |
| `max_sources` | integer | No | Maximum contexts to return (1-1000); is_truncated reports whether this cut traversal short. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Database Stats

**Slug:** `HYDRADB_GET_DATABASE_STATS`

Get knowledge and memory collection row counts for one database.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `database` | string | Yes | Database whose collection statistics to return. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Database Status

**Slug:** `HYDRADB_GET_DATABASE_STATUS`

Check whether one database's scheduler, graph, and vector infrastructure is ready for ingestion.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `database` | string | Yes | Database whose infrastructure status to check. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Indexing Webhook

**Slug:** `HYDRADB_GET_INDEXING_WEBHOOK`

Get the account's indexing webhook URL, subscribed event types, registration state, and whether signing is configured.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Metadata Schema

**Slug:** `HYDRADB_GET_METADATA_SCHEMA`

Get the declared metadata fields and types for one database.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `database` | string | Yes | Database whose metadata schema to read. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Webhook Delivery

**Slug:** `HYDRADB_GET_WEBHOOK_DELIVERY`

Get one indexing webhook delivery attempt by delivery ID for failure diagnosis.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `delivery_id` | string | Yes | Delivery ID returned by List Webhook Deliveries. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Ingest Context

**Slug:** `HYDRADB_INGEST_CONTEXT`

Ingest documents, app knowledge, memories, or an explicit graph into a HydraDB database and return context IDs for asynchronous status checks.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string ("knowledge" | "memory") | No | Corpus to ingest into: knowledge for documents or app content; memory for memories. Graph payloads work with either corpus. |
| `upsert` | boolean | No | Whether to replace an existing context that has the same context ID. |
| `database` | string | Yes | Database to ingest into. |
| `memories` | string | No | JSON array of memory entries. Each entry requires text or user_assistant_pairs and may include id, title, infer, metadata, and additional_metadata. Requires type=memory. |
| `documents` | array | No | Document files to ingest into the knowledge corpus, in submission order. |
| `collection` | string | No | Collection to ingest into. Omit it to use the database's default collection. |
| `app_knowledge` | string | No | JSON array of pre-extracted app knowledge entries. Each entry should include stable identity and searchable content. |
| `graph_payload` | string | No | JSON object containing an explicit graph keyed by source ID. |
| `document_metadata` | string | No | JSON array with one metadata item per uploaded document. Each item may contain id, metadata, additional_metadata, and relations. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Inspect Context

**Slug:** `HYDRADB_INSPECT_CONTEXT`

Fetch one context's stored content, enrichment, and/or a time-limited download URL.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `acl` | array | No | Principals to answer as; the context must be visible to them. Omit for no access scoping. |
| `mode` | string ("content" | "url" | "both") | No | Return stored content, a time-limited download URL, or both. |
| `database` | string | Yes | Database containing the context. |
| `collection` | string | No | Collection containing the context; omit it to use the database's default collection. |
| `context_id` | string | Yes | Context ID to inspect. |
| `expiry_seconds` | integer | No | Lifetime of the returned download URL in seconds (60-604800). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Collections

**Slug:** `HYDRADB_LIST_COLLECTIONS`

List the collections in one HydraDB database.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `database` | string | Yes | Database whose collections to list. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Connector Providers

**Slug:** `HYDRADB_LIST_CONNECTOR_PROVIDERS`

List supported connector providers, or describe one provider's resource types, credential schema, and setup requirements.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `provider` | string | No | Provider slug to describe in detail, such as slack or gmail. Omit to list the provider catalog. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Connector Resources

**Slug:** `HYDRADB_LIST_CONNECTOR_RESOURCES`

List the resources currently configured on a connector, including routing, filters, access controls, and per-resource health metadata.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `connector_id` | string | Yes | Connector ID whose configured resources to list. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Connectors

**Slug:** `HYDRADB_LIST_CONNECTORS`

List the connected data providers in the account, optionally filtered by provider, with optional health rollups.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `provider` | string | No | Provider slug to filter by, such as github or slack. |
| `include_health` | boolean | No | Whether to include the health rollup keyed by connector ID. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Contexts

**Slug:** `HYDRADB_LIST_CONTEXTS`

List knowledge or memory contexts in a database or collection, one bounded page at a time.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `acl` | array | No | Principals to answer as; only contexts visible to them are listed. Omit for no access scoping. |
| `ids` | array | No | Context IDs to restrict the list to, at most 100. |
| `page` | integer | No | Page number to fetch, starting at 1. Pass a response next_cursor here to continue. |
| `type` | string ("knowledge" | "memory" | "all") | No | Corpus to list: knowledge, memory, or all for both. |
| `filters` | object | No | Exact-match metadata, additional-metadata, and built-in field filters; all supplied pairs must match. |
| `database` | string | Yes | Database whose contexts to list. |
| `page_size` | integer | No | Maximum contexts to return on this page. |
| `collection` | string | No | Collection to list; omit for the database default collection. |
| `group_threads` | boolean | No | Whether to nest comments and replies under their parent context instead of listing separate rows. |
| `include_fields` | array | No | Fields to return in addition to id, database, and collection. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Databases

**Slug:** `HYDRADB_LIST_DATABASES`

List HydraDB databases and preserve per-database provisioning or failure diagnostics.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Webhook Deliveries

**Slug:** `HYDRADB_LIST_WEBHOOK_DELIVERIES`

List recent indexing webhook delivery attempts, optionally filtered by status, one page at a time.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum delivery attempts to return on this page. |
| `cursor` | string | No | Opaque next_cursor from the previous page; omit for the first page. |
| `status` | string | No | Delivery status to filter by; omit to return deliveries in any status. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Query Context

**Slug:** `HYDRADB_QUERY_CONTEXT`

Search a HydraDB database for ranked chunks and graph context, with optional collection, metadata, source, ACL, and retrieval controls.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `acl` | array | No | Principals to query as. Omit, use an empty list, or use ['*'] for no access scoping. |
| `ids` | array | No | Source or memory IDs to search within, at most 200. If none match, the query returns no matches. |
| `mode` | string ("fast" | "thinking" | "auto") | No | Recall mode: fast, thinking, or auto. Thinking mode always includes graph context. |
| `type` | string ("knowledge" | "memory" | "all") | No | Context corpus to search: knowledge, memory, or all. |
| `alpha` | string | No | Hybrid-search balance: auto or a numeric weight from 0 to 1. |
| `query` | string | Yes | Non-empty natural-language search query. |
| `titles` | array | No | Exact document titles to search within, matched case-insensitively and ORed. Intersects with ids when both are supplied. |
| `database` | string | Yes | Database to query. |
| `operator` | string ("or" | "and" | "phrase") | No | How query terms or paths are combined: or, and, or phrase. |
| `query_by` | string ("hybrid" | "text") | No | Retrieval method: hybrid or text. |
| `collection` | string | No | Single collection to search; omit it to use the default collection. Do not combine with collections. |
| `query_apps` | boolean | No | Whether to enable app-aware retrieval while searching the selected knowledge. |
| `code_search` | boolean | No | Force repository code search on or off; omit it to let HydraDB decide. |
| `collections` | string | No | One to 100 collection IDs, or a mapping of one to 100 collection IDs to positive ranking weights in 0.1 increments. Do not combine with collection. |
| `max_results` | integer | No | Maximum number of ranked chunks to return. |
| `recency_bias` | number | No | Recency ranking boost from 0 to 1; zero disables it. |
| `graph_context` | boolean | No | Whether fast mode includes graph context. Thinking mode always includes it. |
| `response_format` | string ("default" | "structured" | "markdown") | No | Output format. Default returns structured results with llm_prompt; structured omits llm_prompt; markdown returns one Markdown string. |
| `metadata_filters` | object | No | ANDed metadata filters. Values may be scalars, lists, or contains, contains_any, and equals objects; lists may contain at most 500 values and the complete filter may be at most 64 KiB. |
| `additional_context` | string | No | Context prepended to the query to improve retrieval relevance. |
| `num_related_chunks` | integer | No | Number of adjacent chunks to include around each matched chunk. |
| `temporal_reasoning` | boolean | No | Whether to resolve time-based questions using dated facts. |
| `query_forceful_relations` | boolean | No | Whether thinking mode follows relations declared at ingestion and returns their chunks as additional context. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Register Indexing Webhook

**Slug:** `HYDRADB_REGISTER_INDEXING_WEBHOOK`

Register or replace the organization's HTTPS endpoint and event subscriptions for HydraDB indexing events. This call can preserve the existing signing secret, generate and return a new one, or install a caller-supplied secret.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | Yes | HTTPS endpoint owned by the caller that will receive indexing events. |
| `confirm` | boolean | Yes | Must be true to confirm this consequential operation. |
| `event_types` | array | Yes | Indexing event types to deliver, such as indexing.status_changed. |
| `signing_secret` | string | No | Caller-owned signing secret of at least 16 characters. Treated as secret and never echoed from the request. |
| `generate_signing_secret` | boolean | No | Generate a new signing secret and return it once in this response. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Retry Webhook Delivery

**Slug:** `HYDRADB_RETRY_WEBHOOK_DELIVERY`

Queue one failed indexing webhook delivery for another attempt. This repeats an external callback and may repeat downstream side effects.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `confirm` | boolean | Yes | Must be true to confirm this consequential operation. |
| `delivery_id` | string | Yes | Failed or permanently failed delivery ID returned by List Webhook Deliveries. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Set Connector Paused State

**Slug:** `HYDRADB_SET_CONNECTOR_PAUSED`

Pause scheduled syncs or resume a paused HydraDB connector. Resuming immediately schedules a sync from the connector's saved positions.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `paused` | boolean | Yes | True to pause scheduled syncs; false to resume and immediately schedule a sync from the connector's saved positions. |
| `connector_id` | string | Yes | Connector ID whose scheduling state to change. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Submit Query Feedback

**Slug:** `HYDRADB_SUBMIT_QUERY_FEEDBACK`

Record a rating, comment, or known ground truth for a prior HydraDB query. This optional signal does not change the original query result. HydraDB allows 100 feedback submissions per minute per organization; if rate limited, skip the report rather than retrying in a loop.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `rating` | string ("positive" | "negative" | "neutral") | No | Optional overall judgment: positive, negative, or neutral. Omit it to submit feedback without a rating. |
| `source` | string ("user" | "agent") | No | Submitter type: user for human feedback or agent for agent feedback. |
| `database` | string | No | Owning database when scoping this feedback. |
| `feedback` | string | No | Specific explanation of what was right or wrong about the query result. Required unless ground_truth is supplied. |
| `metadata` | object | No | Up to 20 string key-value pairs of context, such as agent, conversation, or evaluation-run identifiers. Keys are at most 64 characters and values at most 512 characters. |
| `collection` | string | No | Owning collection. database is required when collection is supplied. |
| `request_id` | string | Yes | meta.request_id from the successful HydraDB query being evaluated. |
| `ground_truth` | object | No | Known correct answer, context source IDs containing it, or both. Do not guess ground truth. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Test Indexing Webhook

**Slug:** `HYDRADB_TEST_INDEXING_WEBHOOK`

Send one test event to the currently registered indexing webhook endpoint.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `confirm` | boolean | Yes | Must be true to confirm this consequential operation. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Trigger Connector Sync

**Slug:** `HYDRADB_TRIGGER_CONNECTOR_SYNC`

Start a connector sync now, causing external provider reads and HydraDB ingestion. If a sync is already running, it continues; paused connectors and connectors without active resources fail.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `connector_id` | string | Yes | Active connector ID to sync. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Connector

**Slug:** `HYDRADB_UPDATE_CONNECTOR`

Update an existing HydraDB connector's sync cadence, default ingestion instructions, or provider credentials. Replacing credentials requires explicit confirmation.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `connector_id` | string | Yes | Connector ID to update. |
| `custom_instructions` | string | No | New default ingestion instructions for resources without their own instructions. Send an empty string to clear them. |
| `sync_interval_seconds` | integer | No | New scheduled sync interval in seconds. Provider-specific bounds apply; send 0 to select the provider default. |
| `provider_authorization` | object | No | Replacement provider authorization matching the provider credential schema. Sent to HydraDB as credentials to reconnect, treated as secret, and never returned. |
| `confirm_credentials_replacement` | boolean | No | Must be the boolean value true when credentials are supplied, confirming that the previous provider authorization will stop working immediately. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Connector Resource

**Slug:** `HYDRADB_UPDATE_CONNECTOR_RESOURCE`

Replace a HydraDB connector resource's access rules or change its ingestion instructions for subsequent syncs.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `acl` | array | No | Complete replacement access list. Send an empty list to allow nobody, or ["__public__"] to allow every identified caller; omit to leave unchanged. |
| `resource_id` | string | Yes | Configured resource ID to update. |
| `connector_id` | string | Yes | Connector ID containing the resource. |
| `custom_instructions` | string | No | Resource-specific ingestion and indexing instructions applied from the next sync. Send an empty string to clear them back to the connector default; omit to leave unchanged. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Context Metadata

**Slug:** `HYDRADB_UPDATE_CONTEXT_METADATA`

Merge metadata into one HydraDB context or replace its access-control list without re-ingesting content.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `acl` | array | No | Complete ACL replacement. Send an empty list or null to make the context private, or ["__public__"] to make it public; omit to leave it unchanged. |
| `database` | string | Yes | Database containing the context. |
| `collection` | string | Yes | Collection containing the context; this endpoint does not default it. |
| `context_id` | string | Yes | Context ID to update. |
| `database_metadata` | object | No | Schema-declared metadata values to merge, up to 16 KiB as compact JSON. Omit to leave these values unchanged. |
| `additional_metadata` | object | No | Free-form metadata values to merge, up to 1 KiB as compact JSON. Omit to leave these values unchanged. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |
