{
  "components": {
    "schemas": {
      "connectors.Resource": {
        "properties": {
          "acl": {
            "description": "ACL is the customer-declared access-control list stamped onto every\nobject synced from this resource (PRO-1684; see internal/domain/acl).\nStored in caller-supplied form and normalized at transform time. nil\nmeans no ACL, documents stay unrestricted. Provider-derived ACLs\n(Phase 2) take precedence over this when the provider supports them.",
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false
          },
          "acl_fingerprint": {
            "description": "ACLFingerprint is the stable identity of the ACL last APPLIED to this\nresource's already-indexed documents (PRO-1684). The sync compares the\nfreshly-resolved provider ACL against it: equal means nothing to do,\ndifferent means fan the new ACL out to existing documents. Empty means\nnothing has been applied yet (first capture-enabled sync).",
            "type": "string"
          },
          "acl_warning": {
            "description": "ACLWarning explains, in the provider's own words, why this resource's\npermissions could not be captured. Capture fails OPEN, so the resource\nis readable by everyone while this is set; without surfacing it, that\nwidening would be invisible to the person who turned RBAC on. Cleared\nautomatically by the next successful capture.",
            "type": "string"
          },
          "acl_warning_at": {
            "description": "ACLWarningAt is when this warning last CHANGED (RFC3339). An unchanged\nwarning is not rewritten each cycle, so it reads as \"open since\".",
            "type": "string"
          },
          "additional_metadata": {
            "additionalProperties": {},
            "description": "AdditionalMetadata is merged into the additional_metadata (document\nmetadata) layer of every object synced from this resource. User-supplied\nkeys are shallow-merged as the base; provider-generated fields are\napplied on top and always win on conflict.",
            "example": {
              "author": "ada",
              "doc_version": 3
            },
            "type": "object"
          },
          "backfill_chunk_interval_seconds": {
            "description": "BackfillChunkIntervalSeconds is the pacing interval persisted at configure\ntime so the scheduler can thread it into each chunk's workflow input.",
            "example": 86400,
            "type": "integer"
          },
          "backfill_floor": {
            "description": "BackfillFloor is the fixed oldest boundary the historical crawl is working\ntowards, stamped once at configure time as now-lookback_days.\n\nIt exists because the floor used to be recomputed per chunk from the\nworkflow's own clock, which made it a *moving* target: every hour the\ncrawl was delayed, the boundary advanced an hour with it. A connector\npaused mid-backfill (PRO-1762) makes that trivially reachable — pause for\nlonger than the crawl has left and it resumes, finds backfill_oldest\nalready at or past the recomputed floor, declares itself complete and\nclears the marker. The remaining history is never fetched and nothing\nreports it missing. Anchoring the boundary is what makes \"backfill 30\ndays\" mean 30 days from when it was asked for, however long the crawl\ntakes.\n\nEmpty on rows configured before this field existed; the workflow falls\nback to the old now-relative computation for those, so their behaviour is\nunchanged rather than silently altered by a deploy.",
            "type": "string"
          },
          "backfill_next_chunk_at": {
            "description": "BackfillNextChunkAt is the RFC3339 time the next chunk becomes due. The\nbackfill workflow processes one chunk then sets this to now+interval and\nexits; the connector scheduler starts the next chunk once it passes.",
            "type": "string"
          },
          "backfill_oldest": {
            "description": "BackfillOldest is an RFC3339 timestamp marking the oldest boundary remaining\nfor async historical backfill. Empty means backfill is complete or not needed.",
            "example": "2026-06-01T00:00:00Z",
            "type": "string"
          },
          "backfill_status": {
            "description": "BackfillStatus gates the sparse ResourcesByBackfillNextChunkAt GSI: it is\nset to BackfillStatusActive while a historical backfill is in progress and\nremoved when it completes, so only actively-backfilling resources appear in\nthe scheduler's due query. Pacing between chunks is driven by that scheduler\n(see BackfillNextChunkAt), not by an in-workflow sleep.",
            "type": "string"
          },
          "collection_override": {
            "description": "Routes this resource's synced objects into a specific collection, overriding the connector's. Canonical name; mirrors the deprecated `sub_tenant_id_override` alias.",
            "type": "string"
          },
          "connector_id": {
            "description": "Connector this resource belongs to.",
            "example": "conn_abc123",
            "type": "string"
          },
          "custom_instructions": {
            "description": "CustomInstructions is optional free-text ingestion guidance scoped to\nthis resource. When set it replaces the connector-level\ncustom_instructions for documents synced from this resource; empty means\nthe resource inherits the connector's value. Max 4000 characters;\nchanges apply from the next sync cycle.",
            "type": "string"
          },
          "database_override": {
            "description": "DatabaseOverride/CollectionOverride are the canonical v2 names for the\ndeprecated tenant_id_override/sub_tenant_id_override wire fields. Empty\nmeans the resource inherits the connector's database/collection, exactly\nas the deprecated fields do. Not persisted (dynamodbav:\"-\"): mirrored from\nthe tenant_id_override/sub_tenant_id_override values at construction time.",
            "type": "string"
          },
          "display_name": {
            "description": "Human-readable name for this resource.",
            "example": "general",
            "type": "string"
          },
          "filters": {
            "additionalProperties": {},
            "description": "Provider-specific filters applied during sync (e.g. `{\"lookback_days\": 30}`).",
            "example": {
              "channel": "general"
            },
            "type": "object"
          },
          "metadata": {
            "additionalProperties": {},
            "description": "Metadata is merged into the tenant metadata layer of every object synced\nfrom this resource. User-supplied keys are shallow-merged as the base;\nsystem defaults (connector_id, provider) are applied on top so they\nalways win on conflict — user keys extend the map but cannot override\nsystem-set fields.",
            "example": {
              "department": "finance",
              "priority": 7
            },
            "type": "object"
          },
          "page_acl_warning": {
            "description": "PageACLWarning is the same signal for SOURCE-level failures inside this\nresource: individual pages whose own restrictions could not be resolved\nand were therefore opened (Confluence, PRO-1684).\n\nA SEPARATE field from ACLWarning on purpose. The two are written by\ndifferent steps at different points in a sync, and ACLWarning is CLEARED\nwhenever resource capture succeeds. Sharing one field would let a healthy\nspace wipe a live page warning every cycle, leaving a window in which the\ndashboard reports no problems while pages are still open — a false\nall-clear on an access-control surface, which is worse than no surface.",
            "type": "string"
          },
          "page_acl_warning_at": {
            "description": "PageACLWarningAt is when PageACLWarning last CHANGED (RFC3339).",
            "type": "string"
          },
          "page_acl_warning_run": {
            "description": "PageACLWarningRun is the drain run that last observed a page failing open\nhere. It is what makes the warning self-clearing: the drain settles each\nresource at the END of a cycle, and a stored run that is not the current\none means that whole cycle passed with nothing failing, so the warning is\nwithdrawn. Durable on purpose — the alternative was remembering it in the\nworker, which a restart loses and which has no moment that means \"all\npages have now been judged\".",
            "type": "string"
          },
          "provider_cursor": {
            "description": "Bookmark of the last synced position. Non-empty value confirms the first sync has run.",
            "example": "1699999999.000100",
            "type": "string"
          },
          "provider_metadata": {
            "additionalProperties": {},
            "description": "Additional provider-supplied metadata for this resource.",
            "example": {
              "workspace_id": "T12345ACME"
            },
            "type": "object"
          },
          "resource_id": {
            "description": "Resource identifier from the Discover endpoint.",
            "example": "C0123456789",
            "type": "string"
          },
          "resource_type": {
            "description": "Type of resource within the provider (e.g. `channel`, `repo`, `linear_team`).",
            "example": "channel",
            "type": "string"
          },
          "status": {
            "description": "Current sync state of this resource (e.g. `active`, `paused`).",
            "example": "completed",
            "type": "string"
          },
          "sub_tenant_id_override": {
            "deprecated": true,
            "description": "Overrides the connector-level collection for objects synced from this resource.",
            "type": "string",
            "x-deprecated": "true"
          },
          "sync_blocked": {
            "description": "SyncBlocked marks a resource the provider will go on refusing — a table\nthat was dropped, a channel this credential was never invited to.\n\nDeliberately not a Status value. Status gates ListConnectorResources,\nwhich is what GET /connectors/{id}/status reads, so expressing this as a\nstatus would hide the resource from the one endpoint that explains why it\nstopped. The resource stays active and visible; this only takes it out of\nwhat gets synced.",
            "example": true,
            "type": "boolean"
          },
          "sync_blocked_at": {
            "description": "SyncBlockedAt is when the resource was stopped (RFC3339).",
            "type": "string"
          },
          "sync_blocked_reason": {
            "description": "SyncBlockedReason is the provider's own explanation, carried forward from\nthe health that triggered the block so it survives the next sync\noverwriting that health.",
            "type": "string"
          },
          "tenant_id_override": {
            "deprecated": true,
            "description": "Overrides the connector-level database for objects synced from this resource. Deprecated.",
            "type": "string",
            "x-deprecated": "true"
          }
        },
        "type": "object"
      },
      "dashboard.PaginationMeta": {
        "properties": {
          "has_next": {
            "description": "Whether a next page exists.",
            "example": true,
            "type": "boolean"
          },
          "has_previous": {
            "description": "Whether a previous page exists.",
            "example": false,
            "type": "boolean"
          },
          "page": {
            "description": "Current page number (1-indexed).",
            "example": 1,
            "type": "integer"
          },
          "page_size": {
            "description": "Number of items per page.",
            "example": 50,
            "type": "integer"
          },
          "total": {
            "description": "Total number of items across all pages.",
            "example": 128,
            "type": "integer"
          },
          "total_pages": {
            "description": "Total number of pages.",
            "example": 3,
            "type": "integer"
          }
        },
        "type": "object"
      },
      "feedback.GroundTruth": {
        "properties": {
          "answer": {
            "description": "Answer is the response the caller expected — the text a correct system\nwould have produced from the retrieved context.",
            "maxLength": 8000,
            "type": "string"
          },
          "source_ids": {
            "description": "SourceIDs are the ingested source IDs that actually contain the answer,\nas returned in query results and accepted by /context endpoints.",
            "example": [
              "HydraDoc1234",
              "HydraDoc4567"
            ],
            "items": {
              "maxLength": 256,
              "type": "string"
            },
            "maxItems": 100,
            "type": "array",
            "uniqueItems": false
          }
        },
        "type": "object"
      },
      "feedback.Rating": {
        "enum": [
          "positive",
          "negative",
          "neutral"
        ],
        "type": "string",
        "x-enum-varnames": [
          "RatingPositive",
          "RatingNegative",
          "RatingNeutral"
        ]
      },
      "feedback.Source": {
        "enum": [
          "user",
          "agent"
        ],
        "type": "string",
        "x-enum-varnames": [
          "SourceUser",
          "SourceAgent"
        ]
      },
      "feedback.SubmitRequest": {
        "allOf": [
          {
            "anyOf": [
              {
                "patternProperties": {
                  "^feedback$": {
                    "minLength": 1,
                    "pattern": "\\S"
                  }
                },
                "required": [
                  "feedback"
                ]
              },
              {
                "patternProperties": {
                  "^ground_truth$": {
                    "anyOf": [
                      {
                        "properties": {
                          "answer": {
                            "minLength": 1,
                            "pattern": "\\S"
                          }
                        },
                        "required": [
                          "answer"
                        ]
                      },
                      {
                        "properties": {
                          "source_ids": {
                            "contains": {
                              "minLength": 1,
                              "pattern": "\\S"
                            }
                          }
                        },
                        "required": [
                          "source_ids"
                        ]
                      }
                    ]
                  }
                },
                "required": [
                  "ground_truth"
                ]
              }
            ]
          }
        ],
        "dependentSchemas": {
          "collection": {
            "anyOf": [
              {
                "required": [
                  "database"
                ]
              },
              {
                "required": [
                  "tenant_id"
                ]
              }
            ]
          },
          "sub_tenant_id": {
            "anyOf": [
              {
                "required": [
                  "database"
                ]
              },
              {
                "required": [
                  "tenant_id"
                ]
              }
            ]
          }
        },
        "properties": {
          "collection": {
            "description": "Optional collection scope for this feedback. A collection is scoped to a database, so `database` must be sent alongside it; sending `collection` on its own is rejected.",
            "example": "team_docs",
            "minLength": 1,
            "type": "string"
          },
          "database": {
            "description": "Owning database. Formerly `tenant_id`; the `tenant_id` alias is still accepted (deprecated).",
            "example": "acme_corp",
            "minLength": 1,
            "type": "string"
          },
          "feedback": {
            "description": "Free-text comment describing what was right or wrong about the results. Required unless `ground_truth` is supplied.",
            "maxLength": 8000,
            "type": "string"
          },
          "ground_truth": {
            "$ref": "#/components/schemas/feedback.GroundTruth",
            "description": "What you already know the right answer to be, when you know it. Supply an expected `answer`, the `source_ids` that contain it, or both — at least one is required if the field is present. Machine-checkable, so it is a stronger signal than a comment: submit it alone and `feedback` becomes optional.",
            "example": {
              "source_ids": [
                "HydraDoc1234",
                "HydraDoc4567"
              ]
            }
          },
          "metadata": {
            "additionalProperties": {
              "maxLength": 512,
              "type": "string"
            },
            "description": "Free-form key-value context stored alongside the feedback (e.g. agent name, conversation or eval-run ID).",
            "example": {
              "agent": "support-bot",
              "conversation": "c-8891"
            },
            "maxProperties": 20,
            "propertyNames": {
              "maxLength": 64
            },
            "type": "object"
          },
          "rating": {
            "$ref": "#/components/schemas/feedback.Rating",
            "description": "Optional overall judgement: `positive`, `negative`, or `neutral`. Omit to send a comment with no rating."
          },
          "request_id": {
            "description": "The `request_id` from `response.meta` of the query this feedback is about. Required — it is what links the feedback to the query that ran.",
            "example": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
            "format": "uuid",
            "type": "string"
          },
          "source": {
            "$ref": "#/components/schemas/feedback.Source",
            "description": "Who is submitting: `user` (default) or `agent`."
          },
          "sub_tenant_id": {
            "deprecated": true,
            "description": "deprecated: use collection",
            "example": "sub_tenant_4567",
            "minLength": 1,
            "type": "string",
            "x-deprecated": "true",
            "x-deprecated-since": "2.0.1"
          },
          "tenant_id": {
            "deprecated": true,
            "description": "deprecated: use database",
            "example": "tenant_1234",
            "minLength": 1,
            "type": "string",
            "x-deprecated": "true",
            "x-deprecated-since": "2.0.1"
          }
        },
        "required": [
          "request_id"
        ],
        "type": "object"
      },
      "feedback.SubmitResponse": {
        "properties": {
          "created_at": {
            "description": "RFC3339 timestamp when the feedback was recorded.",
            "example": "2026-07-02T10:00:00Z",
            "type": "string"
          },
          "feedback_id": {
            "description": "Unique identifier assigned to this feedback submission.",
            "type": "string"
          },
          "message": {
            "description": "Human-readable result message.",
            "example": "Success",
            "type": "string"
          },
          "recorded": {
            "description": "Whether the feedback was durably stored.",
            "example": true,
            "type": "boolean"
          },
          "request_id": {
            "description": "The query request ID this feedback was recorded against.",
            "example": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
            "type": "string"
          }
        },
        "type": "object"
      },
      "fetch.V2SourceFetchResponse": {
        "properties": {
          "content": {
            "description": "Extracted text content of the source document.",
            "example": "# Q4 Report\n\nRevenue grew 23% quarter over quarter.",
            "type": "string"
          },
          "content_base64": {
            "description": "Base64-encoded binary content, for binary file types.",
            "type": "string"
          },
          "content_type": {
            "description": "MIME type of the source (e.g. `application/pdf`, `text/plain`).",
            "example": "application/pdf",
            "type": "string"
          },
          "error": {
            "description": "Error message, empty string on success.",
            "example": "",
            "type": "string"
          },
          "id": {
            "description": "Unique identifier for this resource.",
            "example": "HydraDoc1234",
            "type": "string"
          },
          "inferred_content": {
            "description": "LLM-generated summary of the source content.",
            "example": "Summary: Q4 revenue rose 23% QoQ, driven by enterprise expansion.",
            "type": "string"
          },
          "message": {
            "description": "Human-readable result message.",
            "example": "Success",
            "type": "string"
          },
          "presigned_url": {
            "description": "Time-limited download URL for the original file.",
            "example": "https://storage.hydradb.com/sources/HydraDoc1234?sig=...",
            "type": "string"
          },
          "size_bytes": {
            "description": "File size in bytes.",
            "example": 20480,
            "type": "integer"
          },
          "success": {
            "deprecated": true,
            "description": "Deprecated for API clients: to decide whether the request succeeded,\ncheck the HTTP status code — 2xx is success — or equivalently the\nenvelope's top-level `success`. This nested copy always carries the same\nvalue as that flag and never carries independent information. Still\nemitted unchanged for existing clients (PRO-1208).",
            "example": true,
            "type": "boolean",
            "x-deprecated": "true"
          }
        },
        "type": "object"
      },
      "github_com_hydradb_hydradb-application_internal_platform_storagelayout.Layout": {
        "description": "StorageLayout is the physical storage layout the database is created with,\nfrom the request's `type` field. \"split\" is the two-collection layout every\ndatabase uses, and the default. Fixed at creation and IMMUTABLE thereafter:\nthe layout decides how every entity id is hashed, so a database that changed\nits mind would orphan everything already stored.",
        "enum": [
          "split"
        ],
        "type": "string",
        "x-enum-varnames": [
          "LayoutSplit"
        ]
      },
      "github_com_hydradb_hydradb-application_internal_service.MetadataEditResult": {
        "properties": {
          "acl_drift_recorded": {
            "description": "ACLDriftRecorded reports that a failed ACL mirror was durably recorded\nfor reconciliation. Always true when vector_acl_synced is true. False\nbeside acl_updated=true and vector_acl_synced=false is the one state\nthe operator must act on (the error log names the document).",
            "example": true,
            "type": "boolean"
          },
          "acl_updated": {
            "description": "ACLUpdated reports that this edit replaced the source's ACL (PRO-1684).",
            "example": true,
            "type": "boolean"
          },
          "additional_metadata_keys": {
            "description": "Additional metadata keys included in the update request.",
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false
          },
          "chunk_rows_matched": {
            "description": "Number of MongoDB chunk rows matched by the source update.",
            "example": 1,
            "type": "integer"
          },
          "chunk_rows_modified": {
            "description": "Number of MongoDB chunk rows modified by the source update.",
            "example": 1,
            "type": "integer"
          },
          "collection": {
            "description": "Collection that contained the source. Canonical name; mirrors the deprecated `sub_tenant_id` alias.",
            "example": "team_docs",
            "type": "string"
          },
          "database": {
            "description": "Owning database. Canonical name; mirrors the deprecated `tenant_id` alias.",
            "example": "acme_corp",
            "type": "string"
          },
          "database_metadata_keys": {
            "description": "Database metadata keys included in the update request. Canonical name; `tenant_metadata_keys` is a deprecated alias.",
            "example": [
              "department",
              "priority"
            ],
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false
          },
          "id": {
            "description": "Unique identifier for this resource.",
            "example": "HydraDoc1234",
            "type": "string"
          },
          "milvus_rows_synced": {
            "deprecated": true,
            "description": "deprecated: use vector_rows_synced",
            "example": 1,
            "type": "integer",
            "x-deprecated": "true"
          },
          "milvus_sync_required": {
            "deprecated": true,
            "description": "Deprecated: use vector_sync_required / vector_synced / vector_rows_synced.\nRetained as additive aliases for existing clients; carry the same values.",
            "example": true,
            "type": "boolean",
            "x-deprecated": "true"
          },
          "milvus_synced": {
            "deprecated": true,
            "description": "deprecated: use vector_synced",
            "example": true,
            "type": "boolean",
            "x-deprecated": "true"
          },
          "partial_commit": {
            "description": "PartialCommit reports that the edit committed in at least one database\nof a shared deployment but a later write in another failed; the\nidempotent retry converges the database that fell behind.",
            "type": "string"
          },
          "sub_tenant_id": {
            "deprecated": true,
            "description": "deprecated: use collection",
            "example": "sub_tenant_4567",
            "type": "string",
            "x-deprecated": "true"
          },
          "tenant_id": {
            "deprecated": true,
            "description": "deprecated: use database",
            "example": "tenant_1234",
            "type": "string",
            "x-deprecated": "true"
          },
          "tenant_metadata_keys": {
            "deprecated": true,
            "description": "deprecated: use database_metadata_keys",
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false,
            "x-deprecated": "true"
          },
          "updated": {
            "description": "Whether the source metadata was updated.",
            "example": true,
            "type": "boolean"
          },
          "vector_acl_synced": {
            "description": "VectorACLSynced reports that the ACL edit also reached the vector rows'\npushdown columns (PRO-1740). False with ACLUpdated true means the\ndocument's own-ACL projection is stale until its next re-index: still\nenforced correctly from Mongo, but invisible to the pushdown lane for\nany principal the edit ADDED. Always false for collections created\nbefore PRO-1740, which carry no pushdown columns.",
            "example": true,
            "type": "boolean"
          },
          "vector_rows_synced": {
            "description": "Number of chunk rows synced to the vector store when sync was required.",
            "example": 1,
            "type": "integer"
          },
          "vector_sync_error": {
            "description": "VectorSyncError explains a vector_synced=false when a sync was\nrequired: the authority (Mongo) committed, the vector metadata did\nnot follow; the idempotent retry converges it.",
            "type": "string"
          },
          "vector_sync_required": {
            "description": "Vendor-neutral vector-sync signal (PRO-1185): the canonical field must not\nname the vector store. The milvus_* fields below are deprecated aliases kept\nfor backward compatibility (additive change, not a rename) and carry the same\nvalues; they are slated for removal in a future major version.",
            "example": true,
            "type": "boolean"
          },
          "vector_synced": {
            "description": "Whether the vector store metadata sync completed. Present when sync was required.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "graph.Entity": {
        "properties": {
          "entity_id": {
            "description": "Unique identifier for this entity in the graph.",
            "example": "entity_1a2b",
            "type": "string"
          },
          "hydration": {
            "description": "Hydration is set on Source nodes in AuxiliaryRelations only, and omitted\neverywhere else. RELATES_TO MERGEs its target by source_id, so a target\nthat has not been ingested yet still exists as a node — callers must be\nable to tell a real document from a forward reference to one.\n\n\tresolved    — ingested; source_id and app_provider both present\n\tstub        — MERGE-created target; source_id present, no app_provider\n\tplaceholder — source_id IS NULL, keyed by app_external_id, awaiting\n\t              builder.py's reconciliation pass",
            "type": "string"
          },
          "identifier": {
            "description": "NO omitempty — serialize as null",
            "example": "Acme Corp",
            "type": "string"
          },
          "name": {
            "description": "Human-readable label for this resource.",
            "example": "general",
            "type": "string"
          },
          "namespace": {
            "description": "Namespace grouping for the entity (e.g. `organization`, `person`).",
            "example": "organization",
            "type": "string"
          },
          "provider": {
            "description": "Provider is the source app the entity's evidence chunk came from (e.g.\n\"slack\", \"google\", \"intercom\"), read from the owning Source node's\napp_provider. Empty string when the evidence has no app source (plain\ndocument / web ingest). Consumed by the dashboard to render a connector\nlogo inside the graph node.",
            "example": "slack",
            "type": "string"
          },
          "type": {
            "description": "Entity type label (e.g. `knowledge`, `person`, `organization`).",
            "example": "knowledge",
            "type": "string"
          }
        },
        "type": "object"
      },
      "graph.GraphRelationsResponse": {
        "properties": {
          "auxiliary_relations": {
            "description": "AuxiliaryRelations carries the structural graph around the entity\nrelations: Entity-\u003eSource presence, Source-\u003eComment/Attachment,\nActor-\u003eSource/Comment, and Source-\u003eSource links. Same item shape as\nRelations, so a caller wanting one graph concatenates the two.\n\nDeliberately a SEPARATE array rather than merged into Relations:\ncapPreservingTies counts triplets against the caller's limit, and\ncomputeNextCursor keys on relation timestamps. Auxiliary edges carry\ncreated_at — a different clock — so merging them would both shrink the\nentity relations returned for a given limit and corrupt the cursor.",
            "example": [
              {
                "chunk_id": "HydraEmbeddings123_0",
                "relations": [
                  {
                    "canonical_predicate": "works_at",
                    "chunk_id": "HydraEmbeddings123_0",
                    "confidence": 0.92,
                    "context": "Ada joined Acme Corp in 2024 as a staff engineer.",
                    "raw_predicate": "is employed by",
                    "relationship_id": "rel_1234",
                    "source_entity_id": "entity_1a2b",
                    "synthesized": true,
                    "target_entity_id": "entity_3c4d",
                    "temporal_details": "since 2024",
                    "timestamp": "2026-07-02T10:00:00Z"
                  }
                ],
                "source": {
                  "entity_id": "entity_1a2b",
                  "identifier": "Acme Corp",
                  "name": "general",
                  "namespace": "organization",
                  "provider": "slack",
                  "type": "knowledge"
                },
                "target": {
                  "entity_id": "entity_1a2b",
                  "identifier": "Acme Corp",
                  "name": "general",
                  "namespace": "organization",
                  "provider": "slack",
                  "type": "knowledge"
                },
                "truncated": true
              }
            ],
            "items": {
              "$ref": "#/components/schemas/graph.TripletWithEvidence"
            },
            "type": "array",
            "uniqueItems": false
          },
          "auxiliary_truncated": {
            "description": "AuxiliaryTruncated reports that an aggregate row ceiling clipped the\nauxiliary graph. Distinct from the per-triplet Truncated flag, which only\ncovers a single node exceeding its fan-out cap: a wide page can blow the\naggregate ceiling with every individual node still under its own cap, and\nwithout this the caller would receive a subset presented as complete.\n\nIndependent of IsTruncated, which describes Relations pagination only.",
            "example": true,
            "type": "boolean"
          },
          "is_truncated": {
            "description": "Whether the response was truncated due to the result limit.",
            "example": false,
            "type": "boolean"
          },
          "message": {
            "description": "Human-readable result message.",
            "example": "Success",
            "type": "string"
          },
          "next_cursor": {
            "description": "NO omitempty",
            "example": 0.5,
            "type": "number"
          },
          "relations": {
            "description": "Array of triplet groups with evidence for each relationship.",
            "example": [
              {
                "chunk_id": "HydraEmbeddings123_0",
                "relations": [
                  {
                    "canonical_predicate": "works_at",
                    "chunk_id": "HydraEmbeddings123_0",
                    "confidence": 0.92,
                    "context": "Ada joined Acme Corp in 2024 as a staff engineer.",
                    "raw_predicate": "is employed by",
                    "relationship_id": "rel_1234",
                    "source_entity_id": "entity_1a2b",
                    "synthesized": true,
                    "target_entity_id": "entity_3c4d",
                    "temporal_details": "since 2024",
                    "timestamp": "2026-07-02T10:00:00Z"
                  }
                ],
                "source": {
                  "entity_id": "entity_1a2b",
                  "identifier": "Acme Corp",
                  "name": "general",
                  "namespace": "organization",
                  "provider": "slack",
                  "type": "knowledge"
                },
                "target": {
                  "entity_id": "entity_1a2b",
                  "identifier": "Acme Corp",
                  "name": "general",
                  "namespace": "organization",
                  "provider": "slack",
                  "type": "knowledge"
                },
                "truncated": true
              }
            ],
            "items": {
              "$ref": "#/components/schemas/graph.TripletWithEvidence"
            },
            "type": "array",
            "uniqueItems": false
          },
          "success": {
            "deprecated": true,
            "description": "Deprecated for API clients: to decide whether the request succeeded,\ncheck the HTTP status code — 2xx is success — or equivalently the\nenvelope's top-level `success`. This nested copy always carries the same\nvalue and never carries independent information. Still emitted unchanged\nfor existing clients (PRO-1208).",
            "example": true,
            "type": "boolean",
            "x-deprecated": "true"
          }
        },
        "type": "object"
      },
      "graph.RelationEvidence": {
        "properties": {
          "canonical_predicate": {
            "description": "Normalized predicate for the relationship (e.g. `works_at`, `depends_on`).",
            "example": "works_at",
            "type": "string"
          },
          "chunk_id": {
            "description": "NO omitempty",
            "example": "HydraEmbeddings123_0",
            "type": "string"
          },
          "confidence": {
            "description": "Confidence score, from 0 to 1.",
            "example": 0.92,
            "type": "number"
          },
          "context": {
            "description": "Verbatim passage from the source that evidences the relationship.",
            "example": "Ada joined Acme Corp in 2024 as a staff engineer.",
            "type": "string"
          },
          "raw_predicate": {
            "description": "As-extracted predicate before normalization.",
            "example": "is employed by",
            "type": "string"
          },
          "relationship_id": {
            "description": "Unique identifier for this relationship instance.",
            "example": "rel_1234",
            "type": "string"
          },
          "source_entity_id": {
            "description": "NO omitempty",
            "example": "entity_1a2b",
            "type": "string"
          },
          "synthesized": {
            "description": "Synthesized marks a triplet with no stored edge behind it. Only\n`present_in` sets it: that edge is derived by collapsing\nEntity-PRESENT_IN-\u003eChunk-HAS_CHUNK-\u003eSource, so its RelationshipID is a\ndeterministic synthetic id rather than a graph relationship id. Omitted\n(false) on every stored edge.",
            "example": true,
            "type": "boolean"
          },
          "target_entity_id": {
            "description": "NO omitempty",
            "example": "entity_3c4d",
            "type": "string"
          },
          "temporal_details": {
            "description": "NO omitempty",
            "example": "since 2024",
            "type": "string"
          },
          "timestamp": {
            "description": "RFC3339 timestamp associated with this item.",
            "example": "2026-07-02T10:00:00Z",
            "type": "string"
          }
        },
        "type": "object"
      },
      "graph.SourceSubgraphResponse": {
        "properties": {
          "auxiliary_relations": {
            "description": "AuxiliaryRelations carries the structural graph around the member\nsources: Entity-\u003eSource presence, Source-\u003eComment/Attachment and\nActor-\u003eSource/Comment links. Same item shape as Relations, matching\nGraphRelationsResponse so the dashboard renderer works unchanged.",
            "example": [
              {
                "chunk_id": "HydraEmbeddings123_0",
                "relations": [
                  {
                    "canonical_predicate": "works_at",
                    "chunk_id": "HydraEmbeddings123_0",
                    "confidence": 0.92,
                    "context": "Ada joined Acme Corp in 2024 as a staff engineer.",
                    "raw_predicate": "is employed by",
                    "relationship_id": "rel_1234",
                    "source_entity_id": "entity_1a2b",
                    "synthesized": true,
                    "target_entity_id": "entity_3c4d",
                    "temporal_details": "since 2024",
                    "timestamp": "2026-07-02T10:00:00Z"
                  }
                ],
                "source": {
                  "entity_id": "entity_1a2b",
                  "identifier": "Acme Corp",
                  "name": "general",
                  "namespace": "organization",
                  "provider": "slack",
                  "type": "knowledge"
                },
                "target": {
                  "entity_id": "entity_1a2b",
                  "identifier": "Acme Corp",
                  "name": "general",
                  "namespace": "organization",
                  "provider": "slack",
                  "type": "knowledge"
                },
                "truncated": true
              }
            ],
            "items": {
              "$ref": "#/components/schemas/graph.TripletWithEvidence"
            },
            "type": "array",
            "uniqueItems": false
          },
          "auxiliary_truncated": {
            "description": "AuxiliaryTruncated reports that a fetch ceiling clipped the auxiliary\ngraph, same contract as GraphRelationsResponse.AuxiliaryTruncated.",
            "example": true,
            "type": "boolean"
          },
          "is_truncated": {
            "description": "IsTruncated reports that the traversal stopped before exhausting the\nconnected component: the source budget or an edge/expansion fetch cap\nwas hit, or the depth limit left an unexpanded frontier.",
            "example": false,
            "type": "boolean"
          },
          "max_depth_reached": {
            "description": "MaxDepthReached is the deepest BFS level that admitted a member.",
            "example": 1,
            "type": "integer"
          },
          "message": {
            "description": "Human-readable result message.",
            "example": "Success",
            "type": "string"
          },
          "relations": {
            "description": "Relations holds the Source-\u003eSource triplets: every RELATES_TO edge whose\nendpoints are both members, plus synthesized same_thread / child_of\nprovenance edges for members reached through a node property rather than\na stored edge (those carry Synthesized on their evidence).",
            "example": [
              {
                "chunk_id": "HydraEmbeddings123_0",
                "relations": [
                  {
                    "canonical_predicate": "works_at",
                    "chunk_id": "HydraEmbeddings123_0",
                    "confidence": 0.92,
                    "context": "Ada joined Acme Corp in 2024 as a staff engineer.",
                    "raw_predicate": "is employed by",
                    "relationship_id": "rel_1234",
                    "source_entity_id": "entity_1a2b",
                    "synthesized": true,
                    "target_entity_id": "entity_3c4d",
                    "temporal_details": "since 2024",
                    "timestamp": "2026-07-02T10:00:00Z"
                  }
                ],
                "source": {
                  "entity_id": "entity_1a2b",
                  "identifier": "Acme Corp",
                  "name": "general",
                  "namespace": "organization",
                  "provider": "slack",
                  "type": "knowledge"
                },
                "target": {
                  "entity_id": "entity_1a2b",
                  "identifier": "Acme Corp",
                  "name": "general",
                  "namespace": "organization",
                  "provider": "slack",
                  "type": "knowledge"
                },
                "truncated": true
              }
            ],
            "items": {
              "$ref": "#/components/schemas/graph.TripletWithEvidence"
            },
            "type": "array",
            "uniqueItems": false
          },
          "seed_source_id": {
            "type": "string"
          },
          "sources": {
            "description": "Sources is every member of the subgraph in BFS discovery order, seed\nfirst.",
            "example": [
              {
                "app_external_id": "C0123456789",
                "app_kind": "slack",
                "app_provider": "slack",
                "depth": 1,
                "source_id": "HydraDoc1234",
                "title": "Project Phoenix Overview"
              }
            ],
            "items": {
              "$ref": "#/components/schemas/graph.SubgraphSource"
            },
            "type": "array",
            "uniqueItems": false
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "graph.SubgraphSource": {
        "properties": {
          "app_external_id": {
            "description": "Provider-assigned identifier for this source (e.g. Slack channel ID).",
            "example": "C0123456789",
            "type": "string"
          },
          "app_kind": {
            "description": "App integration category, populated for connector-synced sources.",
            "example": "slack",
            "type": "string"
          },
          "app_provider": {
            "description": "Provider name for app-sourced items (e.g. `slack`, `github`).",
            "example": "slack",
            "type": "string"
          },
          "depth": {
            "description": "Depth is the BFS distance from the seed (0 for the seed itself).",
            "example": 1,
            "type": "integer"
          },
          "discovered_relation": {
            "type": "string"
          },
          "discovered_via": {
            "description": "DiscoveredVia and DiscoveredRelation record the traversal provenance:\nwhich already-admitted source this member was first reached from, and\nthrough which mechanism — a RELATES_TO relation_type (reply_to,\nchild_of, ...), same_thread, parent or child. Empty on the seed.",
            "type": "string"
          },
          "hydration": {
            "description": "Hydration carries the same resolved/stub/placeholder classification\nEntity.Hydration documents: a RELATES_TO target may be a MERGE-created\nforward reference to a document that has not been ingested yet.",
            "type": "string"
          },
          "source_id": {
            "example": "HydraDoc1234",
            "type": "string"
          },
          "thread_id": {
            "type": "string"
          },
          "title": {
            "description": "Title or name of the source.",
            "example": "Project Phoenix Overview",
            "type": "string"
          }
        },
        "type": "object"
      },
      "graph.TripletWithEvidence": {
        "properties": {
          "chunk_id": {
            "description": "Chunk that provides evidence for this relation.",
            "example": "HydraEmbeddings123_0",
            "type": "string"
          },
          "relations": {
            "description": "Evidence entries for this relationship triplet.",
            "example": [
              {
                "canonical_predicate": "works_at",
                "chunk_id": "HydraEmbeddings123_0",
                "confidence": 0.92,
                "context": "Ada joined Acme Corp in 2024 as a staff engineer.",
                "raw_predicate": "is employed by",
                "relationship_id": "rel_1234",
                "source_entity_id": "entity_1a2b",
                "synthesized": true,
                "target_entity_id": "entity_3c4d",
                "temporal_details": "since 2024",
                "timestamp": "2026-07-02T10:00:00Z"
              }
            ],
            "items": {
              "$ref": "#/components/schemas/graph.RelationEvidence"
            },
            "type": "array",
            "uniqueItems": false
          },
          "source": {
            "$ref": "#/components/schemas/graph.Entity",
            "example": {
              "entity_id": "entity_1a2b",
              "identifier": "Acme Corp",
              "name": "general",
              "namespace": "organization",
              "provider": "slack",
              "type": "knowledge"
            }
          },
          "target": {
            "$ref": "#/components/schemas/graph.Entity",
            "example": {
              "entity_id": "entity_1a2b",
              "identifier": "Acme Corp",
              "name": "general",
              "namespace": "organization",
              "provider": "slack",
              "type": "knowledge"
            }
          },
          "truncated": {
            "description": "Truncated is set on auxiliary triplets whose fan-out hit a per-node cap,\nso a caller can tell \"this source has no more comments\" from \"we stopped\ncounting\". Omitted (false) on entity relations, which are bounded by the\nrequest's own limit/cursor instead.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.Envelope-feedback_SubmitResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/feedback.SubmitResponse",
            "example": {
              "created_at": "2026-07-02T10:00:00Z",
              "message": "Success",
              "recorded": true,
              "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d"
            }
          },
          "error": {
            "$ref": "#/components/schemas/handler.apiError",
            "description": "Error message, empty string on success.",
            "example": {
              "code": "DATABASE_NOT_FOUND",
              "message": "Database not found"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/handler.responseMeta",
            "example": {
              "collection": "team_docs",
              "database": "acme_corp",
              "latency_ms": 12.3,
              "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
              "source_type": "file",
              "sub_tenant_id": "sub_tenant_4567",
              "tenant_id": "tenant_1234"
            }
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.Envelope-fetch_V2SourceFetchResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/fetch.V2SourceFetchResponse",
            "example": {
              "content": "# Q4 Report\n\nRevenue grew 23% quarter over quarter.",
              "content_type": "application/pdf",
              "error": "",
              "id": "HydraDoc1234",
              "inferred_content": "Summary: Q4 revenue rose 23% QoQ, driven by enterprise expansion.",
              "message": "Success",
              "presigned_url": "https://storage.hydradb.com/sources/HydraDoc1234?sig=...",
              "size_bytes": 20480,
              "success": true
            }
          },
          "error": {
            "$ref": "#/components/schemas/handler.apiError",
            "description": "Error message, empty string on success.",
            "example": {
              "code": "DATABASE_NOT_FOUND",
              "message": "Database not found"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/handler.responseMeta",
            "example": {
              "collection": "team_docs",
              "database": "acme_corp",
              "latency_ms": 12.3,
              "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
              "source_type": "file",
              "sub_tenant_id": "sub_tenant_4567",
              "tenant_id": "tenant_1234"
            }
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.Envelope-github_com_hydradb_hydradb-application_internal_service_MetadataEditResult": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/github_com_hydradb_hydradb-application_internal_service.MetadataEditResult",
            "example": {
              "acl_drift_recorded": true,
              "acl_updated": true,
              "chunk_rows_matched": 1,
              "chunk_rows_modified": 1,
              "collection": "team_docs",
              "database": "acme_corp",
              "database_metadata_keys": [
                "department",
                "priority"
              ],
              "id": "HydraDoc1234",
              "milvus_rows_synced": 1,
              "milvus_sync_required": true,
              "milvus_synced": true,
              "sub_tenant_id": "sub_tenant_4567",
              "tenant_id": "tenant_1234",
              "updated": true,
              "vector_acl_synced": true,
              "vector_rows_synced": 1,
              "vector_sync_required": true,
              "vector_synced": true
            }
          },
          "error": {
            "$ref": "#/components/schemas/handler.apiError",
            "description": "Error message, empty string on success.",
            "example": {
              "code": "DATABASE_NOT_FOUND",
              "message": "Database not found"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/handler.responseMeta",
            "example": {
              "collection": "team_docs",
              "database": "acme_corp",
              "latency_ms": 12.3,
              "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
              "source_type": "file",
              "sub_tenant_id": "sub_tenant_4567",
              "tenant_id": "tenant_1234"
            }
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.Envelope-graph_GraphRelationsResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/graph.GraphRelationsResponse",
            "example": {
              "auxiliary_relations": [
                {
                  "chunk_id": "HydraEmbeddings123_0",
                  "relations": [
                    {
                      "canonical_predicate": "works_at",
                      "chunk_id": "HydraEmbeddings123_0",
                      "confidence": 0.92,
                      "context": "Ada joined Acme Corp in 2024 as a staff engineer.",
                      "raw_predicate": "is employed by",
                      "relationship_id": "rel_1234",
                      "source_entity_id": "entity_1a2b",
                      "synthesized": true,
                      "target_entity_id": "entity_3c4d",
                      "temporal_details": "since 2024",
                      "timestamp": "2026-07-02T10:00:00Z"
                    }
                  ],
                  "source": {
                    "entity_id": "entity_1a2b",
                    "identifier": "Acme Corp",
                    "name": "general",
                    "namespace": "organization",
                    "provider": "slack",
                    "type": "knowledge"
                  },
                  "target": {
                    "entity_id": "entity_1a2b",
                    "identifier": "Acme Corp",
                    "name": "general",
                    "namespace": "organization",
                    "provider": "slack",
                    "type": "knowledge"
                  },
                  "truncated": true
                }
              ],
              "auxiliary_truncated": true,
              "is_truncated": false,
              "message": "Success",
              "next_cursor": 0.5,
              "relations": [
                {
                  "chunk_id": "HydraEmbeddings123_0",
                  "relations": [
                    {
                      "canonical_predicate": "works_at",
                      "chunk_id": "HydraEmbeddings123_0",
                      "confidence": 0.92,
                      "context": "Ada joined Acme Corp in 2024 as a staff engineer.",
                      "raw_predicate": "is employed by",
                      "relationship_id": "rel_1234",
                      "source_entity_id": "entity_1a2b",
                      "synthesized": true,
                      "target_entity_id": "entity_3c4d",
                      "temporal_details": "since 2024",
                      "timestamp": "2026-07-02T10:00:00Z"
                    }
                  ],
                  "source": {
                    "entity_id": "entity_1a2b",
                    "identifier": "Acme Corp",
                    "name": "general",
                    "namespace": "organization",
                    "provider": "slack",
                    "type": "knowledge"
                  },
                  "target": {
                    "entity_id": "entity_1a2b",
                    "identifier": "Acme Corp",
                    "name": "general",
                    "namespace": "organization",
                    "provider": "slack",
                    "type": "knowledge"
                  },
                  "truncated": true
                }
              ],
              "success": true
            }
          },
          "error": {
            "$ref": "#/components/schemas/handler.apiError",
            "description": "Error message, empty string on success.",
            "example": {
              "code": "DATABASE_NOT_FOUND",
              "message": "Database not found"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/handler.responseMeta",
            "example": {
              "collection": "team_docs",
              "database": "acme_corp",
              "latency_ms": 12.3,
              "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
              "source_type": "file",
              "sub_tenant_id": "sub_tenant_4567",
              "tenant_id": "tenant_1234"
            }
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.Envelope-graph_SourceSubgraphResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/graph.SourceSubgraphResponse",
            "example": {
              "auxiliary_relations": [
                {
                  "chunk_id": "HydraEmbeddings123_0",
                  "relations": [
                    {
                      "canonical_predicate": "works_at",
                      "chunk_id": "HydraEmbeddings123_0",
                      "confidence": 0.92,
                      "context": "Ada joined Acme Corp in 2024 as a staff engineer.",
                      "raw_predicate": "is employed by",
                      "relationship_id": "rel_1234",
                      "source_entity_id": "entity_1a2b",
                      "synthesized": true,
                      "target_entity_id": "entity_3c4d",
                      "temporal_details": "since 2024",
                      "timestamp": "2026-07-02T10:00:00Z"
                    }
                  ],
                  "source": {
                    "entity_id": "entity_1a2b",
                    "identifier": "Acme Corp",
                    "name": "general",
                    "namespace": "organization",
                    "provider": "slack",
                    "type": "knowledge"
                  },
                  "target": {
                    "entity_id": "entity_1a2b",
                    "identifier": "Acme Corp",
                    "name": "general",
                    "namespace": "organization",
                    "provider": "slack",
                    "type": "knowledge"
                  },
                  "truncated": true
                }
              ],
              "auxiliary_truncated": true,
              "is_truncated": false,
              "max_depth_reached": 1,
              "message": "Success",
              "relations": [
                {
                  "chunk_id": "HydraEmbeddings123_0",
                  "relations": [
                    {
                      "canonical_predicate": "works_at",
                      "chunk_id": "HydraEmbeddings123_0",
                      "confidence": 0.92,
                      "context": "Ada joined Acme Corp in 2024 as a staff engineer.",
                      "raw_predicate": "is employed by",
                      "relationship_id": "rel_1234",
                      "source_entity_id": "entity_1a2b",
                      "synthesized": true,
                      "target_entity_id": "entity_3c4d",
                      "temporal_details": "since 2024",
                      "timestamp": "2026-07-02T10:00:00Z"
                    }
                  ],
                  "source": {
                    "entity_id": "entity_1a2b",
                    "identifier": "Acme Corp",
                    "name": "general",
                    "namespace": "organization",
                    "provider": "slack",
                    "type": "knowledge"
                  },
                  "target": {
                    "entity_id": "entity_1a2b",
                    "identifier": "Acme Corp",
                    "name": "general",
                    "namespace": "organization",
                    "provider": "slack",
                    "type": "knowledge"
                  },
                  "truncated": true
                }
              ],
              "sources": [
                {
                  "app_external_id": "C0123456789",
                  "app_kind": "slack",
                  "app_provider": "slack",
                  "depth": 1,
                  "source_id": "HydraDoc1234",
                  "title": "Project Phoenix Overview"
                }
              ],
              "success": true
            }
          },
          "error": {
            "$ref": "#/components/schemas/handler.apiError",
            "description": "Error message, empty string on success.",
            "example": {
              "code": "DATABASE_NOT_FOUND",
              "message": "Database not found"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/handler.responseMeta",
            "example": {
              "collection": "team_docs",
              "database": "acme_corp",
              "latency_ms": 12.3,
              "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
              "source_type": "file",
              "sub_tenant_id": "sub_tenant_4567",
              "tenant_id": "tenant_1234"
            }
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.Envelope-handler_supabaseWebhookAck": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/handler.supabaseWebhookAck",
            "example": {
              "id": "HydraDoc1234",
              "status": "completed"
            }
          },
          "error": {
            "$ref": "#/components/schemas/handler.apiError",
            "description": "Error message, empty string on success.",
            "example": {
              "code": "DATABASE_NOT_FOUND",
              "message": "Database not found"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/handler.responseMeta",
            "example": {
              "collection": "team_docs",
              "database": "acme_corp",
              "latency_ms": 12.3,
              "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
              "source_type": "file",
              "sub_tenant_id": "sub_tenant_4567",
              "tenant_id": "tenant_1234"
            }
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.Envelope-ingestion_V2BatchProcessingStatus": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/ingestion.V2BatchProcessingStatus",
            "example": {
              "statuses": [
                {
                  "error_code": "",
                  "error_message": "",
                  "id": "HydraDoc1234",
                  "indexing_status": "completed",
                  "message": "Source processed successfully.",
                  "success": true
                }
              ]
            }
          },
          "error": {
            "$ref": "#/components/schemas/handler.apiError",
            "description": "Error message, empty string on success.",
            "example": {
              "code": "DATABASE_NOT_FOUND",
              "message": "Database not found"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/handler.responseMeta",
            "example": {
              "collection": "team_docs",
              "database": "acme_corp",
              "latency_ms": 12.3,
              "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
              "source_type": "file",
              "sub_tenant_id": "sub_tenant_4567",
              "tenant_id": "tenant_1234"
            }
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.Envelope-ingestion_V2IngestResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/ingestion.V2IngestResponse",
            "example": {
              "failed_count": 0,
              "message": "Success",
              "results": [
                {
                  "error": "",
                  "filename": "policy.pdf",
                  "id": "HydraDoc1234",
                  "infer": true,
                  "relations_created": 5,
                  "status": "queued",
                  "title": "Project Phoenix Overview"
                }
              ],
              "success": true,
              "success_count": 2
            }
          },
          "error": {
            "$ref": "#/components/schemas/handler.apiError",
            "description": "Error message, empty string on success.",
            "example": {
              "code": "DATABASE_NOT_FOUND",
              "message": "Database not found"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/handler.responseMeta",
            "example": {
              "collection": "team_docs",
              "database": "acme_corp",
              "latency_ms": 12.3,
              "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
              "source_type": "file",
              "sub_tenant_id": "sub_tenant_4567",
              "tenant_id": "tenant_1234"
            }
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.Envelope-list_V2ListResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/list.V2ListResponse",
            "example": {
              "message": "Success",
              "pagination": {
                "has_next": true,
                "has_previous": false,
                "page": 1,
                "page_size": 50,
                "total": 128,
                "total_pages": 3
              },
              "sources": [
                {
                  "additional_metadata": {
                    "author": "ada",
                    "doc_version": 3
                  },
                  "app_external_id": "C0123456789",
                  "app_kind": "slack",
                  "app_provider": "slack",
                  "collection": "team_docs",
                  "comments_truncated": true,
                  "database": "acme_corp",
                  "description": "Internal overview of the Project Phoenix rollout.",
                  "id": "HydraDoc1234",
                  "metadata": {
                    "department": "finance",
                    "priority": 7
                  },
                  "note": "Superseded by the Q3 rollout plan.",
                  "sub_tenant_id": "sub_tenant_4567",
                  "tenant_id": "tenant_1234",
                  "timestamp": "2026-07-02T10:00:00Z",
                  "title": "Project Phoenix Overview",
                  "type": "knowledge"
                }
              ],
              "success": true,
              "total": 128,
              "user_memories": [
                {
                  "additional_metadata": {
                    "author": "ada",
                    "doc_version": 3
                  },
                  "app_external_id": "C0123456789",
                  "app_kind": "slack",
                  "app_provider": "slack",
                  "collection": "team_docs",
                  "comments_truncated": true,
                  "database": "acme_corp",
                  "description": "Internal overview of the Project Phoenix rollout.",
                  "memory_id": "memory_1234",
                  "metadata": {
                    "department": "finance",
                    "priority": 7
                  },
                  "note": "Superseded by the Q3 rollout plan.",
                  "sub_tenant_id": "sub_tenant_4567",
                  "tenant_id": "tenant_1234",
                  "timestamp": "2026-07-02T10:00:00Z",
                  "title": "Project Phoenix Overview",
                  "type": "knowledge"
                }
              ]
            }
          },
          "error": {
            "$ref": "#/components/schemas/handler.apiError",
            "description": "Error message, empty string on success.",
            "example": {
              "code": "DATABASE_NOT_FOUND",
              "message": "Database not found"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/handler.responseMeta",
            "example": {
              "collection": "team_docs",
              "database": "acme_corp",
              "latency_ms": 12.3,
              "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
              "source_type": "file",
              "sub_tenant_id": "sub_tenant_4567",
              "tenant_id": "tenant_1234"
            }
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.Envelope-search_ChunkInspectResult": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/search.ChunkInspectResult",
            "example": {
              "chunks": [
                {
                  "additional_metadata": {
                    "author": "ada",
                    "doc_version": 3
                  },
                  "chunk_content": "HydraDB supports hybrid retrieval across knowledge and memories.",
                  "chunk_uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
                  "extra_context_ids": [
                    "HydraEmbeddings123_2",
                    "HydraEmbeddings123_3"
                  ],
                  "layout": "text",
                  "metadata": {
                    "department": "finance",
                    "priority": 7
                  },
                  "relevancy_score": 0.87,
                  "source_id": "HydraDoc1234",
                  "source_last_updated_time": "2026-07-02T12:30:00Z",
                  "source_title": "Project Phoenix Overview",
                  "source_type": "file",
                  "source_upload_time": "2026-07-02T10:00:00Z",
                  "sub_tenant_id": "sub_tenant_4567"
                }
              ],
              "is_truncated": false,
              "message": "Success",
              "success": true
            }
          },
          "error": {
            "$ref": "#/components/schemas/handler.apiError",
            "description": "Error message, empty string on success.",
            "example": {
              "code": "DATABASE_NOT_FOUND",
              "message": "Database not found"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/handler.responseMeta",
            "example": {
              "collection": "team_docs",
              "database": "acme_corp",
              "latency_ms": 12.3,
              "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
              "source_type": "file",
              "sub_tenant_id": "sub_tenant_4567",
              "tenant_id": "tenant_1234"
            }
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.Envelope-search_EntityProfileView": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/search.EntityProfileView",
            "example": {
              "entity_id": "entity_1a2b",
              "entries": [
                {
                  "confidence": 0.92
                }
              ],
              "name": "general",
              "pending_importance": 1,
              "version": 1
            }
          },
          "error": {
            "$ref": "#/components/schemas/handler.apiError",
            "description": "Error message, empty string on success.",
            "example": {
              "code": "DATABASE_NOT_FOUND",
              "message": "Database not found"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/handler.responseMeta",
            "example": {
              "collection": "team_docs",
              "database": "acme_corp",
              "latency_ms": 12.3,
              "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
              "source_type": "file",
              "sub_tenant_id": "sub_tenant_4567",
              "tenant_id": "tenant_1234"
            }
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.Envelope-search_V2RetrievalResult": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/search.V2RetrievalResult",
            "example": {
              "additional_context": "The user is a senior engineer onboarding to the platform.",
              "app_search_fusion": {
                "stats": {
                  "app_chunks": 1,
                  "app_has_exact_ids": true,
                  "app_lane_empty_text": true,
                  "consensus": 1,
                  "exact_candidates": 1,
                  "exact_promoted": 1,
                  "limit": 1,
                  "normal_chunks": 1,
                  "normal_displaced": 1,
                  "tail_added": 1,
                  "tail_candidates": 1
                },
                "stats_by_pass": [
                  {
                    "app_chunks": 1,
                    "app_has_exact_ids": true,
                    "app_lane_empty_text": true,
                    "consensus": 1,
                    "exact_candidates": 1,
                    "exact_promoted": 1,
                    "limit": 1,
                    "normal_chunks": 1,
                    "normal_displaced": 1,
                    "tail_added": 1,
                    "tail_candidates": 1
                  }
                ]
              },
              "chunks": [
                {
                  "additional_metadata": {
                    "author": "ada",
                    "doc_version": 3
                  },
                  "chunk_content": "HydraDB supports hybrid retrieval across knowledge and memories.",
                  "chunk_uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
                  "collection": "team_docs",
                  "extra_context_ids": [
                    "HydraEmbeddings123_2",
                    "HydraEmbeddings123_3"
                  ],
                  "id": "HydraDoc1234",
                  "layout": "text",
                  "metadata": {
                    "department": "finance",
                    "priority": 7
                  },
                  "relevancy_score": 0.87,
                  "source_last_updated_time": "2026-07-02T12:30:00Z",
                  "source_title": "Project Phoenix Overview",
                  "source_type": "file",
                  "source_upload_time": "2026-07-02T10:00:00Z",
                  "sub_tenant_id": "sub_tenant_4567"
                }
              ],
              "code_search": {
                "duration_ms": 0.5,
                "repos": [
                  {
                    "duration_ms": 0.5,
                    "error": "",
                    "status": "completed",
                    "truncated": true,
                    "unsigned": true
                  }
                ],
                "status": "completed"
              },
              "forceful_relations": {
                "declared": [
                  {
                    "chunk": {
                      "additional_metadata": {
                        "author": "ada",
                        "doc_version": 3
                      },
                      "chunk_content": "HydraDB supports hybrid retrieval across knowledge and memories.",
                      "chunk_uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
                      "collection": "team_docs",
                      "extra_context_ids": [
                        "HydraEmbeddings123_2",
                        "HydraEmbeddings123_3"
                      ],
                      "id": "HydraDoc1234",
                      "layout": "text",
                      "metadata": {
                        "department": "finance",
                        "priority": 7
                      },
                      "relevancy_score": 0.87,
                      "source_last_updated_time": "2026-07-02T12:30:00Z",
                      "source_title": "Project Phoenix Overview",
                      "source_type": "file",
                      "source_upload_time": "2026-07-02T10:00:00Z",
                      "sub_tenant_id": "sub_tenant_4567"
                    }
                  }
                ],
                "inferred": [
                  {
                    "chunk": {
                      "additional_metadata": {
                        "author": "ada",
                        "doc_version": 3
                      },
                      "chunk_content": "HydraDB supports hybrid retrieval across knowledge and memories.",
                      "chunk_uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
                      "collection": "team_docs",
                      "extra_context_ids": [
                        "HydraEmbeddings123_2",
                        "HydraEmbeddings123_3"
                      ],
                      "id": "HydraDoc1234",
                      "layout": "text",
                      "metadata": {
                        "department": "finance",
                        "priority": 7
                      },
                      "relevancy_score": 0.87,
                      "source_last_updated_time": "2026-07-02T12:30:00Z",
                      "source_title": "Project Phoenix Overview",
                      "source_type": "file",
                      "source_upload_time": "2026-07-02T10:00:00Z",
                      "sub_tenant_id": "sub_tenant_4567"
                    }
                  }
                ]
              },
              "graph": {
                "paths": [
                  {
                    "chunk_ids": [
                      "HydraEmbeddings123_0",
                      "HydraEmbeddings123_1"
                    ],
                    "combined_context": "Acme Corp deploys HydraDB in production for context retrieval.",
                    "relevancy_score": 0.87,
                    "triplets": [
                      {
                        "relation": {
                          "confidence": 0.92,
                          "predicate": "works_at"
                        },
                        "source": {
                          "entity_id": "entity_1a2b",
                          "name": "Ada",
                          "type": "person"
                        },
                        "target": {
                          "entity_id": "entity_3c4d",
                          "name": "Acme Corp",
                          "type": "organization"
                        }
                      }
                    ]
                  }
                ]
              },
              "graph_context": {
                "chunk_id_to_group_ids": {
                  "HydraEmbeddings123_0": [
                    "grp_1234"
                  ]
                },
                "chunk_relations": [
                  {
                    "combined_context": "Acme Corp deploys HydraDB in production for context retrieval.",
                    "group_id": "grp_1234",
                    "relevancy_score": 0.87,
                    "source_chunk_ids": [
                      "HydraEmbeddings123_0",
                      "HydraEmbeddings123_1"
                    ],
                    "triplets": [
                      {
                        "relation": {
                          "confidence": 0.92,
                          "predicate": "works_at"
                        },
                        "source": {
                          "entity_id": "entity_1a2b",
                          "name": "Ada",
                          "type": "person"
                        },
                        "target": {
                          "entity_id": "entity_3c4d",
                          "name": "Acme Corp",
                          "type": "organization"
                        }
                      }
                    ]
                  }
                ],
                "query_paths": [
                  {
                    "combined_context": "Acme Corp deploys HydraDB in production for context retrieval.",
                    "group_id": "grp_1234",
                    "relevancy_score": 0.87,
                    "source_chunk_ids": [
                      "HydraEmbeddings123_0",
                      "HydraEmbeddings123_1"
                    ],
                    "triplets": [
                      {
                        "relation": {
                          "confidence": 0.92,
                          "predicate": "works_at"
                        },
                        "source": {
                          "entity_id": "entity_1a2b",
                          "name": "Ada",
                          "type": "person"
                        },
                        "target": {
                          "entity_id": "entity_3c4d",
                          "name": "Acme Corp",
                          "type": "organization"
                        }
                      }
                    ]
                  }
                ]
              },
              "profile_context": {
                "entity_id": "entity_1a2b",
                "entries": [
                  {
                    "confidence": 0.92
                  }
                ],
                "name": "general",
                "version": 1
              },
              "profile_filter": {
                "applied": true,
                "degraded": true,
                "entity_id": "entity_1a2b",
                "found": true,
                "selected_entries": 1,
                "version": 1
              },
              "source_facts": [
                {
                  "app_kind": "slack",
                  "chunk_id": "HydraEmbeddings123_0",
                  "provider": "slack",
                  "relationship_id": "rel_1234",
                  "source_id": "HydraDoc1234",
                  "synced_at": 1
                }
              ],
              "source_filter": {
                "applied": true,
                "degraded": true,
                "matched_facts": 1,
                "mode": "thinking",
                "provider": "slack",
                "thread_scope": true,
                "truncated": true
              },
              "sources": [
                {
                  "additional_metadata": {
                    "author": "ada",
                    "doc_version": 3
                  },
                  "app_external_id": "C0123456789",
                  "app_kind": "slack",
                  "app_provider": "slack",
                  "collection": "team_docs",
                  "description": "Internal overview of the Project Phoenix rollout.",
                  "id": "HydraDoc1234",
                  "metadata": {
                    "department": "finance",
                    "priority": 7
                  },
                  "sub_tenant_id": "sub_tenant_4567",
                  "timestamp": "2026-07-02T10:00:00Z",
                  "title": "Project Phoenix Overview",
                  "type": "knowledge",
                  "url": "https://docs.hydradb.com/phoenix"
                }
              ],
              "temporal_duration": {
                "approximate": true,
                "days": 1,
                "from": {
                  "chunk_id": "HydraEmbeddings123_0",
                  "event_end": 1,
                  "event_start": 1,
                  "relationship_id": "rel_1234",
                  "source_id": "HydraDoc1234",
                  "status": "completed"
                },
                "pairing_confidence": 0.5,
                "to": {
                  "chunk_id": "HydraEmbeddings123_0",
                  "event_end": 1,
                  "event_start": 1,
                  "relationship_id": "rel_1234",
                  "source_id": "HydraDoc1234",
                  "status": "completed"
                }
              },
              "temporal_facts": [
                {
                  "chunk_id": "HydraEmbeddings123_0",
                  "event_end": 1,
                  "event_start": 1,
                  "relationship_id": "rel_1234",
                  "source_id": "HydraDoc1234",
                  "status": "completed"
                }
              ],
              "temporal_filter": {
                "applied": true,
                "chunk_scope": 1,
                "degraded": true,
                "matched_facts": 1,
                "mode": "thinking",
                "promoted": 1,
                "truncated": true
              }
            }
          },
          "error": {
            "$ref": "#/components/schemas/handler.apiError",
            "description": "Error message, empty string on success.",
            "example": {
              "code": "DATABASE_NOT_FOUND",
              "message": "Database not found"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/handler.responseMeta",
            "example": {
              "collection": "team_docs",
              "database": "acme_corp",
              "latency_ms": 12.3,
              "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
              "source_type": "file",
              "sub_tenant_id": "sub_tenant_4567",
              "tenant_id": "tenant_1234"
            }
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.Envelope-sources_MemoryDeleteResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/sources.MemoryDeleteResponse",
            "example": {
              "deleted_count": 1,
              "message": "Success",
              "results": [
                {
                  "deleted": true,
                  "error": "",
                  "id": "HydraDoc1234"
                }
              ],
              "success": true,
              "user_memory_deleted": 1
            }
          },
          "error": {
            "$ref": "#/components/schemas/handler.apiError",
            "description": "Error message, empty string on success.",
            "example": {
              "code": "DATABASE_NOT_FOUND",
              "message": "Database not found"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/handler.responseMeta",
            "example": {
              "collection": "team_docs",
              "database": "acme_corp",
              "latency_ms": 12.3,
              "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
              "source_type": "file",
              "sub_tenant_id": "sub_tenant_4567",
              "tenant_id": "tenant_1234"
            }
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.Envelope-tenants_InfraStatusResponseV2": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/tenants.InfraStatusResponseV2",
            "example": {
              "database": "acme_corp",
              "infra": {
                "graph_status": true,
                "ready_for_ingestion": true,
                "scheduler_status": true,
                "vectorstore_status": {
                  "knowledge": true,
                  "memories": true
                }
              },
              "message": "Success",
              "org_id": "org_1a2b3c",
              "tenant_id": "tenant_1234",
              "type": "split"
            }
          },
          "error": {
            "$ref": "#/components/schemas/handler.apiError",
            "description": "Error message, empty string on success.",
            "example": {
              "code": "DATABASE_NOT_FOUND",
              "message": "Database not found"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/handler.responseMeta",
            "example": {
              "collection": "team_docs",
              "database": "acme_corp",
              "latency_ms": 12.3,
              "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
              "source_type": "file",
              "sub_tenant_id": "sub_tenant_4567",
              "tenant_id": "tenant_1234"
            }
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.Envelope-tenants_SubTenantDeleteResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/tenants.SubTenantDeleteResponse",
            "example": {
              "collection": "team_docs",
              "database": "acme_corp",
              "message": "Success",
              "status": "completed",
              "sub_tenant_id": "sub_tenant_4567",
              "tenant_id": "tenant_1234"
            }
          },
          "error": {
            "$ref": "#/components/schemas/handler.apiError",
            "description": "Error message, empty string on success.",
            "example": {
              "code": "DATABASE_NOT_FOUND",
              "message": "Database not found"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/handler.responseMeta",
            "example": {
              "collection": "team_docs",
              "database": "acme_corp",
              "latency_ms": 12.3,
              "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
              "source_type": "file",
              "sub_tenant_id": "sub_tenant_4567",
              "tenant_id": "tenant_1234"
            }
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.Envelope-tenants_SubTenantIdsResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/tenants.SubTenantIdsResponse",
            "example": {
              "collections": [
                "team_docs",
                "engineering"
              ],
              "message": "Success",
              "sub_tenant_ids": [
                "sub_tenant_4567",
                "sub_tenant_8901"
              ]
            }
          },
          "error": {
            "$ref": "#/components/schemas/handler.apiError",
            "description": "Error message, empty string on success.",
            "example": {
              "code": "DATABASE_NOT_FOUND",
              "message": "Database not found"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/handler.responseMeta",
            "example": {
              "collection": "team_docs",
              "database": "acme_corp",
              "latency_ms": 12.3,
              "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
              "source_type": "file",
              "sub_tenant_id": "sub_tenant_4567",
              "tenant_id": "tenant_1234"
            }
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.Envelope-tenants_TenantCreateAcceptedResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/tenants.TenantCreateAcceptedResponse",
            "example": {
              "database": "acme_corp",
              "message": "Success",
              "status": "completed",
              "tenant_id": "tenant_1234"
            }
          },
          "error": {
            "$ref": "#/components/schemas/handler.apiError",
            "description": "Error message, empty string on success.",
            "example": {
              "code": "DATABASE_NOT_FOUND",
              "message": "Database not found"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/handler.responseMeta",
            "example": {
              "collection": "team_docs",
              "database": "acme_corp",
              "latency_ms": 12.3,
              "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
              "source_type": "file",
              "sub_tenant_id": "sub_tenant_4567",
              "tenant_id": "tenant_1234"
            }
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.Envelope-tenants_TenantDeleteResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/tenants.TenantDeleteResponse",
            "example": {
              "database": "acme_corp",
              "message": "Success",
              "status": "completed",
              "tenant_id": "tenant_1234"
            }
          },
          "error": {
            "$ref": "#/components/schemas/handler.apiError",
            "description": "Error message, empty string on success.",
            "example": {
              "code": "DATABASE_NOT_FOUND",
              "message": "Database not found"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/handler.responseMeta",
            "example": {
              "collection": "team_docs",
              "database": "acme_corp",
              "latency_ms": 12.3,
              "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
              "source_type": "file",
              "sub_tenant_id": "sub_tenant_4567",
              "tenant_id": "tenant_1234"
            }
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.Envelope-tenants_TenantIdsResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/tenants.TenantIdsResponse",
            "example": {
              "databases": [
                "acme_corp",
                "research_kb"
              ],
              "details": [
                {
                  "database": "acme_corp",
                  "type": "split"
                }
              ],
              "failed_databases": [
                {
                  "database": "acme_corp",
                  "error": "",
                  "tenant_id": "tenant_1234"
                }
              ],
              "failed_tenant_ids": [
                {
                  "database": "acme_corp",
                  "error": "",
                  "tenant_id": "tenant_1234"
                }
              ],
              "message": "Success",
              "tenant_ids": [
                "tenant_1234",
                "tenant_5678"
              ]
            }
          },
          "error": {
            "$ref": "#/components/schemas/handler.apiError",
            "description": "Error message, empty string on success.",
            "example": {
              "code": "DATABASE_NOT_FOUND",
              "message": "Database not found"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/handler.responseMeta",
            "example": {
              "collection": "team_docs",
              "database": "acme_corp",
              "latency_ms": 12.3,
              "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
              "source_type": "file",
              "sub_tenant_id": "sub_tenant_4567",
              "tenant_id": "tenant_1234"
            }
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.Envelope-tenants_TenantMetadataSchemaResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/tenants.TenantMetadataSchemaResponse",
            "example": {
              "database": "acme_corp",
              "fields": [
                {
                  "data_type": "VARCHAR",
                  "enable_dense_embedding": true,
                  "enable_match": true,
                  "enable_sparse_embedding": false,
                  "max_length": 256,
                  "name": "category"
                }
              ],
              "tenant_id": "acme_corp"
            }
          },
          "error": {
            "$ref": "#/components/schemas/handler.apiError",
            "description": "Error message, empty string on success.",
            "example": {
              "code": "DATABASE_NOT_FOUND",
              "message": "Database not found"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/handler.responseMeta",
            "example": {
              "collection": "team_docs",
              "database": "acme_corp",
              "latency_ms": 12.3,
              "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
              "source_type": "file",
              "sub_tenant_id": "sub_tenant_4567",
              "tenant_id": "tenant_1234"
            }
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.Envelope-tenants_TenantRenameResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/tenants.TenantRenameResponse",
            "example": {
              "connector_reassignment": "complete",
              "database": "acme_corp",
              "message": "Success",
              "status": "completed",
              "tenant_id": "tenant_1234"
            }
          },
          "error": {
            "$ref": "#/components/schemas/handler.apiError",
            "description": "Error message, empty string on success.",
            "example": {
              "code": "DATABASE_NOT_FOUND",
              "message": "Database not found"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/handler.responseMeta",
            "example": {
              "collection": "team_docs",
              "database": "acme_corp",
              "latency_ms": 12.3,
              "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
              "source_type": "file",
              "sub_tenant_id": "sub_tenant_4567",
              "tenant_id": "tenant_1234"
            }
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.Envelope-tenants_TenantStatsResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/tenants.TenantStatsResponse",
            "example": {
              "database": "acme_corp",
              "knowledge_collection": {
                "row_count": 1280
              },
              "memory_collection": {
                "row_count": 1280
              },
              "message": "Success",
              "tenant_id": "tenant_1234"
            }
          },
          "error": {
            "$ref": "#/components/schemas/handler.apiError",
            "description": "Error message, empty string on success.",
            "example": {
              "code": "DATABASE_NOT_FOUND",
              "message": "Database not found"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/handler.responseMeta",
            "example": {
              "collection": "team_docs",
              "database": "acme_corp",
              "latency_ms": 12.3,
              "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
              "source_type": "file",
              "sub_tenant_id": "sub_tenant_4567",
              "tenant_id": "tenant_1234"
            }
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.Envelope-webhooks_DeliveryItem": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/webhooks.DeliveryItem",
            "example": {
              "attempts": 1,
              "created_at": "2026-07-02T10:00:00Z",
              "delivery_id": "dlv_9f8e7d6c",
              "doc_id": "HydraDoc1234",
              "error_code": "",
              "error_message": "",
              "event_type": "indexing.status_changed",
              "indexing_status": "completed",
              "status": "completed",
              "updated_at": "2026-07-02T10:00:05Z"
            }
          },
          "error": {
            "$ref": "#/components/schemas/handler.apiError",
            "description": "Error message, empty string on success.",
            "example": {
              "code": "DATABASE_NOT_FOUND",
              "message": "Database not found"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/handler.responseMeta",
            "example": {
              "collection": "team_docs",
              "database": "acme_corp",
              "latency_ms": 12.3,
              "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
              "source_type": "file",
              "sub_tenant_id": "sub_tenant_4567",
              "tenant_id": "tenant_1234"
            }
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.Envelope-webhooks_DeliveryListResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/webhooks.DeliveryListResponse",
            "example": {
              "count": 12,
              "deliveries": [
                {
                  "attempts": 1,
                  "created_at": "2026-07-02T10:00:00Z",
                  "delivery_id": "dlv_9f8e7d6c",
                  "doc_id": "HydraDoc1234",
                  "error_code": "",
                  "error_message": "",
                  "event_type": "indexing.status_changed",
                  "indexing_status": "completed",
                  "status": "completed",
                  "updated_at": "2026-07-02T10:00:05Z"
                }
              ],
              "next_cursor": "eyJvZmZzZXQiOjUwfQ=="
            }
          },
          "error": {
            "$ref": "#/components/schemas/handler.apiError",
            "description": "Error message, empty string on success.",
            "example": {
              "code": "DATABASE_NOT_FOUND",
              "message": "Database not found"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/handler.responseMeta",
            "example": {
              "collection": "team_docs",
              "database": "acme_corp",
              "latency_ms": 12.3,
              "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
              "source_type": "file",
              "sub_tenant_id": "sub_tenant_4567",
              "tenant_id": "tenant_1234"
            }
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.Envelope-webhooks_RetryResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/webhooks.RetryResponse",
            "example": {
              "delivery_id": "dlv_9f8e7d6c",
              "message": "Success",
              "queued": true
            }
          },
          "error": {
            "$ref": "#/components/schemas/handler.apiError",
            "description": "Error message, empty string on success.",
            "example": {
              "code": "DATABASE_NOT_FOUND",
              "message": "Database not found"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/handler.responseMeta",
            "example": {
              "collection": "team_docs",
              "database": "acme_corp",
              "latency_ms": 12.3,
              "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
              "source_type": "file",
              "sub_tenant_id": "sub_tenant_4567",
              "tenant_id": "tenant_1234"
            }
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.Envelope-webhooks_SigningSecretResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/webhooks.SigningSecretResponse",
            "example": {
              "generated": true,
              "message": "Success",
              "signing_secret": "whsec_EXAMPLE_ONLY_THIS_IS_NOT_A_REAL_SIGNING_KEY"
            }
          },
          "error": {
            "$ref": "#/components/schemas/handler.apiError",
            "description": "Error message, empty string on success.",
            "example": {
              "code": "DATABASE_NOT_FOUND",
              "message": "Database not found"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/handler.responseMeta",
            "example": {
              "collection": "team_docs",
              "database": "acme_corp",
              "latency_ms": 12.3,
              "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
              "source_type": "file",
              "sub_tenant_id": "sub_tenant_4567",
              "tenant_id": "tenant_1234"
            }
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.Envelope-webhooks_WebhookDeleteResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/webhooks.WebhookDeleteResponse",
            "example": {
              "deleted": true,
              "message": "Success"
            }
          },
          "error": {
            "$ref": "#/components/schemas/handler.apiError",
            "description": "Error message, empty string on success.",
            "example": {
              "code": "DATABASE_NOT_FOUND",
              "message": "Database not found"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/handler.responseMeta",
            "example": {
              "collection": "team_docs",
              "database": "acme_corp",
              "latency_ms": 12.3,
              "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
              "source_type": "file",
              "sub_tenant_id": "sub_tenant_4567",
              "tenant_id": "tenant_1234"
            }
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.Envelope-webhooks_WebhookGetResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/webhooks.WebhookGetResponse",
            "example": {
              "event_types": [
                "indexing.status_changed"
              ],
              "registered": true,
              "signing_secret_configured": true,
              "url": "https://docs.hydradb.com/phoenix"
            }
          },
          "error": {
            "$ref": "#/components/schemas/handler.apiError",
            "description": "Error message, empty string on success.",
            "example": {
              "code": "DATABASE_NOT_FOUND",
              "message": "Database not found"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/handler.responseMeta",
            "example": {
              "collection": "team_docs",
              "database": "acme_corp",
              "latency_ms": 12.3,
              "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
              "source_type": "file",
              "sub_tenant_id": "sub_tenant_4567",
              "tenant_id": "tenant_1234"
            }
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.Envelope-webhooks_WebhookRegisterResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/webhooks.WebhookRegisterResponse",
            "example": {
              "event_types": [
                "indexing.status_changed"
              ],
              "message": "Success",
              "registered": true,
              "signing_secret": "whsec_EXAMPLE_ONLY_THIS_IS_NOT_A_REAL_SIGNING_KEY",
              "signing_secret_configured": true,
              "url": "https://docs.hydradb.com/phoenix"
            }
          },
          "error": {
            "$ref": "#/components/schemas/handler.apiError",
            "description": "Error message, empty string on success.",
            "example": {
              "code": "DATABASE_NOT_FOUND",
              "message": "Database not found"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/handler.responseMeta",
            "example": {
              "collection": "team_docs",
              "database": "acme_corp",
              "latency_ms": 12.3,
              "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
              "source_type": "file",
              "sub_tenant_id": "sub_tenant_4567",
              "tenant_id": "tenant_1234"
            }
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.Envelope-webhooks_WebhookTestResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/webhooks.WebhookTestResponse",
            "example": {
              "delivered": true,
              "message": "Success",
              "status_code": 200
            }
          },
          "error": {
            "$ref": "#/components/schemas/handler.apiError",
            "description": "Error message, empty string on success.",
            "example": {
              "code": "DATABASE_NOT_FOUND",
              "message": "Database not found"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/handler.responseMeta",
            "example": {
              "collection": "team_docs",
              "database": "acme_corp",
              "latency_ms": 12.3,
              "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
              "source_type": "file",
              "sub_tenant_id": "sub_tenant_4567",
              "tenant_id": "tenant_1234"
            }
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.ErrorDetail": {
        "properties": {
          "deprecated": {
            "description": "Whether this response concerns a deprecated field or route.",
            "example": true,
            "type": "boolean"
          },
          "deprecated_field": {
            "description": "The deprecated field name.",
            "example": "tenant_id",
            "type": "string"
          },
          "error_code": {
            "description": "Machine-readable error classification code.",
            "example": "VALIDATION_ERROR",
            "type": "string"
          },
          "message": {
            "description": "Human-readable description of the error.",
            "example": "Request validation failed",
            "type": "string"
          },
          "preferred_field": {
            "description": "The canonical replacement for the deprecated field.",
            "example": "database",
            "type": "string"
          },
          "success": {
            "deprecated": true,
            "description": "Deprecated for API clients: always false on this path, so it carries no\ninformation. To detect a failure read the HTTP status code; for what\nwent wrong read the envelope's error.code and error.message, and\nmeta.request_id when reporting it. The whole `detail` object is\ndeprecated legacy — tagging the field individually so SDK users see it\non the property, not just the container (PRO-1208).",
            "example": true,
            "type": "boolean",
            "x-deprecated": "true"
          }
        },
        "type": "object"
      },
      "handler.ErrorEnvelope-sources_MemoryDeleteResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/sources.MemoryDeleteResponse",
            "example": {
              "deleted_count": 1,
              "message": "Success",
              "results": [
                {
                  "deleted": true,
                  "error": "",
                  "id": "HydraDoc1234"
                }
              ],
              "success": true,
              "user_memory_deleted": 1
            }
          },
          "detail": {
            "$ref": "#/components/schemas/handler.ErrorDetail",
            "example": {
              "deprecated": true,
              "deprecated_field": "tenant_id",
              "error_code": "VALIDATION_ERROR",
              "message": "Request validation failed",
              "preferred_field": "database"
            }
          },
          "error": {
            "$ref": "#/components/schemas/handler.apiError",
            "description": "Error message, empty string on success.",
            "example": {
              "code": "DATABASE_NOT_FOUND",
              "message": "Database not found"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/handler.ErrorMeta",
            "example": {
              "latency_ms": 12.3,
              "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d"
            }
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.ErrorMeta": {
        "properties": {
          "api_version": {
            "type": "string"
          },
          "latency_ms": {
            "example": 12.3,
            "type": "number"
          },
          "request_id": {
            "description": "Unique identifier for this request, useful for support and tracing.",
            "example": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
            "type": "string"
          }
        },
        "type": "object"
      },
      "handler.ErrorResponse": {
        "properties": {
          "data": {},
          "detail": {
            "$ref": "#/components/schemas/handler.ErrorDetail",
            "description": "Structured error detail with code, message, and deprecation hints.",
            "example": {
              "deprecated": true,
              "deprecated_field": "tenant_id",
              "error_code": "VALIDATION_ERROR",
              "message": "Request validation failed",
              "preferred_field": "database"
            }
          },
          "error": {
            "$ref": "#/components/schemas/handler.apiError",
            "description": "Error message, empty string on success.",
            "example": {
              "code": "DATABASE_NOT_FOUND",
              "message": "Database not found"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/handler.ErrorMeta",
            "example": {
              "latency_ms": 12.3,
              "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d"
            }
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.apiError": {
        "properties": {
          "code": {
            "description": "Machine-readable error code (e.g. `DATABASE_NOT_FOUND`).",
            "example": "DATABASE_NOT_FOUND",
            "type": "string"
          },
          "message": {
            "description": "Human-readable description of the error.",
            "example": "Database not found",
            "type": "string"
          }
        },
        "type": "object"
      },
      "handler.catalogConnector": {
        "properties": {
          "category": {
            "type": "string"
          },
          "is_alpha": {
            "example": true,
            "type": "boolean"
          },
          "is_beta": {
            "example": true,
            "type": "boolean"
          },
          "moveit_support": {
            "example": true,
            "type": "boolean"
          },
          "provider": {
            "description": "External provider being synced (e.g. `slack`, `github`, `linear`, `notion`, `gmail`).",
            "example": "slack",
            "type": "string"
          },
          "rank": {
            "description": "Rank is the dashboard display order (lower first); null means unranked.",
            "example": 1,
            "type": "integer"
          },
          "rbac_description": {
            "type": "string"
          },
          "rbac_support": {
            "description": "RBACSupport reports whether document-level ACL capture (PRO-1684) is\nenabled for this provider (the acl_supported control-plane flag), and\nRBACDescription says in one sentence WHAT is captured, so the dashboard\ncan explain the capability instead of showing a bare boolean.",
            "example": true,
            "type": "boolean"
          },
          "supported": {
            "example": true,
            "type": "boolean"
          },
          "webhook_support": {
            "description": "WebhookSupport marks a provider fed by an inbound webhook. The dashboard\nneeds it to pick the credential form: it otherwise reads moveit_support=false\nas \"classic\", and renders the single-token form instead of the provider's\ndeclared credential schema.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.configureReq": {
        "properties": {
          "backfill_chunk_interval_seconds": {
            "description": "Internal interval for async backfill paging.",
            "example": 86400,
            "type": "integer"
          },
          "full_visibility_roles": {
            "description": "FullVisibilityRoles names the HubSpot roles whose members can see every\nrecord (PRO-2036). Resolved to ids against the portal at configure time\nand stored on the account-wide resource row. A pointer so an omitted\nfield keeps the current setting while an explicit [] clears it.",
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false
          },
          "lookback_days": {
            "description": "How far back the first sync fetches historical data. Only applies to the initial sync — subsequent syncs are incremental from the last cursor.",
            "example": 30,
            "type": "integer"
          },
          "resources": {
            "description": "Resources to activate for this connector. Each item corresponds to one entry from the Discover endpoint.",
            "example": [
              {
                "additional_metadata": {
                  "author": "ada",
                  "doc_version": 3
                },
                "collection": "team_docs",
                "database": "acme_corp",
                "metadata": {
                  "department": "finance",
                  "priority": 7
                },
                "name": "general",
                "resource_id": "C0123456789",
                "resource_type": "channel"
              }
            ],
            "items": {
              "$ref": "#/components/schemas/handler.resourceMapping"
            },
            "type": "array",
            "uniqueItems": false
          },
          "table_configs": {
            "description": "TableConfigs carries per-table replication settings for MOVEIT\nconnectors whose tap reads a `table_configs` credential input (bigquery).\nConfigure merges them into the stored credential bundle before the first\nsync, so the mode chosen at selection time governs every sync from the\nstart. Optional; rejected for non-MOVEIT engines.",
            "items": {
              "$ref": "#/components/schemas/handler.tableConfigEntry"
            },
            "type": "array",
            "uniqueItems": false
          }
        },
        "required": [
          "resources"
        ],
        "type": "object"
      },
      "handler.configureResponse": {
        "properties": {
          "backfill": {
            "example": true,
            "type": "boolean"
          },
          "configured": {
            "example": 1,
            "type": "integer"
          },
          "connector_id": {
            "description": "Connector this resource belongs to.",
            "example": "conn_abc123",
            "type": "string"
          },
          "first_sync_at": {
            "description": "FirstSyncAt/Message state the timing expectation: whether the first\nsync is already running (configure triggers one) or when the scheduled\none runs, so clients stop inventing their own copy (PRO-1565).",
            "type": "string"
          },
          "message": {
            "description": "Human-readable result message.",
            "example": "Success",
            "type": "string"
          },
          "meta": {
            "$ref": "#/components/schemas/handler.configureResponseMeta"
          },
          "warnings": {
            "description": "Warnings names resources that were saved but produced nothing when\nprobed. They are valid — the user may know a table is empty and expect it\nto fill — so they are not rejected, but they are the case that is\notherwise indistinguishable from success at every layer, so they are\nnever saved silently either.",
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false
          }
        },
        "type": "object"
      },
      "handler.configureResponseMeta": {
        "properties": {
          "deprecation": {
            "items": {
              "$ref": "#/components/schemas/handler.deprecationNotice"
            },
            "type": "array",
            "uniqueItems": false
          }
        },
        "type": "object"
      },
      "handler.connectorAPIView": {
        "properties": {
          "acl_changes_cursor": {
            "description": "ACLChangesCursor is the provider permission-change feed's persisted\ncursor (PRO-1684; e.g. the Drive changes.list page token). Empty means\nuninitialized: the next cycle fetches a baseline and starts from now.\nAdvanced ONLY after every reported change was applied, so a failed\napply replays the same changes next cycle (at-least-once; the writes\nare idempotent full replacements).",
            "type": "string"
          },
          "active_resource_count": {
            "description": "ActiveResourceCount mirrors the number of non-disabled resource rows so\nlist responses can distinguish \"no resources configured yet\"\n(pending_setup) without a per-connector resources query.",
            "example": 1,
            "type": "integer"
          },
          "auth_type": {
            "description": "Authentication method for the provider connection (e.g. `api_token`, `oauth`).",
            "example": "api_token",
            "type": "string"
          },
          "collection": {
            "description": "Collection scope. Defaults to the default collection when omitted. Formerly `sub_tenant_id`; the `sub_tenant_id` alias is still accepted (deprecated).",
            "example": "team_docs",
            "type": "string"
          },
          "connector_id": {
            "description": "Connector this resource belongs to.",
            "example": "conn_abc123",
            "type": "string"
          },
          "custom_instructions": {
            "description": "CustomInstructions is optional free-text guidance applied when this\nconnector's documents are ingested: it steers how content is interpreted\nand indexed. Max 4000 characters; changes apply from the next sync cycle.",
            "type": "string"
          },
          "database": {
            "description": "Database/Collection are the canonical v2 names for the deprecated\ntenant_id/sub_tenant_id wire fields. They mirror the same values so a v2\nclient sees the canonical names on responses while a legacy client keeps\nreading tenant_id/sub_tenant_id. Not persisted (dynamodbav:\"-\"): the store\nbuilds items from tenant_id/sub_tenant_id and mirrors these on load. They\nare populated at every construction point (toConnector, connectorFromItem)\nrather than via MarshalJSON so Temporal's JSON data converter round-trips\nConnector activity inputs without spuriously populating them.",
            "example": "acme_corp",
            "type": "string"
          },
          "documents_dispatched": {
            "description": "DocumentsDispatched is the running total of objects handed to ingestion\nacross all completed cycles. It is dispatch *activity*, not an indexed\ncount: upserts count every time they change, deletes are never\nsubtracted, and an activity retry can double-count. Suitable as an\nis-data-moving signal, never as \"N documents indexed\".",
            "example": 1,
            "type": "integer"
          },
          "first_data_dispatched_at": {
            "description": "FirstDataDispatchedAt is set once, by the first completed cycle that\ndispatched more than zero objects. Its presence is what proves the\npipeline end to end; after it is set, an empty cycle is \"nothing changed\nat the source\", not \"still ingesting\".",
            "type": "string"
          },
          "last_attempted_sync_at": {
            "description": "RFC3339 timestamp of the most recent sync attempt (successful or not).",
            "example": "2026-07-02T17:00:00Z",
            "type": "string"
          },
          "last_error": {
            "description": "Error message from the most recent failed sync, empty string when no error.",
            "example": "",
            "type": "string"
          },
          "last_successful_sync_at": {
            "description": "RFC3339 timestamp of the last successful sync completion.",
            "example": "2026-07-02T17:00:00Z",
            "type": "string"
          },
          "lifecycle": {
            "description": "Lifecycle is the derived what-is-it-doing-now field and the one status\nclients should read (PRO-1565): reconnect | syncing | pending_setup |\ningesting | active. The embedded `status` field is a scheduler-internal\nconstant (\"active\" always) kept only for compatibility, and `sync_status`\nis the narrower mid-cycle indicator. Computed at the HTTP boundary from\nthe connector's stored facts, never persisted, so it cannot disagree\nwith them.",
            "type": "string"
          },
          "name": {
            "description": "Human-readable label for this resource.",
            "example": "general",
            "type": "string"
          },
          "needs_reauth": {
            "example": true,
            "type": "boolean"
          },
          "needs_reauth_at": {
            "type": "string"
          },
          "needs_reauth_reason": {
            "type": "string"
          },
          "next_sync_at": {
            "description": "RFC3339 timestamp when the next scheduled sync will run.",
            "example": "2026-07-02T18:00:00Z",
            "type": "string"
          },
          "paused": {
            "description": "Paused marks a connector its owner deliberately stopped (PRO-1762). It\nparks next_sync_at as SyncBlocked does, but stays a separate field:\nblocking clears itself once the cause is fixed, whereas only an explicit\nresume lifts a pause. Resources keep their committed provider_cursor, so\nresuming continues from where each stream stopped.",
            "example": true,
            "type": "boolean"
          },
          "paused_at": {
            "type": "string"
          },
          "paused_next_sync_at": {
            "description": "PausedNextSyncAt preserves the schedule the pause displaced. Resume makes\nthe connector due immediately, so this is read back only to recover from\na pause applied by mistake.",
            "type": "string"
          },
          "provider": {
            "description": "External provider being synced (e.g. `slack`, `github`, `linear`, `notion`, `gmail`).",
            "example": "slack",
            "type": "string"
          },
          "provider_account_scope": {
            "description": "Identifier for the external account (e.g. Slack workspace ID, GitHub org name). Must be distinct across connectors for the same provider.",
            "example": "T12345ACME",
            "type": "string"
          },
          "resources_pending_first_sync": {
            "description": "ResourcesPendingFirstSync counts active resources whose provider_cursor\nis still empty — resources that have never been successfully pulled.\nMOVEIT commits provider_cursor after every successful pull (even a\nzero-row one), so this self-clears one cycle after each resource first\nsyncs. Recomputed by the MOVEIT sync workflow each cycle and by the\nresource-mutating handlers, so a resource added to a long-active\nconnector re-enters the ingesting state.",
            "example": 1,
            "type": "integer"
          },
          "status": {
            "description": "Current lifecycle or processing state.",
            "example": "completed",
            "type": "string"
          },
          "sub_tenant_id": {
            "deprecated": true,
            "example": "sub_tenant_4567",
            "type": "string",
            "x-deprecated": "true"
          },
          "sync_blocked": {
            "description": "NeedsReauth is set by MOVEIT's OAuth refresh sweep when the provider has\nrejected the connector's refresh token (`invalid_grant` — expired, revoked,\nor, for a provider with single-use tokens, already spent).\n\nIt is deliberately distinct from LastError, which records a *sync* failure.\nThis is the one failure class no amount of retrying resolves: the stored\ngrant is gone and only the tenant can mint a new one. Surfacing it as its\nown field is what lets a client show \"reconnect\" instead of a generic\n\"sync failed\", and the sweep clears it automatically on the next successful\nrotation, so a client can trust the absence of the flag as much as its\npresence.\n\nOnly ever set on OAuth-bundle connectors. A connector authenticated with a\nstatic token or with client credentials (X posts: see the `client_id` /\n`client_secret` inputs on tap-twitter) has no refresh token and therefore\ncannot reach this state at all — which is the reason to prefer that shape\nwhere a provider offers it.\nSyncBlocked marks a connector stopped by a terminal failure — one no\nretry can fix. The scheduler skips it and next_sync_at is parked a\ncentury out; only a credential or config update clears it. Distinct from\nNeedsReauth, which is the OAuth sweep's own narrower signal: this covers\nany provider rejection of the stored credentials, including static keys\nthat have no refresh token to sweep.",
            "example": true,
            "type": "boolean"
          },
          "sync_blocked_at": {
            "type": "string"
          },
          "sync_blocked_reason": {
            "type": "string"
          },
          "sync_cycles_completed": {
            "description": "SyncCyclesCompleted counts successfully completed sync cycles. Bounded\nuse only: it lets DeriveLifecycle stop reporting \"ingesting\" after a few\nclean-but-empty cycles on a source that genuinely has nothing to pull.",
            "example": 1,
            "type": "integer"
          },
          "sync_engine": {
            "description": "SyncEngine is \"classic\" (default, empty treated as classic) or \"moveit\".\nSee the SyncEngine* constants; the scheduler branches on it.",
            "type": "string"
          },
          "sync_interval_seconds": {
            "description": "How frequently the scheduler triggers incremental syncs, in seconds. Bounded per provider; send 0 or omit to use the provider default. Change it later with PATCH /connectors/{id}.",
            "example": 3600,
            "type": "integer"
          },
          "sync_status": {
            "description": "Current sync operation state (e.g. `idle`, `running`).",
            "example": "idle",
            "type": "string"
          },
          "tenant_id": {
            "deprecated": true,
            "example": "tenant_1234",
            "type": "string",
            "x-deprecated": "true"
          }
        },
        "type": "object"
      },
      "handler.connectorCatalogResponse": {
        "properties": {
          "connectors": {
            "example": [
              {
                "is_alpha": true,
                "is_beta": true,
                "moveit_support": true,
                "provider": "slack",
                "rank": 1,
                "rbac_support": true,
                "supported": true,
                "webhook_support": true
              }
            ],
            "items": {
              "$ref": "#/components/schemas/handler.catalogConnector"
            },
            "type": "array",
            "uniqueItems": false
          }
        },
        "type": "object"
      },
      "handler.connectorCreateReq": {
        "properties": {
          "auth_type": {
            "description": "Authentication method for the provider connection (e.g. `api_token`, `oauth`).",
            "example": "api_token",
            "type": "string"
          },
          "collection": {
            "description": "Default collection partition for synced objects. Deprecated alias: `sub_tenant_id`.",
            "example": "team_docs",
            "type": "string"
          },
          "credentials": {
            "additionalProperties": {},
            "description": "Provider-specific credentials (typically `{\"api_token\": \"...\"}` or `{\"access_token\": \"...\"}`).",
            "example": {
              "api_token": "xoxb-..."
            },
            "type": "object"
          },
          "custom_instructions": {
            "description": "CustomInstructions optionally steers how this connector's synced\ndocuments are ingested and indexed. Max 4000 characters; editable later\nvia PATCH.",
            "type": "string"
          },
          "database": {
            "description": "Database/Collection are the canonical v2 names; TenantID/SubTenantID are\ntheir deprecated aliases, reconciled by the TenantAliases middleware before\nbinding so TenantID is always populated. Neither is marked binding:required\n(mirroring TenantCreateRequest): a caller may send either spelling, and the\ntenant scope is validated downstream by resolveTenant. Requiring tenant_id\nhere would force the generated SDK to demand the deprecated field.",
            "example": "acme_corp",
            "type": "string"
          },
          "name": {
            "description": "Human-readable label for this connector.",
            "example": "general",
            "type": "string"
          },
          "provider": {
            "description": "External provider being synced (e.g. `slack`, `github`, `linear`, `notion`, `gmail`).",
            "example": "slack",
            "type": "string"
          },
          "provider_account_scope": {
            "description": "Identifier for the external account (e.g. Slack workspace ID, GitHub org name). Must be distinct across connectors for the same provider.",
            "example": "T12345ACME",
            "type": "string"
          },
          "sub_tenant_id": {
            "deprecated": true,
            "description": "deprecated: use collection",
            "example": "sub_tenant_4567",
            "type": "string",
            "x-deprecated": "true"
          },
          "sync_interval_seconds": {
            "description": "How frequently the scheduler triggers incremental syncs, in seconds. Bounded per provider; send 0 or omit to use the provider default. Change it later with PATCH /connectors/{id}.",
            "example": 3600,
            "type": "integer"
          },
          "tenant_id": {
            "deprecated": true,
            "description": "deprecated: use database",
            "example": "tenant_1234",
            "type": "string",
            "x-deprecated": "true"
          }
        },
        "required": [
          "provider"
        ],
        "type": "object"
      },
      "handler.connectorCreateResponse": {
        "properties": {
          "acl_changes_cursor": {
            "description": "ACLChangesCursor is the provider permission-change feed's persisted\ncursor (PRO-1684; e.g. the Drive changes.list page token). Empty means\nuninitialized: the next cycle fetches a baseline and starts from now.\nAdvanced ONLY after every reported change was applied, so a failed\napply replays the same changes next cycle (at-least-once; the writes\nare idempotent full replacements).",
            "type": "string"
          },
          "active_resource_count": {
            "description": "ActiveResourceCount mirrors the number of non-disabled resource rows so\nlist responses can distinguish \"no resources configured yet\"\n(pending_setup) without a per-connector resources query.",
            "example": 1,
            "type": "integer"
          },
          "auth_type": {
            "description": "Authentication method for the provider connection (e.g. `api_token`, `oauth`).",
            "example": "api_token",
            "type": "string"
          },
          "collection": {
            "description": "Collection scope. Defaults to the default collection when omitted. Formerly `sub_tenant_id`; the `sub_tenant_id` alias is still accepted (deprecated).",
            "example": "team_docs",
            "type": "string"
          },
          "connector_id": {
            "description": "Connector this resource belongs to.",
            "example": "conn_abc123",
            "type": "string"
          },
          "custom_instructions": {
            "description": "CustomInstructions is optional free-text guidance applied when this\nconnector's documents are ingested: it steers how content is interpreted\nand indexed. Max 4000 characters; changes apply from the next sync cycle.",
            "type": "string"
          },
          "database": {
            "description": "Database/Collection are the canonical v2 names for the deprecated\ntenant_id/sub_tenant_id wire fields. They mirror the same values so a v2\nclient sees the canonical names on responses while a legacy client keeps\nreading tenant_id/sub_tenant_id. Not persisted (dynamodbav:\"-\"): the store\nbuilds items from tenant_id/sub_tenant_id and mirrors these on load. They\nare populated at every construction point (toConnector, connectorFromItem)\nrather than via MarshalJSON so Temporal's JSON data converter round-trips\nConnector activity inputs without spuriously populating them.",
            "example": "acme_corp",
            "type": "string"
          },
          "documents_dispatched": {
            "description": "DocumentsDispatched is the running total of objects handed to ingestion\nacross all completed cycles. It is dispatch *activity*, not an indexed\ncount: upserts count every time they change, deletes are never\nsubtracted, and an activity retry can double-count. Suitable as an\nis-data-moving signal, never as \"N documents indexed\".",
            "example": 1,
            "type": "integer"
          },
          "first_data_dispatched_at": {
            "description": "FirstDataDispatchedAt is set once, by the first completed cycle that\ndispatched more than zero objects. Its presence is what proves the\npipeline end to end; after it is set, an empty cycle is \"nothing changed\nat the source\", not \"still ingesting\".",
            "type": "string"
          },
          "first_sync_at": {
            "description": "FirstSyncAt is when the first scheduled sync runs (RFC3339).",
            "type": "string"
          },
          "last_attempted_sync_at": {
            "description": "RFC3339 timestamp of the most recent sync attempt (successful or not).",
            "example": "2026-07-02T17:00:00Z",
            "type": "string"
          },
          "last_error": {
            "description": "Error message from the most recent failed sync, empty string when no error.",
            "example": "",
            "type": "string"
          },
          "last_successful_sync_at": {
            "description": "RFC3339 timestamp of the last successful sync completion.",
            "example": "2026-07-02T17:00:00Z",
            "type": "string"
          },
          "lifecycle": {
            "description": "Lifecycle is the derived what-is-it-doing-now field and the one status\nclients should read (PRO-1565): reconnect | syncing | pending_setup |\ningesting | active. The embedded `status` field is a scheduler-internal\nconstant (\"active\" always) kept only for compatibility, and `sync_status`\nis the narrower mid-cycle indicator. Computed at the HTTP boundary from\nthe connector's stored facts, never persisted, so it cannot disagree\nwith them.",
            "type": "string"
          },
          "message": {
            "description": "Message is a human-readable expectation, safe to show verbatim.",
            "example": "Success",
            "type": "string"
          },
          "name": {
            "description": "Human-readable label for this resource.",
            "example": "general",
            "type": "string"
          },
          "needs_reauth": {
            "example": true,
            "type": "boolean"
          },
          "needs_reauth_at": {
            "type": "string"
          },
          "needs_reauth_reason": {
            "type": "string"
          },
          "next_sync_at": {
            "description": "RFC3339 timestamp when the next scheduled sync will run.",
            "example": "2026-07-02T18:00:00Z",
            "type": "string"
          },
          "paused": {
            "description": "Paused marks a connector its owner deliberately stopped (PRO-1762). It\nparks next_sync_at as SyncBlocked does, but stays a separate field:\nblocking clears itself once the cause is fixed, whereas only an explicit\nresume lifts a pause. Resources keep their committed provider_cursor, so\nresuming continues from where each stream stopped.",
            "example": true,
            "type": "boolean"
          },
          "paused_at": {
            "type": "string"
          },
          "paused_next_sync_at": {
            "description": "PausedNextSyncAt preserves the schedule the pause displaced. Resume makes\nthe connector due immediately, so this is read back only to recover from\na pause applied by mistake.",
            "type": "string"
          },
          "provider": {
            "description": "External provider being synced (e.g. `slack`, `github`, `linear`, `notion`, `gmail`).",
            "example": "slack",
            "type": "string"
          },
          "provider_account_scope": {
            "description": "Identifier for the external account (e.g. Slack workspace ID, GitHub org name). Must be distinct across connectors for the same provider.",
            "example": "T12345ACME",
            "type": "string"
          },
          "resources_pending_first_sync": {
            "description": "ResourcesPendingFirstSync counts active resources whose provider_cursor\nis still empty — resources that have never been successfully pulled.\nMOVEIT commits provider_cursor after every successful pull (even a\nzero-row one), so this self-clears one cycle after each resource first\nsyncs. Recomputed by the MOVEIT sync workflow each cycle and by the\nresource-mutating handlers, so a resource added to a long-active\nconnector re-enters the ingesting state.",
            "example": 1,
            "type": "integer"
          },
          "status": {
            "description": "Current lifecycle or processing state.",
            "example": "completed",
            "type": "string"
          },
          "sub_tenant_id": {
            "deprecated": true,
            "example": "sub_tenant_4567",
            "type": "string",
            "x-deprecated": "true"
          },
          "sync_blocked": {
            "description": "NeedsReauth is set by MOVEIT's OAuth refresh sweep when the provider has\nrejected the connector's refresh token (`invalid_grant` — expired, revoked,\nor, for a provider with single-use tokens, already spent).\n\nIt is deliberately distinct from LastError, which records a *sync* failure.\nThis is the one failure class no amount of retrying resolves: the stored\ngrant is gone and only the tenant can mint a new one. Surfacing it as its\nown field is what lets a client show \"reconnect\" instead of a generic\n\"sync failed\", and the sweep clears it automatically on the next successful\nrotation, so a client can trust the absence of the flag as much as its\npresence.\n\nOnly ever set on OAuth-bundle connectors. A connector authenticated with a\nstatic token or with client credentials (X posts: see the `client_id` /\n`client_secret` inputs on tap-twitter) has no refresh token and therefore\ncannot reach this state at all — which is the reason to prefer that shape\nwhere a provider offers it.\nSyncBlocked marks a connector stopped by a terminal failure — one no\nretry can fix. The scheduler skips it and next_sync_at is parked a\ncentury out; only a credential or config update clears it. Distinct from\nNeedsReauth, which is the OAuth sweep's own narrower signal: this covers\nany provider rejection of the stored credentials, including static keys\nthat have no refresh token to sweep.",
            "example": true,
            "type": "boolean"
          },
          "sync_blocked_at": {
            "type": "string"
          },
          "sync_blocked_reason": {
            "type": "string"
          },
          "sync_cycles_completed": {
            "description": "SyncCyclesCompleted counts successfully completed sync cycles. Bounded\nuse only: it lets DeriveLifecycle stop reporting \"ingesting\" after a few\nclean-but-empty cycles on a source that genuinely has nothing to pull.",
            "example": 1,
            "type": "integer"
          },
          "sync_engine": {
            "description": "SyncEngine is \"classic\" (default, empty treated as classic) or \"moveit\".\nSee the SyncEngine* constants; the scheduler branches on it.",
            "type": "string"
          },
          "sync_interval_seconds": {
            "description": "How frequently the scheduler triggers incremental syncs, in seconds. Bounded per provider; send 0 or omit to use the provider default. Change it later with PATCH /connectors/{id}.",
            "example": 3600,
            "type": "integer"
          },
          "sync_status": {
            "description": "Current sync operation state (e.g. `idle`, `running`).",
            "example": "idle",
            "type": "string"
          },
          "tenant_id": {
            "deprecated": true,
            "example": "tenant_1234",
            "type": "string",
            "x-deprecated": "true"
          }
        },
        "type": "object"
      },
      "handler.connectorDeleteResponse": {
        "properties": {
          "connector_id": {
            "description": "Connector this resource belongs to.",
            "example": "conn_abc123",
            "type": "string"
          },
          "deleted": {
            "description": "Whether this specific item was deleted.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.connectorLimitView": {
        "description": "ConnectorLimit is present when the org has used its plan's connector\nallowance (Free: 3) and the caps mode enforces it: creating another\nconnector is refused with 402. Connectors already past the allowance\nkeep syncing; the limit applies to creating one. Absent otherwise, and\nsent with the health rollups only.",
        "properties": {
          "count": {
            "description": "Total number of items returned.",
            "example": 12,
            "type": "integer"
          },
          "limit": {
            "example": 1,
            "type": "integer"
          },
          "message": {
            "description": "Human-readable result message.",
            "example": "Success",
            "type": "string"
          },
          "plan": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "handler.connectorListResponse": {
        "properties": {
          "connector_limit": {
            "$ref": "#/components/schemas/handler.connectorLimitView",
            "example": {
              "count": 12,
              "limit": 1,
              "message": "Success"
            }
          },
          "connectors": {
            "example": [
              {
                "active_resource_count": 1,
                "auth_type": "api_token",
                "collection": "team_docs",
                "connector_id": "conn_abc123",
                "database": "acme_corp",
                "documents_dispatched": 1,
                "last_attempted_sync_at": "2026-07-02T17:00:00Z",
                "last_error": "",
                "last_successful_sync_at": "2026-07-02T17:00:00Z",
                "name": "general",
                "needs_reauth": true,
                "next_sync_at": "2026-07-02T18:00:00Z",
                "paused": true,
                "provider": "slack",
                "provider_account_scope": "T12345ACME",
                "resources_pending_first_sync": 1,
                "status": "completed",
                "sub_tenant_id": "sub_tenant_4567",
                "sync_blocked": true,
                "sync_cycles_completed": 1,
                "sync_interval_seconds": 3600,
                "sync_status": "idle",
                "tenant_id": "tenant_1234"
              }
            ],
            "items": {
              "$ref": "#/components/schemas/handler.connectorAPIView"
            },
            "type": "array",
            "uniqueItems": false
          },
          "health": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Health maps connector_id to its rollup (healthy | degraded | failed |\nchecking | capped), present only when the caller asks for\n`?include=health`. A connector missing from the map has an unknown\nrollup — its resources could not be read — which clients must not\nrender as a failure. `capped` is not a rollup of the connector: it is\noverlaid on a healthy, degraded or checking one when the org is at a\nplan cap, and PlanCap says which.",
            "type": "object"
          },
          "plan_cap": {
            "$ref": "#/components/schemas/handler.planCapView",
            "example": {
              "message": "Success"
            }
          }
        },
        "type": "object"
      },
      "handler.connectorPauseResponse": {
        "properties": {
          "connector_id": {
            "description": "Connector this resource belongs to.",
            "example": "conn_abc123",
            "type": "string"
          },
          "paused": {
            "example": true,
            "type": "boolean"
          },
          "paused_at": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "handler.connectorResourceStatus": {
        "properties": {
          "acl_warning": {
            "description": "ACLWarning explains why permission capture could not read this\nresource. Capture fails OPEN, so while this is set the resource is\nreadable by EVERY caller regardless of the ACL they send. Deliberately\nnot folded into Status: the resource is syncing fine and its content is\ncurrent, so calling it failed would be wrong and would train people to\nignore a red badge. It is a separate signal because it needs a separate\nreaction (grant the missing permission, or set an access rule).",
            "type": "string"
          },
          "acl_warning_at": {
            "description": "ACLWarningAt is when this warning was last CHANGED (RFC3339), not when\nthe failure was last observed. An unchanged warning is deliberately not\nrewritten every cycle, so treat this as \"open since\", not \"checked at\".",
            "type": "string"
          },
          "action": {
            "description": "Action is what the user must do, when there is something they can do.",
            "type": "string"
          },
          "checked_at": {
            "type": "string"
          },
          "display_name": {
            "description": "Human-readable name for this resource.",
            "example": "general",
            "type": "string"
          },
          "http_status": {
            "description": "HTTPStatus is the provider's response code when one was reported.",
            "example": 1,
            "type": "integer"
          },
          "last_row_count": {
            "description": "LastRowCount is the rows produced by the last sync.",
            "example": 1,
            "type": "integer"
          },
          "message": {
            "description": "Message is the provider's own words when Status is failed.",
            "example": "Success",
            "type": "string"
          },
          "page_acl_warning": {
            "description": "PageACLWarning reports that individual PAGES inside this resource could\nnot have their own restrictions resolved and were opened to every caller.\nDistinct from ACLWarning above, which is about the resource itself: a\nresource can capture perfectly while pages inside it fail, and a healthy\nresource capture clears ACLWarning, so sharing one field would blank this\nevery cycle and report all-clear while pages are still open.",
            "type": "string"
          },
          "page_acl_warning_at": {
            "description": "PageACLWarningAt is when PageACLWarning last CHANGED (RFC3339).",
            "type": "string"
          },
          "resource_id": {
            "description": "Resource identifier from the Discover endpoint.",
            "example": "C0123456789",
            "type": "string"
          },
          "retryable": {
            "description": "Retryable is set only for a failed resource: false for a provider\nrejection the user must fix (403, 404, a misconfigured table), true for\nsomething that may clear on its own.",
            "example": true,
            "type": "boolean"
          },
          "status": {
            "description": "Status is one of ok | empty | failed | checking | unknown.",
            "example": "completed",
            "type": "string"
          },
          "sync_blocked": {
            "description": "SyncBlocked reports that this resource has stopped syncing. Distinct from\na failed status: a resource can fail a cycle and be retried, and the\ndifference between \"failing\" and \"given up on\" is the one a user needs to\nact on.",
            "example": true,
            "type": "boolean"
          },
          "sync_blocked_at": {
            "description": "SyncBlockedAt is when it stopped (RFC3339).",
            "type": "string"
          },
          "sync_blocked_reason": {
            "description": "SyncBlockedReason is why it stopped, preserved from the failure that\nstopped it so it survives later syncs overwriting the health block.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "handler.connectorResourcesResponse": {
        "properties": {
          "resources": {
            "example": [
              {
                "additional_metadata": {
                  "author": "ada",
                  "doc_version": 3
                },
                "backfill_chunk_interval_seconds": 86400,
                "backfill_oldest": "2026-06-01T00:00:00Z",
                "connector_id": "conn_abc123",
                "display_name": "general",
                "filters": {
                  "channel": "general"
                },
                "metadata": {
                  "department": "finance",
                  "priority": 7
                },
                "provider_cursor": "1699999999.000100",
                "provider_metadata": {
                  "workspace_id": "T12345ACME"
                },
                "resource_id": "C0123456789",
                "resource_type": "channel",
                "status": "completed",
                "sync_blocked": true
              }
            ],
            "items": {
              "$ref": "#/components/schemas/connectors.Resource"
            },
            "type": "array",
            "uniqueItems": false
          }
        },
        "type": "object"
      },
      "handler.connectorStatusError": {
        "description": "Error is the connector-level failure: a rejected credential, a blocked\nconnector, or a latest sync cycle that failed as a whole. Absent when the\ntrouble is confined to individual resources — those carry their own\nmessages below.",
        "properties": {
          "action": {
            "description": "Action is what the user must do, when there is something they can do.",
            "type": "string"
          },
          "detected_at": {
            "description": "DetectedAt is when the failure was observed (RFC3339).",
            "type": "string"
          },
          "message": {
            "description": "Human-readable result message.",
            "example": "Success",
            "type": "string"
          },
          "retryable": {
            "description": "Retryable reports whether waiting can fix this. False means only the user\ncan: a rejected credential is not a transient error, and telling someone\nto retry a dead OAuth grant wastes their time.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.connectorStatusResponse": {
        "properties": {
          "connector_id": {
            "description": "Connector this resource belongs to.",
            "example": "conn_abc123",
            "type": "string"
          },
          "error": {
            "$ref": "#/components/schemas/handler.connectorStatusError",
            "description": "Error message, empty string on success.",
            "example": {
              "message": "Success",
              "retryable": true
            }
          },
          "last_attempted_sync_at": {
            "description": "RFC3339 timestamp of the most recent sync attempt (successful or not).",
            "example": "2026-07-02T17:00:00Z",
            "type": "string"
          },
          "last_successful_sync_at": {
            "description": "RFC3339 timestamp of the last successful sync completion.",
            "example": "2026-07-02T17:00:00Z",
            "type": "string"
          },
          "lifecycle": {
            "description": "Lifecycle is the derived what-is-it-doing-now field (PRO-1565):\nreconnect | syncing | pending_setup | ingesting | active. Orthogonal to\nthe health rollup above — a connector can be ingesting and healthy, or\nactive and degraded.",
            "type": "string"
          },
          "next_sync_at": {
            "description": "RFC3339 timestamp when the next scheduled sync will run.",
            "example": "2026-07-02T18:00:00Z",
            "type": "string"
          },
          "plan_cap": {
            "$ref": "#/components/schemas/handler.planCapView",
            "example": {
              "message": "Success"
            }
          },
          "provider": {
            "description": "External provider being synced (e.g. `slack`, `github`, `linear`, `notion`, `gmail`).",
            "example": "slack",
            "type": "string"
          },
          "resources": {
            "description": "Resources is one entry per configured resource, always non-nil so it\nserialises as [] rather than null.",
            "example": [
              {
                "display_name": "general",
                "http_status": 1,
                "last_row_count": 1,
                "message": "Success",
                "resource_id": "C0123456789",
                "retryable": true,
                "status": "completed",
                "sync_blocked": true
              }
            ],
            "items": {
              "$ref": "#/components/schemas/handler.connectorResourceStatus"
            },
            "type": "array",
            "uniqueItems": false
          },
          "status": {
            "description": "Status is the rollup: healthy | degraded | failed | checking, or capped\nwhen the org is at an enforced plan cap and the rollup was healthy,\ndegraded or checking (PlanCap then says which cap). It is the worst of\nthe credential state and every resource state.",
            "example": "completed",
            "type": "string"
          },
          "sync_status": {
            "description": "SyncStatus is the in-progress indicator (\"syncing\"/\"idle\"), orthogonal to\nStatus — a connector can be mid-sync and degraded at the same time.",
            "example": "idle",
            "type": "string"
          }
        },
        "type": "object"
      },
      "handler.connectorSyncResponse": {
        "properties": {
          "run_id": {
            "type": "string"
          },
          "workflow_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "handler.connectorUpdateReq": {
        "properties": {
          "credentials": {
            "additionalProperties": {},
            "description": "Provider-specific credentials (typically `{\"api_token\": \"...\"}` or `{\"access_token\": \"...\"}`).",
            "example": {
              "api_token": "xoxb-..."
            },
            "type": "object"
          },
          "custom_instructions": {
            "description": "CustomInstructions replaces the guidance applied when this connector's\ndocuments are ingested. Omitted leaves it unchanged; an explicit empty\nstring clears it. Max 4000 characters; applies from the next sync cycle.",
            "type": "string"
          },
          "sync_interval_seconds": {
            "description": "How frequently the scheduler triggers incremental syncs, in seconds. Bounded per provider; send 0 or omit to use the provider default. Change it later with PATCH /connectors/{id}.",
            "example": 3600,
            "type": "integer"
          }
        },
        "type": "object"
      },
      "handler.connectorUpdateResponse": {
        "properties": {
          "connector_id": {
            "description": "Connector this resource belongs to.",
            "example": "conn_abc123",
            "type": "string"
          },
          "credentials_updated": {
            "description": "CredentialsUpdated reports that the stored credential bundle was\nre-written (and any needs-reauth flag cleared) by this request.",
            "example": true,
            "type": "boolean"
          },
          "custom_instructions_updated": {
            "description": "CustomInstructionsUpdated reports that the steering text was rewritten\n(or cleared) by this request; it takes effect from the next sync cycle.",
            "example": true,
            "type": "boolean"
          },
          "max_sync_interval_seconds": {
            "description": "Largest sync_interval_seconds this connector's provider allows.",
            "example": 604800,
            "type": "integer"
          },
          "min_sync_interval_seconds": {
            "description": "Smallest sync_interval_seconds this connector's provider allows. Values below it are rejected, never clamped.",
            "example": 300,
            "type": "integer"
          },
          "next_sync_at": {
            "description": "RFC3339 timestamp when the next scheduled sync will run.",
            "example": "2026-07-02T18:00:00Z",
            "type": "string"
          },
          "sync_interval_seconds": {
            "description": "How frequently the scheduler triggers incremental syncs, in seconds. Bounded per provider; send 0 or omit to use the provider default. Change it later with PATCH /connectors/{id}.",
            "example": 3600,
            "type": "integer"
          }
        },
        "type": "object"
      },
      "handler.contextMetadataUpdateRequest": {
        "properties": {
          "acl": {
            "description": "ACL, when present, REPLACES the source's access-control list without\nre-ingestion (PRO-1684): pass the COMPLETE new allow-list (adding a\nthird user means sending all three), an empty list to make the source\nprivate, or [\"__public__\"] to open it to every identified caller. A\npointer so omitted (nil, ACL untouched) is distinguishable from an\nexplicit empty list (private).\nACL uses RawMessage so the handler can tell three wire states apart:\nabsent (leave the stored ACL untouched), explicit null (revoke to\nnobody, JSON-merge-patch semantics), and a list (replace). A plain\n*[]string cannot: encoding/json leaves the pointer nil for BOTH\nabsent and null, which silently ignored an explicit null revocation.",
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false
          },
          "additional_metadata": {
            "additionalProperties": {},
            "description": "Free-form key-value pairs to merge into the source's `additional_metadata`. The only accepted spelling for document metadata on this endpoint. Capped at 1 KiB, measured on the compact JSON encoding of the whole map in UTF-8 bytes — keys, quotes, commas and braces count toward the budget. Over-cap returns 400 with the actual byte count.",
            "example": {
              "author": "ada",
              "doc_version": 3
            },
            "type": "object"
          },
          "collection": {
            "description": "Collection scope. Defaults to the default collection when omitted. Formerly `sub_tenant_id`; the `sub_tenant_id` alias is still accepted (deprecated).",
            "example": "team_docs",
            "type": "string"
          },
          "database": {
            "description": "Database/Collection are the canonical v2 names; TenantID/SubTenantID are\ntheir deprecated aliases. The TenantAliases middleware reconciles them in\nthe request body before binding, so the handler reads TenantID/SubTenantID.",
            "example": "acme_corp",
            "type": "string"
          },
          "database_metadata": {
            "additionalProperties": {},
            "description": "Schema-backed metadata fields to merge into the source's `metadata` (database metadata). Canonical name; `tenant_metadata` is a deprecated alias. Capped at 16 KiB, measured on the compact JSON encoding of the whole map in UTF-8 bytes — keys, quotes, commas and braces count toward the budget. Over-cap returns 400 with the actual byte count.",
            "example": {
              "department": "legal",
              "priority": 7
            },
            "type": "object"
          },
          "document_metadata": {
            "additionalProperties": {},
            "deprecated": true,
            "description": "Not accepted on this endpoint. Sending any non-null value returns 400 (`document_metadata is not accepted; use additional_metadata`), regardless of size. Use `additional_metadata` instead. Accepted as an alias on /context/ingest only.",
            "type": "object",
            "x-deprecated": "true"
          },
          "sub_tenant_id": {
            "deprecated": true,
            "description": "deprecated: use collection",
            "example": "sub_tenant_4567",
            "type": "string",
            "x-deprecated": "true"
          },
          "tenant_id": {
            "deprecated": true,
            "description": "deprecated: use database",
            "example": "tenant_1234",
            "type": "string",
            "x-deprecated": "true"
          },
          "tenant_metadata": {
            "additionalProperties": {},
            "deprecated": true,
            "description": "Deprecated alias for `database_metadata`, still accepted here; `database_metadata` wins when both are sent. Capped at 16 KiB, measured on the compact JSON encoding of the whole map in UTF-8 bytes — keys, quotes, commas and braces count toward the budget. Over-cap returns 400 with the actual byte count.",
            "example": {
              "department": "legal",
              "priority": 7
            },
            "type": "object",
            "x-deprecated": "true"
          }
        },
        "type": "object"
      },
      "handler.credentialsUpdateResponse": {
        "properties": {
          "connector_id": {
            "description": "Connector this resource belongs to.",
            "example": "conn_abc123",
            "type": "string"
          },
          "updated": {
            "description": "Whether the source metadata was updated.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "handler.deprecationNotice": {
        "properties": {
          "deprecated": {
            "description": "Whether this response concerns a deprecated field or route.",
            "example": true,
            "type": "boolean"
          },
          "deprecated_field": {
            "description": "The deprecated field name.",
            "example": "tenant_id",
            "type": "string"
          },
          "deprecated_since": {
            "description": "API version when the field was deprecated.",
            "example": "2.0.1",
            "type": "string"
          },
          "message": {
            "description": "Migration guidance message.",
            "example": "tenant_id is deprecated; use database instead.",
            "type": "string"
          },
          "preferred_field": {
            "description": "The canonical replacement for the deprecated field.",
            "example": "database",
            "type": "string"
          }
        },
        "type": "object"
      },
      "handler.discoverPreviewReq": {
        "properties": {
          "auth_type": {
            "description": "Authentication method for the provider connection (e.g. `api_token`, `oauth`).",
            "example": "api_token",
            "type": "string"
          },
          "credentials": {
            "additionalProperties": {},
            "description": "Provider-specific credentials (typically `{\"api_token\": \"...\"}` or `{\"access_token\": \"...\"}`).",
            "example": {
              "api_token": "xoxb-..."
            },
            "type": "object"
          },
          "provider": {
            "description": "External provider being synced (e.g. `slack`, `github`, `linear`, `notion`, `gmail`).",
            "example": "slack",
            "type": "string"
          }
        },
        "required": [
          "credentials",
          "provider"
        ],
        "type": "object"
      },
      "handler.discoverResponseBody": {
        "properties": {
          "has_more": {
            "example": true,
            "type": "boolean"
          },
          "next_cursor": {
            "description": "Opaque pagination cursor for the next page; null or absent when no more pages.",
            "example": "eyJvZmZzZXQiOjUwfQ==",
            "type": "string"
          },
          "provider": {
            "description": "External provider being synced (e.g. `slack`, `github`, `linear`, `notion`, `gmail`).",
            "example": "slack",
            "type": "string"
          },
          "resources": {
            "example": [
              {
                "id": "HydraDoc1234",
                "metadata": {
                  "department": "finance",
                  "priority": 7
                },
                "name": "general",
                "resource_type": "channel"
              }
            ],
            "items": {
              "$ref": "#/components/schemas/handler.discoveredResourceDTO"
            },
            "type": "array",
            "uniqueItems": false
          }
        },
        "type": "object"
      },
      "handler.discoveredResourceDTO": {
        "properties": {
          "id": {
            "description": "Unique identifier for this resource.",
            "example": "HydraDoc1234",
            "type": "string"
          },
          "metadata": {
            "additionalProperties": {},
            "example": {
              "department": "finance",
              "priority": 7
            },
            "type": "object"
          },
          "name": {
            "description": "Human-readable label for this resource.",
            "example": "general",
            "type": "string"
          },
          "resource_type": {
            "description": "Type of resource within the provider (e.g. `channel`, `repo`, `linear_team`).",
            "example": "channel",
            "type": "string"
          }
        },
        "type": "object"
      },
      "handler.instructionsResponse": {
        "properties": {
          "collections": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Collections maps collection name to that collection's own instructions.",
            "example": [
              "team_docs",
              "engineering"
            ],
            "type": "object"
          },
          "custom_instructions": {
            "description": "CustomInstructions applies to every document ingested into the database.",
            "type": "string"
          },
          "database": {
            "description": "Owning database. Formerly `tenant_id`; the `tenant_id` alias is still accepted (deprecated).",
            "example": "acme_corp",
            "type": "string"
          },
          "tenant_id": {
            "deprecated": true,
            "description": "TenantID mirrors Database as a deprecated alias, matching every other v2\ntenant response.",
            "example": "acme_corp",
            "type": "string",
            "x-deprecated": "true"
          }
        },
        "type": "object"
      },
      "handler.instructionsUpdateReq": {
        "properties": {
          "collections": {
            "additionalProperties": {
              "type": [
                "string",
                "null"
              ]
            },
            "description": "Collections merges per-collection instructions into the stored set: a\ncollection present with a value is set, a collection present with \"\" or\nnull is cleared, and a collection absent from the map is left untouched.\nMerge rather than replace so two people editing different collections\ncannot silently delete each other's work.",
            "example": {
              "engineering": null,
              "team_docs": "Summarise decisions and who owns them."
            },
            "type": "object"
          },
          "custom_instructions": {
            "description": "CustomInstructions sets the database-wide instructions. Send \"\" to clear.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "type": "object"
      },
      "handler.metadataSchemaUpdateResponse": {
        "properties": {
          "added_fields": {
            "description": "Names of the metadata schema fields successfully added.",
            "example": [
              "region",
              "summary_label"
            ],
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false
          },
          "database": {
            "description": "Owning database. Formerly `tenant_id`; the `tenant_id` alias is still accepted (deprecated).",
            "example": "acme_corp",
            "type": "string"
          },
          "tenant_id": {
            "deprecated": true,
            "example": "acme_corp",
            "type": "string",
            "x-deprecated": "true"
          }
        },
        "type": "object"
      },
      "handler.planCapView": {
        "description": "PlanCap is present when the org is at a plan cap the caps mode\nenforces; every sync is skipped until the month resets or the plan\nchanges.",
        "properties": {
          "message": {
            "description": "Human-readable result message.",
            "example": "Success",
            "type": "string"
          },
          "meter": {
            "type": "string"
          },
          "plan": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "handler.providerListResponse": {
        "properties": {
          "providers": {
            "example": [
              {
                "is_alpha": true,
                "is_beta": true,
                "moveit_support": true,
                "provider": "slack",
                "rank": 1,
                "rbac_support": true,
                "supported": true,
                "webhook_support": true
              }
            ],
            "items": {
              "$ref": "#/components/schemas/handler.catalogConnector"
            },
            "type": "array",
            "uniqueItems": false
          }
        },
        "type": "object"
      },
      "handler.resourceCreateReq": {
        "properties": {
          "acl": {
            "description": "ACL restricts every object synced from this resource to the listed\nprincipals (see resourceMapping.ACL). Omitted means unrestricted.",
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false
          },
          "additional_metadata": {
            "additionalProperties": {},
            "description": "Key-value pairs merged into document metadata on every synced object from this resource. Capped at 1 KiB, measured on the compact JSON encoding of the whole map in UTF-8 bytes — keys, quotes, commas and braces count toward the budget. The cap is applied when synced objects are ingested, not to this request.",
            "example": {
              "author": "ada",
              "doc_version": 3
            },
            "type": "object"
          },
          "collection_override": {
            "type": "string"
          },
          "custom_instructions": {
            "description": "CustomInstructions optionally steers how documents synced from this\nresource are ingested and indexed. When set it replaces the\nconnector-level custom_instructions for this resource; empty inherits\nthe connector's value. Max 4000 characters.",
            "type": "string"
          },
          "database_override": {
            "type": "string"
          },
          "display_name": {
            "description": "Human-readable name for this resource.",
            "example": "general",
            "type": "string"
          },
          "filters": {
            "additionalProperties": {},
            "description": "Provider-specific filters applied during sync (e.g. `{\"lookback_days\": 30}`).",
            "example": {
              "channel": "general"
            },
            "type": "object"
          },
          "metadata": {
            "additionalProperties": {},
            "description": "Key-value pairs merged into tenant metadata on every synced object from this resource. Capped at 16 KiB, measured on the compact JSON encoding of the whole map in UTF-8 bytes — keys, quotes, commas and braces count toward the budget. The cap is applied when synced objects are ingested, not to this request.",
            "example": {
              "department": "finance",
              "priority": 7
            },
            "type": "object"
          },
          "provider_metadata": {
            "additionalProperties": {},
            "description": "Additional provider-supplied metadata for this resource.",
            "example": {
              "workspace_id": "T12345ACME"
            },
            "type": "object"
          },
          "resource_id": {
            "description": "Resource identifier from the Discover endpoint.",
            "example": "C0123456789",
            "type": "string"
          },
          "resource_type": {
            "description": "Type of resource within the provider (e.g. `channel`, `repo`, `linear_team`).",
            "example": "channel",
            "type": "string"
          },
          "sub_tenant_id_override": {
            "deprecated": true,
            "description": "deprecated: use collection_override",
            "type": "string",
            "x-deprecated": "true"
          },
          "tenant_id_override": {
            "deprecated": true,
            "description": "DatabaseOverride/CollectionOverride are the canonical v2 names;\nTenantIDOverride/SubTenantIDOverride are their deprecated aliases.",
            "type": "string",
            "x-deprecated": "true"
          }
        },
        "required": [
          "resource_id"
        ],
        "type": "object"
      },
      "handler.resourceDeleteResponse": {
        "properties": {
          "connector_id": {
            "description": "Connector this resource belongs to.",
            "example": "conn_abc123",
            "type": "string"
          },
          "deleted": {
            "description": "Whether this specific item was deleted.",
            "example": true,
            "type": "boolean"
          },
          "resource_id": {
            "description": "Resource identifier from the Discover endpoint.",
            "example": "C0123456789",
            "type": "string"
          }
        },
        "type": "object"
      },
      "handler.resourceMapping": {
        "properties": {
          "acl": {
            "description": "ACL restricts every object synced from this resource to the listed\nprincipals (emails, or prefixed principals, see the query-side\nuser_email parameter). Omitted means unrestricted. An explicitly empty\nlist means private (visible only to unfiltered queries).",
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false
          },
          "additional_metadata": {
            "additionalProperties": {},
            "description": "AdditionalMetadata is merged into the additional_metadata layer of every\nobject synced from this resource. Provider-generated fields take precedence.",
            "example": {
              "author": "ada",
              "doc_version": 3
            },
            "type": "object"
          },
          "collection": {
            "description": "Collection is the canonical v2 name for the per-resource sub-tenant\noverride: routes synced objects from this resource into a specific\ncollection. Empty means the resource inherits the connector collection.\nSubTenantID is the deprecated alias for this field, reconciled by\nConfigure before toResource runs.",
            "example": "team_docs",
            "type": "string"
          },
          "custom_instructions": {
            "description": "CustomInstructions optionally steers how documents synced from this\nresource are ingested and indexed. When set it replaces the\nconnector-level custom_instructions for this resource; empty inherits\nthe connector's value. Max 4000 characters.",
            "type": "string"
          },
          "database": {
            "description": "Database is the canonical v2 name for the per-resource tenant override:\nroutes synced objects from this resource into a specific database.\nEmpty means the resource inherits the connector database. TenantID is the\ndeprecated alias for this field, reconciled by Configure before\ntoResource runs.",
            "example": "acme_corp",
            "type": "string"
          },
          "metadata": {
            "additionalProperties": {},
            "description": "Metadata is merged into the tenant metadata layer of every object synced\nfrom this resource. System fields (connector_id, provider) take precedence.",
            "example": {
              "department": "finance",
              "priority": 7
            },
            "type": "object"
          },
          "name": {
            "description": "Display name for this resource.",
            "example": "general",
            "type": "string"
          },
          "resource_id": {
            "description": "Resource identifier from the Discover endpoint.",
            "example": "C0123456789",
            "type": "string"
          },
          "resource_type": {
            "description": "Type of resource within the provider (e.g. `channel`, `repo`, `linear_team`).",
            "example": "channel",
            "type": "string"
          },
          "sub_tenant_id": {
            "deprecated": true,
            "description": "Routes synced objects from this resource into a specific sub-tenant\npartition. Overrides the connector-level sub_tenant_id. Deprecated: use\ncollection.",
            "example": "sub_tenant_4567",
            "type": "string",
            "x-deprecated": "true"
          },
          "sync_mode": {
            "description": "SyncMode is the per-resource update strategy for taps that support one\n(today: attio objects/lists). \"rescan\" (default) re-reads the full set\nevery sync — the only way edits are seen on APIs with no updated_at.\n\"new_only\" bounds each scan to the sync window and stops paging at its\nfloor — cheap, and an explicit opt-in to not seeing edits until\nwebhooks land. Stored in the resource's filters and carried to the tap\non every window.",
            "enum": [
              "rescan",
              "new_only"
            ],
            "type": "string"
          },
          "tenant_id": {
            "deprecated": true,
            "description": "Optional per-resource tenant override (for \"route specific resources to\ndifferent tenants\"). Empty means the resource inherits the connector\ntenant. Deprecated: use database.",
            "example": "tenant_1234",
            "type": "string",
            "x-deprecated": "true"
          }
        },
        "required": [
          "resource_id"
        ],
        "type": "object"
      },
      "handler.responseMeta": {
        "properties": {
          "api_version": {
            "description": "APIVersion echoes the version of the API that served the request (PRO-1209),\nsourced from reqmeta.APIVersion — the same value carried by OpenAPI\ninfo.version and /health — so a client always knows which API version\nproduced a response. Always present (no omitempty).",
            "type": "string"
          },
          "collection": {
            "description": "Collection scope. Defaults to the default collection when omitted. Formerly `sub_tenant_id`; the `sub_tenant_id` alias is still accepted (deprecated).",
            "example": "team_docs",
            "type": "string"
          },
          "database": {
            "description": "Owning database. Formerly `tenant_id`; the `tenant_id` alias is still accepted (deprecated).",
            "example": "acme_corp",
            "type": "string"
          },
          "deprecation": {
            "description": "Deprecation lists any migration nudges that apply to this request — the\ncaller used a legacy /tenants route, a legacy tenant_id/sub_tenant_id field,\nor the deprecated sub_tenant_ids selector. It is a non-breaking signal (the\nstatus code is unchanged); omitempty keeps it absent for fully-migrated\nrequests. A list so independent deprecations coexist without clobbering.",
            "items": {
              "$ref": "#/components/schemas/handler.deprecationNotice"
            },
            "type": "array",
            "uniqueItems": false
          },
          "latency_ms": {
            "description": "Server-side processing time in milliseconds.",
            "example": 12.3,
            "type": "number"
          },
          "request_id": {
            "description": "Unique identifier for this request, useful for support and tracing.",
            "example": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
            "type": "string"
          },
          "source_type": {
            "description": "Type of the parent source (e.g. `file`, `slack`, `notion`).",
            "example": "file",
            "type": "string"
          },
          "sub_tenant_id": {
            "deprecated": true,
            "example": "sub_tenant_4567",
            "type": "string",
            "x-deprecated": "true"
          },
          "tenant_id": {
            "deprecated": true,
            "example": "tenant_1234",
            "type": "string",
            "x-deprecated": "true"
          }
        },
        "type": "object"
      },
      "handler.supabaseWebhookAck": {
        "properties": {
          "id": {
            "description": "Unique identifier for this resource.",
            "example": "HydraDoc1234",
            "type": "string"
          },
          "status": {
            "description": "Current lifecycle or processing state.",
            "example": "completed",
            "type": "string"
          },
          "table": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "handler.tableConfigEntry": {
        "properties": {
          "change_history": {
            "type": "string"
          },
          "replication_key": {
            "type": "string"
          },
          "table": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "handler.vaultCredentialEntry": {
        "properties": {
          "collection": {
            "description": "Collection scope. Defaults to the default collection when omitted. Formerly `sub_tenant_id`; the `sub_tenant_id` alias is still accepted (deprecated).",
            "example": "team_docs",
            "type": "string"
          },
          "connector_id": {
            "description": "Connector this resource belongs to.",
            "example": "conn_abc123",
            "type": "string"
          },
          "credential_id": {
            "type": "string"
          },
          "database": {
            "description": "Owning database. Formerly `tenant_id`; the `tenant_id` alias is still accepted (deprecated).",
            "example": "acme_corp",
            "type": "string"
          },
          "fields": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false
          },
          "label": {
            "type": "string"
          },
          "provider": {
            "description": "External provider being synced (e.g. `slack`, `github`, `linear`, `notion`, `gmail`).",
            "example": "slack",
            "type": "string"
          }
        },
        "type": "object"
      },
      "handler.vaultCredentialListResponse": {
        "properties": {
          "count": {
            "description": "Total number of items returned.",
            "example": 12,
            "type": "integer"
          },
          "credentials": {
            "description": "Provider-specific credentials (typically `{\"api_token\": \"...\"}` or `{\"access_token\": \"...\"}`).",
            "example": {
              "api_token": "xoxb-..."
            },
            "items": {
              "$ref": "#/components/schemas/handler.vaultCredentialEntry"
            },
            "type": "array",
            "uniqueItems": false
          },
          "unavailable_count": {
            "example": 1,
            "type": "integer"
          }
        },
        "type": "object"
      },
      "handler.vaultCredentialRevealReq": {
        "properties": {
          "field": {
            "type": "string"
          }
        },
        "required": [
          "field"
        ],
        "type": "object"
      },
      "handler.vaultCredentialRevealResponse": {
        "properties": {
          "credential_id": {
            "type": "string"
          },
          "field": {
            "type": "string"
          },
          "provider": {
            "description": "External provider being synced (e.g. `slack`, `github`, `linear`, `notion`, `gmail`).",
            "example": "slack",
            "type": "string"
          },
          "value": {}
        },
        "type": "object"
      },
      "handler.vaultCredentialUpdateReq": {
        "properties": {
          "credentials": {
            "additionalProperties": {},
            "description": "Provider-specific credentials (typically `{\"api_token\": \"...\"}` or `{\"access_token\": \"...\"}`).",
            "example": {
              "api_token": "xoxb-..."
            },
            "type": "object"
          }
        },
        "required": [
          "credentials"
        ],
        "type": "object"
      },
      "handler.vaultCredentialUpdateResponse": {
        "properties": {
          "credential_id": {
            "type": "string"
          },
          "updated": {
            "description": "Whether the source metadata was updated.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "ingestion.SourceStatus": {
        "description": "Status is the item's initial lifecycle state. Both modes share this\nvocabulary — memory mode reuses the same values.",
        "enum": [
          "queued",
          "processing",
          "completed",
          "failed"
        ],
        "type": "string",
        "x-enum-varnames": [
          "SourceStatusQueued",
          "SourceStatusProcessing",
          "SourceStatusCompleted",
          "SourceStatusFailed"
        ]
      },
      "ingestion.V2BatchProcessingStatus": {
        "properties": {
          "statuses": {
            "description": "Per-source indexing status results.",
            "example": [
              {
                "error_code": "",
                "error_message": "",
                "id": "HydraDoc1234",
                "indexing_status": "completed",
                "message": "Source processed successfully.",
                "success": true
              }
            ],
            "items": {
              "$ref": "#/components/schemas/ingestion.V2ProcessingStatus"
            },
            "type": "array",
            "uniqueItems": false
          }
        },
        "type": "object"
      },
      "ingestion.V2IngestResponse": {
        "properties": {
          "failed_count": {
            "description": "Number of uploaded files that failed to queue.",
            "example": 0,
            "type": "integer"
          },
          "message": {
            "description": "Human-readable result message.",
            "example": "Success",
            "type": "string"
          },
          "results": {
            "description": "Per-item results.",
            "example": [
              {
                "error": "",
                "filename": "policy.pdf",
                "id": "HydraDoc1234",
                "infer": true,
                "relations_created": 5,
                "status": "queued",
                "title": "Project Phoenix Overview"
              }
            ],
            "items": {
              "$ref": "#/components/schemas/ingestion.V2IngestResultItem"
            },
            "type": "array",
            "uniqueItems": false
          },
          "success": {
            "deprecated": true,
            "description": "Deprecated for API clients: whether the REQUEST was accepted is the HTTP\nstatus code (202) or equivalently the envelope's top-level `success`.\nWhether each SOURCE ingested is per-item — read results[].status and\nresults[].error, then poll GET /context/status, since a 202 only means\nqueued. This flag answers neither question independently: it always\nmirrors the envelope. Still emitted unchanged for existing clients\n(PRO-1208).",
            "example": true,
            "type": "boolean",
            "x-deprecated": "true"
          },
          "success_count": {
            "description": "Number of files successfully queued for processing.",
            "example": 2,
            "type": "integer"
          }
        },
        "type": "object"
      },
      "ingestion.V2IngestResultItem": {
        "properties": {
          "error": {
            "description": "Error is the failure message for this item, null on success. Both modes.",
            "example": "",
            "type": "string"
          },
          "error_code": {
            "description": "ErrorCode is the machine-readable failure classification, null on success.\nBoth modes; always null on the memory path, which produces no per-item code.",
            "type": "string"
          },
          "filename": {
            "description": "Filename is the original filename as submitted. type=knowledge only.",
            "example": "policy.pdf",
            "type": "string"
          },
          "id": {
            "description": "ID is the source identifier assigned to this item. Both modes.",
            "example": "HydraDoc1234",
            "type": "string"
          },
          "infer": {
            "description": "Infer reports whether the memory was queued for inference. type=memory only.",
            "example": true,
            "type": "boolean"
          },
          "relations_created": {
            "description": "RelationsCreated is the number of graph relations extracted from this file.\ntype=knowledge only, and only for items that carried a `relations` payload.",
            "example": 5,
            "type": "integer"
          },
          "relations_error": {
            "description": "RelationsError is the relation-extraction failure message, if any.\ntype=knowledge only.",
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/ingestion.SourceStatus",
            "description": "Current lifecycle or processing state."
          },
          "title": {
            "description": "Title is the memory's title. type=memory only.",
            "example": "Project Phoenix Overview",
            "type": "string"
          }
        },
        "type": "object"
      },
      "ingestion.V2ProcessingStatus": {
        "properties": {
          "error_code": {
            "description": "Machine-readable code for the indexing failure, empty string on success.",
            "example": "",
            "type": "string"
          },
          "error_message": {
            "description": "Human-readable description of the indexing failure, empty string on success.",
            "example": "",
            "type": "string"
          },
          "id": {
            "description": "Unique identifier for this resource.",
            "example": "HydraDoc1234",
            "type": "string"
          },
          "indexing_status": {
            "description": "Current processing state: `queued`, `processing`, `completed`, or `failed`.",
            "example": "completed",
            "type": "string"
          },
          "message": {
            "description": "Human-readable status description.",
            "example": "Source processed successfully.",
            "type": "string"
          },
          "success": {
            "deprecated": true,
            "description": "Deprecated for API clients: this reads like a per-source outcome but is\na constant echo of the envelope's `success` — it is true even for a\nsource that failed indexing. For the state of THIS source read\nindexing_status (and error_code/error_message when it is errored); for\nwhether the request itself succeeded read the HTTP status code or the\nenvelope's top-level `success`. Still emitted unchanged for existing\nclients (PRO-1208).",
            "example": true,
            "type": "boolean",
            "x-deprecated": "true"
          }
        },
        "type": "object"
      },
      "list.ContentFilter": {
        "properties": {
          "additional_metadata": {
            "additionalProperties": {},
            "description": "Filters /context/list by document/additional metadata. Example: {\"author\": \"ada\"}.",
            "example": {
              "author": "ada"
            },
            "type": "object"
          },
          "metadata": {
            "additionalProperties": {},
            "description": "Filters /context/list by tenant/source metadata. Example: {\"department\": \"finance\"}.",
            "example": {
              "department": "finance"
            },
            "type": "object"
          },
          "source_fields": {
            "additionalProperties": {},
            "description": "SourceFields filters by well-known source fields: title, type,\ndescription, url, timestamp, and the app-source keys app_provider,\napp_kind, app_external_id, app_parent_id.\n\napp_external_id and app_parent_id are provider-scoped: a Jira issue key\nand a Linear id can collide, so pair either with app_provider in the\nsame filter to identify one object. Without it a match may span\nproviders that reuse the same external id.",
            "type": "object"
          }
        },
        "type": "object"
      },
      "list.V2ListContentRequest": {
        "properties": {
          "acl": {
            "description": "ACL: see ListContentRequest.ACL (PRO-1684 document ACLs).",
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false
          },
          "collection": {
            "description": "Collection scope. Defaults to the default collection when omitted. Formerly `sub_tenant_id`; the `sub_tenant_id` alias is still accepted (deprecated).",
            "example": "team_docs",
            "type": "string"
          },
          "database": {
            "description": "Database/Collection are the canonical v2 names; TenantID/SubTenantID are\ntheir deprecated aliases (reconciled here in UnmarshalJSON and centrally by\nthe TenantAliases middleware).",
            "example": "acme_corp",
            "type": "string"
          },
          "filters": {
            "$ref": "#/components/schemas/list.ContentFilter",
            "example": {
              "additional_metadata": {
                "author": "ada"
              },
              "metadata": {
                "department": "finance"
              }
            }
          },
          "group_threads": {
            "description": "GroupThreads (type=knowledge only) folds each ticket's/thread root's\ndiscussion (comment and message app sources carrying an app_parent_id)\nunder the parent row as `comments`, newest first, instead of listing them\nas separate top-level rows. Off by default: the flat shape is the\nexisting contract.",
            "example": true,
            "type": "boolean"
          },
          "ids": {
            "description": "When provided, only items with these IDs are returned. Pagination and filters still apply.",
            "example": [
              "HydraDoc1234",
              "HydraDoc4567"
            ],
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false
          },
          "include_fields": {
            "description": "Field projection — only the listed fields plus id, database, collection are returned. Only applies to type=knowledge.",
            "example": [
              "id",
              "title",
              "type"
            ],
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false
          },
          "page": {
            "description": "Current page number (1-indexed).",
            "example": 1,
            "type": "integer"
          },
          "page_size": {
            "description": "Number of items per page.",
            "example": 50,
            "type": "integer"
          },
          "sub_tenant_id": {
            "deprecated": true,
            "description": "deprecated: use collection",
            "example": "sub_tenant_4567",
            "type": "string",
            "x-deprecated": "true"
          },
          "tenant_id": {
            "deprecated": true,
            "description": "deprecated: use database",
            "example": "tenant_1234",
            "type": "string",
            "x-deprecated": "true"
          },
          "type": {
            "description": "Type names the corpus: knowledge (default) or memory.",
            "enum": [
              "knowledge",
              "memory",
              "all"
            ],
            "example": "knowledge",
            "type": "string"
          }
        },
        "type": "object"
      },
      "list.V2ListResponse": {
        "properties": {
          "message": {
            "description": "Human-readable result message.",
            "example": "Success",
            "type": "string"
          },
          "pagination": {
            "$ref": "#/components/schemas/dashboard.PaginationMeta",
            "example": {
              "has_next": true,
              "has_previous": false,
              "page": 1,
              "page_size": 50,
              "total": 128,
              "total_pages": 3
            }
          },
          "sources": {
            "description": "Sources carries the rows when type=knowledge (the default).",
            "example": [
              {
                "additional_metadata": {
                  "author": "ada",
                  "doc_version": 3
                },
                "app_external_id": "C0123456789",
                "app_kind": "slack",
                "app_provider": "slack",
                "collection": "team_docs",
                "comments_truncated": true,
                "database": "acme_corp",
                "description": "Internal overview of the Project Phoenix rollout.",
                "id": "HydraDoc1234",
                "metadata": {
                  "department": "finance",
                  "priority": 7
                },
                "note": "Superseded by the Q3 rollout plan.",
                "sub_tenant_id": "sub_tenant_4567",
                "tenant_id": "tenant_1234",
                "timestamp": "2026-07-02T10:00:00Z",
                "title": "Project Phoenix Overview",
                "type": "knowledge"
              }
            ],
            "items": {
              "$ref": "#/components/schemas/list.V2SourceItem"
            },
            "type": "array",
            "uniqueItems": false
          },
          "success": {
            "deprecated": true,
            "description": "Deprecated for API clients: to decide whether the request succeeded,\ncheck the HTTP status code — 2xx is success — or equivalently the\nenvelope's top-level `success`. This nested copy always carries the same\nvalue and never carries independent information. Still emitted unchanged\nfor existing clients (PRO-1208).",
            "example": true,
            "type": "boolean",
            "x-deprecated": "true"
          },
          "total": {
            "description": "Total is the total number of matching rows across all pages.",
            "example": 128,
            "type": "integer"
          },
          "user_memories": {
            "description": "UserMemories carries the rows when type=memory. Same item shape as Sources\nexcept each row is keyed by memory_id rather than id.",
            "example": [
              {
                "additional_metadata": {
                  "author": "ada",
                  "doc_version": 3
                },
                "app_external_id": "C0123456789",
                "app_kind": "slack",
                "app_provider": "slack",
                "collection": "team_docs",
                "comments_truncated": true,
                "database": "acme_corp",
                "description": "Internal overview of the Project Phoenix rollout.",
                "memory_id": "memory_1234",
                "metadata": {
                  "department": "finance",
                  "priority": 7
                },
                "note": "Superseded by the Q3 rollout plan.",
                "sub_tenant_id": "sub_tenant_4567",
                "tenant_id": "tenant_1234",
                "timestamp": "2026-07-02T10:00:00Z",
                "title": "Project Phoenix Overview",
                "type": "knowledge"
              }
            ],
            "items": {
              "$ref": "#/components/schemas/list.V2MemoryItem"
            },
            "type": "array",
            "uniqueItems": false
          }
        },
        "type": "object"
      },
      "list.V2MemoryItem": {
        "properties": {
          "additional_metadata": {
            "additionalProperties": {},
            "description": "AdditionalMetadata is the caller-supplied per-document metadata (stored as\ndocument_metadata).",
            "example": {
              "author": "ada",
              "doc_version": 3
            },
            "type": "object"
          },
          "app_external_id": {
            "description": "Provider-assigned identifier for this source (e.g. Slack channel ID).",
            "example": "C0123456789",
            "type": "string"
          },
          "app_kind": {
            "description": "App integration category, populated for connector-synced sources.",
            "example": "slack",
            "type": "string"
          },
          "app_parent_id": {
            "description": "AppParentID is the provider external id of this source's conversational\nparent (a Jira comment carries its issue key, a Slack reply its thread\nroot), and AppThreadID the discussion grouping key. Mirrored from the\ningestion pipeline; absent for sources without a parent/thread.",
            "type": "string"
          },
          "app_provider": {
            "description": "App* carry connector provenance, mirrored onto the source document by the\ningestion pipeline. Null for sources that were not connector-ingested.",
            "example": "slack",
            "type": "string"
          },
          "app_relations": {},
          "app_thread_id": {
            "type": "string"
          },
          "collection": {
            "description": "Collection is the canonical name for the sub-scope this row was listed\nfrom. Empty string when the row lives in the database's default collection.",
            "example": "team_docs",
            "type": "string"
          },
          "comments": {
            "description": "Comments is the group_threads discussion: the source's comment/message\nchildren as full sibling rows, newest first, capped per parent with\nCommentsTruncated marking an overflow. Present (possibly empty) on every\nrow of a group_threads response; absent otherwise.",
            "items": {
              "additionalProperties": {},
              "type": "object"
            },
            "type": "array",
            "uniqueItems": false
          },
          "comments_truncated": {
            "example": true,
            "type": "boolean"
          },
          "database": {
            "description": "Database is the canonical name for the scope this row was listed from.",
            "example": "acme_corp",
            "type": "string"
          },
          "description": {
            "description": "Human-readable description of the source.",
            "example": "Internal overview of the Project Phoenix rollout.",
            "type": "string"
          },
          "memory_id": {
            "description": "MemoryID is the memory identifier — the type=memory spelling of ID, and\npresent on exactly the same terms.",
            "example": "memory_1234",
            "type": "string"
          },
          "metadata": {
            "additionalProperties": {},
            "description": "Metadata is the caller-supplied source metadata (stored as tenant_metadata).",
            "example": {
              "department": "finance",
              "priority": 7
            },
            "type": "object"
          },
          "note": {
            "example": "Superseded by the Q3 rollout plan.",
            "type": "string"
          },
          "relations": {
            "description": "Relations/AppRelations are passthrough graph subtrees, returned only when\nrequested via include_fields. Their internal source_id/source_ids keys are\nrenamed to id/ids on the way out; the rest of the subtree is unconstrained."
          },
          "sub_tenant_id": {
            "deprecated": true,
            "description": "SubTenantID is the deprecated spelling of Collection, carrying an identical value.",
            "example": "sub_tenant_4567",
            "type": "string",
            "x-deprecated": "true"
          },
          "tenant_id": {
            "deprecated": true,
            "description": "TenantID is the deprecated spelling of Database, carrying an identical value.",
            "example": "tenant_1234",
            "type": "string",
            "x-deprecated": "true"
          },
          "timestamp": {
            "description": "RFC3339 timestamp associated with this item.",
            "example": "2026-07-02T10:00:00Z",
            "type": "string"
          },
          "title": {
            "description": "Title or name of the source.",
            "example": "Project Phoenix Overview",
            "type": "string"
          },
          "type": {
            "description": "Type is the source kind, e.g. \"knowledge\" or \"memory\".",
            "example": "knowledge",
            "type": "string"
          }
        },
        "required": [
          "collection",
          "database",
          "memory_id",
          "sub_tenant_id",
          "tenant_id"
        ],
        "type": "object"
      },
      "list.V2SourceItem": {
        "properties": {
          "additional_metadata": {
            "additionalProperties": {},
            "description": "AdditionalMetadata is the caller-supplied per-document metadata (stored as\ndocument_metadata).",
            "example": {
              "author": "ada",
              "doc_version": 3
            },
            "type": "object"
          },
          "app_external_id": {
            "description": "Provider-assigned identifier for this source (e.g. Slack channel ID).",
            "example": "C0123456789",
            "type": "string"
          },
          "app_kind": {
            "description": "App integration category, populated for connector-synced sources.",
            "example": "slack",
            "type": "string"
          },
          "app_parent_id": {
            "description": "AppParentID is the provider external id of this source's conversational\nparent (a Jira comment carries its issue key, a Slack reply its thread\nroot), and AppThreadID the discussion grouping key. Mirrored from the\ningestion pipeline; absent for sources without a parent/thread.",
            "type": "string"
          },
          "app_provider": {
            "description": "App* carry connector provenance, mirrored onto the source document by the\ningestion pipeline. Null for sources that were not connector-ingested.",
            "example": "slack",
            "type": "string"
          },
          "app_relations": {
            "description": "Connector-derived relations for this source. Present on connector-ingested rows."
          },
          "app_thread_id": {
            "description": "Discussion grouping key shared by a thread root and its replies/comments. Absent for unthreaded sources.",
            "type": "string"
          },
          "collection": {
            "description": "Collection is the canonical name for the sub-scope this row was listed\nfrom. Empty string when the row lives in the database's default collection.",
            "example": "team_docs",
            "type": "string"
          },
          "comments": {
            "description": "Comments is the group_threads discussion: the source's comment/message\nchildren as full sibling rows, newest first, capped per parent with\nCommentsTruncated marking an overflow. Present (possibly empty) on every\nrow of a group_threads response; absent otherwise.",
            "items": {
              "additionalProperties": {},
              "type": "object"
            },
            "type": "array",
            "uniqueItems": false
          },
          "comments_truncated": {
            "description": "True when the inline `comments` array hit the per-parent cap and more children exist. Fetch them via `filters.additional_metadata` on the parent's external ID.",
            "example": true,
            "type": "boolean"
          },
          "database": {
            "description": "Database is the canonical name for the scope this row was listed from.",
            "example": "acme_corp",
            "type": "string"
          },
          "description": {
            "description": "Human-readable description of the source.",
            "example": "Internal overview of the Project Phoenix rollout.",
            "type": "string"
          },
          "id": {
            "description": "ID is the source identifier. Always present: buildProjection pins\nsource.id as an identity field on every projection path.",
            "example": "HydraDoc1234",
            "type": "string"
          },
          "metadata": {
            "additionalProperties": {},
            "description": "Metadata is the caller-supplied source metadata (stored as tenant_metadata).",
            "example": {
              "department": "finance",
              "priority": 7
            },
            "type": "object"
          },
          "note": {
            "description": "Free-form note attached to the source.",
            "example": "Superseded by the Q3 rollout plan.",
            "type": "string"
          },
          "relations": {
            "description": "Relations/AppRelations are passthrough graph subtrees, returned only when\nrequested via include_fields. Their internal source_id/source_ids keys are\nrenamed to id/ids on the way out; the rest of the subtree is unconstrained."
          },
          "sub_tenant_id": {
            "deprecated": true,
            "description": "SubTenantID is the deprecated spelling of Collection, carrying an identical value.",
            "example": "sub_tenant_4567",
            "type": "string",
            "x-deprecated": "true"
          },
          "tenant_id": {
            "deprecated": true,
            "description": "TenantID is the deprecated spelling of Database, carrying an identical value.",
            "example": "tenant_1234",
            "type": "string",
            "x-deprecated": "true"
          },
          "timestamp": {
            "description": "RFC3339 timestamp associated with this item.",
            "example": "2026-07-02T10:00:00Z",
            "type": "string"
          },
          "title": {
            "description": "Title or name of the source.",
            "example": "Project Phoenix Overview",
            "type": "string"
          },
          "type": {
            "description": "Type is the source kind, e.g. \"knowledge\" or \"memory\".",
            "example": "knowledge",
            "type": "string"
          }
        },
        "required": [
          "collection",
          "database",
          "id",
          "sub_tenant_id",
          "tenant_id"
        ],
        "type": "object"
      },
      "memories.ConversationTurn": {
        "properties": {
          "content": {
            "description": "Extracted text content of the source document.",
            "example": "# Q4 Report\n\nRevenue grew 23% quarter over quarter.",
            "type": "string"
          },
          "name": {
            "description": "Human-readable label for this resource.",
            "example": "general",
            "type": "string"
          },
          "role": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "memories.IngestItem": {
        "properties": {
          "acl": {
            "description": "ACL is the item's access-control list (PRO-1684), the same contract as\nan app_knowledge item's `acl` on a split database: bare emails,\nuser_email:/group:/domain: principals, or the __public__/__private__\nsentinels. Omitted (nil) leaves the context unrestricted; an explicitly\nempty list stores __private__. Normalised here, all-or-nothing, so a\nmalformed principal is a 400 on the request rather than a silently\nmis-scoped context. Enforced by every read that takes `acl`.",
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false
          },
          "attributes": {
            "additionalProperties": {},
            "type": "object"
          },
          "content": {
            "description": "Extracted text content of the source document.",
            "example": "# Q4 Report\n\nRevenue grew 23% quarter over quarter.",
            "type": "string"
          },
          "context_category": {
            "description": "ContextCategory files this context under one of the three buckets\n(PRO-1618). Omitted or \"auto\" leaves it to HydraDB; naming a bucket pins\nit and inference will not overwrite it. See\ndomain/ingestion/context_category.go.",
            "enum": [
              "auto",
              "user_preference",
              "business_knowledge",
              "decision_trace"
            ],
            "type": "string"
          },
          "context_id": {
            "type": "string"
          },
          "conversation": {
            "description": "Conversation is the canonical name; `messages` is accepted as an alias.\nBoth are the shape a developer already builds for OpenAI or Anthropic.",
            "example": [
              {
                "content": "# Q4 Report\n\nRevenue grew 23% quarter over quarter.",
                "name": "general"
              }
            ],
            "items": {
              "$ref": "#/components/schemas/memories.ConversationTurn"
            },
            "type": "array",
            "uniqueItems": false
          },
          "custom_attributes": {
            "additionalProperties": {},
            "type": "object"
          },
          "custom_instructions": {
            "type": "string"
          },
          "enrich": {
            "example": true,
            "type": "boolean"
          },
          "happened_at": {
            "type": "string"
          },
          "is_markdown": {
            "description": "IsMarkdown tells the pipeline the text is markdown, so it is chunked on\nstructure rather than as flat prose. The memories[] path has always\ncarried it; without it here a markdown sync has nowhere to say so.",
            "example": true,
            "type": "boolean"
          },
          "messages": {
            "example": [
              {
                "content": "# Q4 Report\n\nRevenue grew 23% quarter over quarter.",
                "name": "general"
              }
            ],
            "items": {
              "$ref": "#/components/schemas/memories.ConversationTurn"
            },
            "type": "array",
            "uniqueItems": false
          },
          "text": {
            "description": "Text is the canonical name; `content` is accepted as an alias.",
            "type": "string"
          },
          "title": {
            "description": "Title names the context. It becomes the context's document title, and it\nis what distinguishes two items whose text is identical: the document id\nis generated from the title, so without one they collide.",
            "example": "Project Phoenix Overview",
            "type": "string"
          },
          "user_name": {
            "description": "UserName is the speaker identity for a TEXT item. A conversation names\nits speaker per turn instead, and that stays authoritative: this field\nonly fills in when the turns supplied none. Empty ends up as \"User\",\nmatching the split path, so the pipeline is never handed a blank.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "memories.UnifiedIngestRequest": {
        "properties": {
          "collection": {
            "description": "Collection scope. Defaults to the default collection when omitted. Formerly `sub_tenant_id`; the `sub_tenant_id` alias is still accepted (deprecated).",
            "example": "team_docs",
            "type": "string"
          },
          "contexts": {
            "example": [
              {
                "content": "# Q4 Report\n\nRevenue grew 23% quarter over quarter.",
                "conversation": [
                  {
                    "content": "# Q4 Report\n\nRevenue grew 23% quarter over quarter.",
                    "name": "general"
                  }
                ],
                "enrich": true,
                "is_markdown": true,
                "messages": [
                  {
                    "content": "# Q4 Report\n\nRevenue grew 23% quarter over quarter.",
                    "name": "general"
                  }
                ],
                "title": "Project Phoenix Overview"
              }
            ],
            "items": {
              "$ref": "#/components/schemas/memories.IngestItem"
            },
            "type": "array",
            "uniqueItems": false
          },
          "database": {
            "description": "Owning database. Formerly `tenant_id`; the `tenant_id` alias is still accepted (deprecated).",
            "example": "acme_corp",
            "type": "string"
          },
          "items": {
            "description": "Items is the canonical name from the design spec. `contexts` is accepted\nas an alias because the field was drafted under that name.",
            "example": [
              {
                "content": "# Q4 Report\n\nRevenue grew 23% quarter over quarter.",
                "conversation": [
                  {
                    "content": "# Q4 Report\n\nRevenue grew 23% quarter over quarter.",
                    "name": "general"
                  }
                ],
                "enrich": true,
                "is_markdown": true,
                "messages": [
                  {
                    "content": "# Q4 Report\n\nRevenue grew 23% quarter over quarter.",
                    "name": "general"
                  }
                ],
                "title": "Project Phoenix Overview"
              }
            ],
            "items": {
              "$ref": "#/components/schemas/memories.IngestItem"
            },
            "type": "array",
            "uniqueItems": false
          },
          "upsert": {
            "example": "true",
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "search.AliasExpansionNote": {
        "properties": {
          "alias": {
            "type": "string"
          },
          "canonical": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "search.AppSearchFusionDiagnostics": {
        "description": "AppSearchFusion is the diagnostic block of the query_apps fusion\n(PRO-1882): per-chunk lane attribution and counts. Present only when\nquery_apps was on, the request was not ACL-scoped, and attributed chunks\nsurvived final filtering. Identifier maps cover only returned chunks.",
        "properties": {
          "app_recipes": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "AppRecipes maps the chunk_uuid of each final chunk the app lane returned to\nthe recipe that produced it (exact_id, recall, dated, bm25, broad, ...),\nincluding chunks the normal lane also had, so a consensus can be\nattributed to a recipe.",
            "type": "object"
          },
          "chunk_origins": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "ChunkOrigins maps every returned chunk_uuid to where the fusion placed it\nfrom: \"normal\" (normal lane only), \"both\" (both lanes, normal position\nkept), \"exact_id\" (promoted from the app lane's exact-identifier\nrecipe), \"app_tail\" (appended from the app lane).",
            "type": "object"
          },
          "stats": {
            "$ref": "#/components/schemas/search.AppSearchFusionStats",
            "description": "Counts for the first or only fusion pass before postprocessing, not final response counts or totals across alias alternatives. The entire diagnostic block is omitted for ACL-scoped requests.",
            "example": {
              "app_chunks": 1,
              "app_has_exact_ids": true,
              "app_lane_empty_text": true,
              "consensus": 1,
              "exact_candidates": 1,
              "exact_promoted": 1,
              "limit": 1,
              "normal_chunks": 1,
              "normal_displaced": 1,
              "tail_added": 1,
              "tail_candidates": 1
            }
          },
          "stats_by_pass": {
            "description": "StatsByPass preserves each independent fusion's accounting when results\ncombine multiple passes, in merge order (original before alternate when\nboth have diagnostics). Counts overlap; they are not unique totals.",
            "example": [
              {
                "app_chunks": 1,
                "app_has_exact_ids": true,
                "app_lane_empty_text": true,
                "consensus": 1,
                "exact_candidates": 1,
                "exact_promoted": 1,
                "limit": 1,
                "normal_chunks": 1,
                "normal_displaced": 1,
                "tail_added": 1,
                "tail_candidates": 1
              }
            ],
            "items": {
              "$ref": "#/components/schemas/search.AppSearchFusionStats"
            },
            "type": "array",
            "uniqueItems": false
          }
        },
        "type": "object"
      },
      "search.AppSearchFusionStats": {
        "description": "Stats describes the first (or only) fusion pass before postprocessing,\nnot final counts or a sum across alias alternatives/fan-out branches.",
        "properties": {
          "app_chunks": {
            "description": "AppChunks is what the app lane returned.",
            "example": 1,
            "type": "integer"
          },
          "app_has_exact_ids": {
            "description": "AppHasExactIDs mirrors the app plan's exact-identifier marker.",
            "example": true,
            "type": "boolean"
          },
          "app_lane_empty_text": {
            "description": "AppLaneEmptyText is true when the app lane returned no chunks (sources\nor side context only).",
            "example": true,
            "type": "boolean"
          },
          "consensus": {
            "description": "Consensus counts app chunks the normal lane already had; they keep the\nnormal lane's position.",
            "example": 1,
            "type": "integer"
          },
          "exact_candidates": {
            "description": "ExactCandidates counts app chunks the exact-identifier recipe found;\nExactPromoted is how many of them were placed above the normal lane.",
            "example": 1,
            "type": "integer"
          },
          "exact_promoted": {
            "description": "Exact-identifier chunks placed above the normal lane.",
            "example": 1,
            "type": "integer"
          },
          "limit": {
            "description": "Limit is the final chunk limit the fusion applied.",
            "example": 1,
            "type": "integer"
          },
          "normal_chunks": {
            "description": "NormalChunks is what the normal lane returned.",
            "example": 1,
            "type": "integer"
          },
          "normal_displaced": {
            "description": "NormalDisplaced counts normal-lane chunks the promoted block and the\ntail pushed past the limit.",
            "example": 1,
            "type": "integer"
          },
          "tail_added": {
            "description": "App-only chunks appended within the tail budget.",
            "example": 1,
            "type": "integer"
          },
          "tail_candidates": {
            "description": "TailCandidates counts app-only chunks eligible for the tail; TailAdded\nis how many were appended within the tail budget.",
            "example": 1,
            "type": "integer"
          }
        },
        "type": "object"
      },
      "search.ChunkInspectResult": {
        "properties": {
          "chunks": {
            "example": [
              {
                "additional_metadata": {
                  "author": "ada",
                  "doc_version": 3
                },
                "chunk_content": "HydraDB supports hybrid retrieval across knowledge and memories.",
                "chunk_uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
                "extra_context_ids": [
                  "HydraEmbeddings123_2",
                  "HydraEmbeddings123_3"
                ],
                "layout": "text",
                "metadata": {
                  "department": "finance",
                  "priority": 7
                },
                "relevancy_score": 0.87,
                "source_id": "HydraDoc1234",
                "source_last_updated_time": "2026-07-02T12:30:00Z",
                "source_title": "Project Phoenix Overview",
                "source_type": "file",
                "source_upload_time": "2026-07-02T10:00:00Z",
                "sub_tenant_id": "sub_tenant_4567"
              }
            ],
            "items": {
              "$ref": "#/components/schemas/search.VectorStoreChunk"
            },
            "type": "array",
            "uniqueItems": false
          },
          "is_truncated": {
            "description": "IsTruncated reports that the source has more chunks than the limit\nreturned, so the reader knows the text they see is a prefix of the\ndocument and not the whole of it.",
            "example": false,
            "type": "boolean"
          },
          "message": {
            "description": "Human-readable result message.",
            "example": "Success",
            "type": "string"
          },
          "missing_chunk_ids": {
            "description": "MissingChunkIDs are ids the caller asked for that have no chunk row in\neither store. An expected, documented state rather than an error: on\nstaging 61% of one Slack collection's sources had graph relations but no\nchunk_data row at all (see attributedSourceID), and the vector store is\nnot guaranteed to still hold a re-ingested source's older chunk ids.\nAlways empty for a source-scoped read, which discovers ids rather than\nbeing handed them.",
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false
          },
          "success": {
            "description": "Whether the request succeeded.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "search.CodeSearchRepoResult": {
        "properties": {
          "answer": {
            "type": "string"
          },
          "duration_ms": {
            "example": 0.5,
            "type": "number"
          },
          "error": {
            "description": "Error message, empty string on success.",
            "example": "",
            "type": "string"
          },
          "repo": {
            "type": "string"
          },
          "status": {
            "description": "Current lifecycle or processing state.",
            "example": "completed",
            "type": "string"
          },
          "truncated": {
            "example": true,
            "type": "boolean"
          },
          "unsigned": {
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "search.CodeSearchResult": {
        "description": "CodeSearch is the repository code-search branch's answer, when routed.",
        "properties": {
          "decided_by": {
            "description": "DecidedBy names the signal that routed the query: \"request\" (caller\nforced it), \"planner\" (is_code_query) or \"stage2\" (embedding router).",
            "type": "string"
          },
          "duration_ms": {
            "description": "DurationMS is the wall time the branch took.",
            "example": 0.5,
            "type": "number"
          },
          "reason": {
            "description": "Reason explains a non-ok status in one sentence.",
            "type": "string"
          },
          "repos": {
            "description": "Repos lists each repository searched with its own status and answer.",
            "example": [
              {
                "duration_ms": 0.5,
                "error": "",
                "status": "completed",
                "truncated": true,
                "unsigned": true
              }
            ],
            "items": {
              "$ref": "#/components/schemas/search.CodeSearchRepoResult"
            },
            "type": "array",
            "uniqueItems": false
          },
          "status": {
            "description": "Status is \"ok\" when at least one repository answered, \"not_found\" when\nnone had an archive, \"error\"/\"timeout\" when the branch failed, or\n\"skipped\" with a Reason when it was not attempted (no repositories\nconnected, caller opted out).",
            "example": "completed",
            "type": "string"
          }
        },
        "type": "object"
      },
      "search.EntityProfileView": {
        "properties": {
          "compiled_at": {
            "type": "string"
          },
          "entity_id": {
            "description": "Unique identifier for this entity in the graph.",
            "example": "entity_1a2b",
            "type": "string"
          },
          "entity_type": {
            "type": "string"
          },
          "entries": {
            "example": [
              {
                "confidence": 0.92
              }
            ],
            "items": {
              "$ref": "#/components/schemas/search.ProfileEntry"
            },
            "type": "array",
            "uniqueItems": false
          },
          "headline": {
            "type": "string"
          },
          "name": {
            "description": "Human-readable label for this resource.",
            "example": "general",
            "type": "string"
          },
          "pending_importance": {
            "example": 1,
            "type": "integer"
          },
          "perspective": {
            "type": "string"
          },
          "subject": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "summary_cites": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false
          },
          "unknown": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false
          },
          "version": {
            "example": 1,
            "type": "integer"
          }
        },
        "type": "object"
      },
      "search.ForcefulRelationEntry": {
        "properties": {
          "chunk": {
            "$ref": "#/components/schemas/search.V2Chunk",
            "example": {
              "additional_metadata": {
                "author": "ada",
                "doc_version": 3
              },
              "chunk_content": "HydraDB supports hybrid retrieval across knowledge and memories.",
              "chunk_uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
              "collection": "team_docs",
              "extra_context_ids": [
                "HydraEmbeddings123_2",
                "HydraEmbeddings123_3"
              ],
              "id": "HydraDoc1234",
              "layout": "text",
              "metadata": {
                "department": "finance",
                "priority": 7
              },
              "relevancy_score": 0.87,
              "source_last_updated_time": "2026-07-02T12:30:00Z",
              "source_title": "Project Phoenix Overview",
              "source_type": "file",
              "source_upload_time": "2026-07-02T10:00:00Z",
              "sub_tenant_id": "sub_tenant_4567"
            }
          },
          "via": {
            "$ref": "#/components/schemas/search.RelationVia"
          }
        },
        "type": "object"
      },
      "search.ForcefulRelationsBucket": {
        "description": "ForcefulRelations is the caller-declared relation bucket, carrying the\nfrom-\u003eto edge that additional_context discards when it flattens these\ninto a chunk-uuid map. Always present, so a caller can read it\nunconditionally.",
        "properties": {
          "declared": {
            "example": [
              {
                "chunk": {
                  "additional_metadata": {
                    "author": "ada",
                    "doc_version": 3
                  },
                  "chunk_content": "HydraDB supports hybrid retrieval across knowledge and memories.",
                  "chunk_uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
                  "collection": "team_docs",
                  "extra_context_ids": [
                    "HydraEmbeddings123_2",
                    "HydraEmbeddings123_3"
                  ],
                  "id": "HydraDoc1234",
                  "layout": "text",
                  "metadata": {
                    "department": "finance",
                    "priority": 7
                  },
                  "relevancy_score": 0.87,
                  "source_last_updated_time": "2026-07-02T12:30:00Z",
                  "source_title": "Project Phoenix Overview",
                  "source_type": "file",
                  "source_upload_time": "2026-07-02T10:00:00Z",
                  "sub_tenant_id": "sub_tenant_4567"
                }
              }
            ],
            "items": {
              "$ref": "#/components/schemas/search.ForcefulRelationEntry"
            },
            "type": "array",
            "uniqueItems": false
          },
          "inferred": {
            "example": [
              {
                "chunk": {
                  "additional_metadata": {
                    "author": "ada",
                    "doc_version": 3
                  },
                  "chunk_content": "HydraDB supports hybrid retrieval across knowledge and memories.",
                  "chunk_uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
                  "collection": "team_docs",
                  "extra_context_ids": [
                    "HydraEmbeddings123_2",
                    "HydraEmbeddings123_3"
                  ],
                  "id": "HydraDoc1234",
                  "layout": "text",
                  "metadata": {
                    "department": "finance",
                    "priority": 7
                  },
                  "relevancy_score": 0.87,
                  "source_last_updated_time": "2026-07-02T12:30:00Z",
                  "source_title": "Project Phoenix Overview",
                  "source_type": "file",
                  "source_upload_time": "2026-07-02T10:00:00Z",
                  "sub_tenant_id": "sub_tenant_4567"
                }
              }
            ],
            "items": {
              "$ref": "#/components/schemas/search.ForcefulRelationEntry"
            },
            "type": "array",
            "uniqueItems": false
          }
        },
        "type": "object"
      },
      "search.GraphContext": {
        "deprecated": true,
        "description": "GraphContext is omitted entirely when graph_context is disabled on the\nrequest (pointer + omitempty), so the response carries no graph slice\ninstead of an empty-but-present object.",
        "properties": {
          "chunk_id_to_group_ids": {
            "additionalProperties": {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "description": "Mapping from chunk ID to the relation group IDs it participates in.",
            "example": {
              "HydraEmbeddings123_0": [
                "grp_1234"
              ]
            },
            "type": "object"
          },
          "chunk_relations": {
            "description": "Scored relation paths relevant to the query, grouped by chunk.",
            "example": [
              {
                "combined_context": "Acme Corp deploys HydraDB in production for context retrieval.",
                "group_id": "grp_1234",
                "relevancy_score": 0.87,
                "source_chunk_ids": [
                  "HydraEmbeddings123_0",
                  "HydraEmbeddings123_1"
                ],
                "triplets": [
                  {
                    "relation": {
                      "confidence": 0.92,
                      "predicate": "works_at"
                    },
                    "source": {
                      "entity_id": "entity_1a2b",
                      "name": "Ada",
                      "type": "person"
                    },
                    "target": {
                      "entity_id": "entity_3c4d",
                      "name": "Acme Corp",
                      "type": "organization"
                    }
                  }
                ]
              }
            ],
            "items": {
              "$ref": "#/components/schemas/search.ScoredPathResponse"
            },
            "type": "array",
            "uniqueItems": false
          },
          "query_paths": {
            "description": "Scored relation paths ranked by relevance to the query.",
            "example": [
              {
                "combined_context": "Acme Corp deploys HydraDB in production for context retrieval.",
                "group_id": "grp_1234",
                "relevancy_score": 0.87,
                "source_chunk_ids": [
                  "HydraEmbeddings123_0",
                  "HydraEmbeddings123_1"
                ],
                "triplets": [
                  {
                    "relation": {
                      "confidence": 0.92,
                      "predicate": "works_at"
                    },
                    "source": {
                      "entity_id": "entity_1a2b",
                      "name": "Ada",
                      "type": "person"
                    },
                    "target": {
                      "entity_id": "entity_3c4d",
                      "name": "Acme Corp",
                      "type": "organization"
                    }
                  }
                ]
              }
            ],
            "items": {
              "$ref": "#/components/schemas/search.ScoredPathResponse"
            },
            "type": "array",
            "uniqueItems": false
          }
        },
        "type": "object",
        "x-deprecated": "true"
      },
      "search.GraphPath": {
        "properties": {
          "chunk_ids": {
            "example": [
              "HydraEmbeddings123_0",
              "HydraEmbeddings123_1"
            ],
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false
          },
          "combined_context": {
            "description": "Merged text from all chunk passages in this relation path.",
            "example": "Acme Corp deploys HydraDB in production for context retrieval.",
            "type": "string"
          },
          "relevancy_score": {
            "description": "Relevance score for this item against the query.",
            "example": 0.87,
            "type": "number"
          },
          "triplets": {
            "description": "Knowledge-graph triplets that make up this relation path.",
            "example": [
              {
                "relation": {
                  "confidence": 0.92,
                  "predicate": "works_at"
                },
                "source": {
                  "entity_id": "entity_1a2b",
                  "name": "Ada",
                  "type": "person"
                },
                "target": {
                  "entity_id": "entity_3c4d",
                  "name": "Acme Corp",
                  "type": "organization"
                }
              }
            ],
            "items": {
              "$ref": "#/components/schemas/search.PathTriplet"
            },
            "type": "array",
            "uniqueItems": false
          }
        },
        "type": "object"
      },
      "search.GraphPlane": {
        "description": "Graph is the consolidated graph plane: query_paths and\nchunk_relations consolidated into one ordered paths[] list, with each\npath carrying the chunk ids it supports so the caller no longer joins\nagainst chunk_id_to_group_ids. Populated whenever graph_context is on;\ngraph_context stays populated beside it.",
        "properties": {
          "paths": {
            "example": [
              {
                "chunk_ids": [
                  "HydraEmbeddings123_0",
                  "HydraEmbeddings123_1"
                ],
                "combined_context": "Acme Corp deploys HydraDB in production for context retrieval.",
                "relevancy_score": 0.87,
                "triplets": [
                  {
                    "relation": {
                      "confidence": 0.92,
                      "predicate": "works_at"
                    },
                    "source": {
                      "entity_id": "entity_1a2b",
                      "name": "Ada",
                      "type": "person"
                    },
                    "target": {
                      "entity_id": "entity_3c4d",
                      "name": "Acme Corp",
                      "type": "organization"
                    }
                  }
                ]
              }
            ],
            "items": {
              "$ref": "#/components/schemas/search.GraphPath"
            },
            "type": "array",
            "uniqueItems": false
          }
        },
        "type": "object"
      },
      "search.MetadataFilters": {
        "additionalProperties": {},
        "description": "DEPRECATED: use `attributes`, which is an operator language pushed into the vector search rather than bare equality applied after it. `metadata_filters` keeps working, and is still the only way to filter on per-context custom_attributes, which `attributes` does not cover yet. Filters results by context metadata. Top-level keys target tenant metadata (for example department, priority, active, or tags). Nested additional_metadata keys target document metadata. Separate keys are ANDed. Each top-level key accepts an operator object naming the comparison: {\"contains\": value} matches sources whose field holds that value (multi-value fields are stored comma-joined, so this matches one member); {\"contains_any\": [values]} matches sources holding ANY one of the listed values; {\"equals\": value} matches sources whose field is exactly that value. The bare forms remain supported and unchanged but are deprecated in favour of the operators, because the comparison they perform is inferred from the JSON shape rather than stated: a bare scalar behaves as equals, a bare array as contains_any, and a bare single-element array as contains. Operators apply to top-level keys only; inside additional_metadata use the bare scalar or array forms. An operator used inside additional_metadata is NOT rejected - it is read as an exact-match filter against a stored object, so on a normal field it matches nothing and the request returns 200 with an empty result rather than an error. A known operator given the wrong operand type, or several operators in one object, is rejected with 400 VALIDATION_ERROR rather than silently matching nothing. A MISSPELLED operator is not: {\"contian\": \"x\"} is indistinguishable from a filter for a stored object with that key, so it is left alone and matches nothing. An object whose keys are not operator names is likewise treated as an exact-match filter against a stored object, unchanged. RESERVED NAMES: contains, contains_any and equals are reserved as the keys of a top-level filter object, so an object built only from them is read as an operator and is no longer available for exact object matching -- {\"f\": {\"contains\": \"x\"}} is read as the operator, and an object whose keys are ALL operator names is rejected with 400. A caller matching such an object in a JSON-typed field must rename the nested key or the field. Mixing an operator name with any other key ({\"contains\": \"a\", \"other\": 1}) is unaffected and still exact-matches. There is no ALL/AND operator within a single key. contains, contains_any and arrays are supported on VARCHAR fields only: any of them passed for a declared field of another type is rejected with 400 VALIDATION_ERROR. equals works on every declared type, so {\"priority\": {\"equals\": 7}} is valid on an INT64 field. Size limits: each list may hold at most 500 values, and the whole metadata_filters object is capped at 64 KiB measured on its compact JSON encoding in UTF-8 bytes AFTER operator objects are reduced to their values, so {\"contains\": \"x\"} is measured as [\"x\"] and the operator keyword itself costs nothing. The cap bounds the cost of the resulting vector-store expression, which the operator spelling does not change. Field names and punctuation count. Exceeding either returns 400 naming the offending key or the actual byte count.",
        "example": {
          "active": true,
          "additional_metadata": {
            "author": "ada"
          },
          "department": "finance",
          "priority": 7,
          "tags": [
            "alpha",
            "beta"
          ]
        },
        "type": "object"
      },
      "search.Operator": {
        "enum": [
          "or",
          "and",
          "phrase"
        ],
        "type": "string",
        "x-enum-varnames": [
          "OperatorOr",
          "OperatorAnd",
          "OperatorPhrase"
        ]
      },
      "search.PathTriplet": {
        "properties": {
          "relation": {
            "additionalProperties": {},
            "description": "Relation properties including predicate and confidence score.",
            "example": {
              "confidence": 0.92,
              "predicate": "works_at"
            },
            "type": "object"
          },
          "source": {
            "additionalProperties": {},
            "description": "Source entity of the relationship.",
            "example": {
              "entity_id": "entity_1a2b",
              "name": "Ada",
              "type": "person"
            },
            "type": "object"
          },
          "target": {
            "additionalProperties": {},
            "description": "Target entity of the relationship.",
            "example": {
              "entity_id": "entity_3c4d",
              "name": "Acme Corp",
              "type": "organization"
            },
            "type": "object"
          }
        },
        "type": "object"
      },
      "search.ProfileContext": {
        "description": "ProfileContext/ProfileFilter surface the entity-profile block when the\nrequest named a profile_subject (PRO-1797); omitted otherwise.",
        "properties": {
          "entity_id": {
            "description": "Unique identifier for this entity in the graph.",
            "example": "entity_1a2b",
            "type": "string"
          },
          "entries": {
            "example": [
              {
                "confidence": 0.92
              }
            ],
            "items": {
              "$ref": "#/components/schemas/search.ProfileEntry"
            },
            "type": "array",
            "uniqueItems": false
          },
          "headline": {
            "type": "string"
          },
          "name": {
            "description": "Human-readable label for this resource.",
            "example": "general",
            "type": "string"
          },
          "perspective": {
            "type": "string"
          },
          "subject": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "version": {
            "example": 1,
            "type": "integer"
          }
        },
        "type": "object"
      },
      "search.ProfileEntry": {
        "properties": {
          "confidence": {
            "description": "Confidence score, from 0 to 1.",
            "example": 0.92,
            "type": "number"
          },
          "facet": {
            "type": "string"
          },
          "since": {
            "type": "string"
          },
          "slot": {
            "type": "string"
          },
          "state": {
            "description": "stated | observed | inferred | record",
            "type": "string"
          },
          "statement_keys": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false
          },
          "text": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "search.ProfileFilterInfo": {
        "properties": {
          "applied": {
            "example": true,
            "type": "boolean"
          },
          "degraded": {
            "example": true,
            "type": "boolean"
          },
          "entity_id": {
            "description": "Unique identifier for this entity in the graph.",
            "example": "entity_1a2b",
            "type": "string"
          },
          "found": {
            "example": true,
            "type": "boolean"
          },
          "selected_entries": {
            "example": 1,
            "type": "integer"
          },
          "subject": {
            "type": "string"
          },
          "version": {
            "example": 1,
            "type": "integer"
          }
        },
        "type": "object"
      },
      "search.QueryBy": {
        "enum": [
          "hybrid",
          "text"
        ],
        "type": "string",
        "x-enum-varnames": [
          "QueryByHybrid",
          "QueryByText"
        ]
      },
      "search.QueryRequest": {
        "properties": {
          "acl": {
            "description": "ACL scopes retrieval to documents the given principals may access\n(PRO-1684 document ACLs): a document matches when its stored ACL is\nempty (unrestricted, pre-RBAC content and connectors without permission\nsupport), contains __public__, or intersects these principals. Entries\nare bare emails or prefixed principals (user_email:/group:/domain:).\nOmitted, empty, or [\"*\"] disables ACL filtering entirely, today's\nbehavior. Like IDs, the resulting clause survives the metadata\nzero-result retry. An entry that is not a known principal fails CLOSED:\nit matches only public and unrestricted documents, never restricted.",
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false
          },
          "additional_context": {
            "description": "Optional context string prepended to the query to improve retrieval relevance.",
            "example": "The user is a senior engineer onboarding to the platform.",
            "type": "string"
          },
          "alpha": {
            "description": "Weighting balance between dense and sparse retrieval in hybrid mode. `\"auto\"` lets HydraDB choose; a number from 0 (full BM25) to 1 (full dense) sets it explicitly."
          },
          "attributes": {
            "additionalProperties": {},
            "description": "Attributes is the go-forward metadata filter: a MongoDB-like operator query\n($eq/$ne/$gt/$gte/$lt/$lte/$in/$nin/$and/$or/$not/$exists) over the\ndatabase attributes, translated to a safe Milvus scalar pre-filter by\nBuildAttributesFilterExpr (PRO-1618). It composes (AND) with the\ndeprecated metadata_filters while both exist. Field names are allowlisted\nand values escaped, so it is injection-safe.\n\nIt is applied everywhere metadata_filters is, and nowhere else: the\nchunks a query returns, the additional context and forceful-relation\nchunks (the fail-closed post-filter net in the service), and the graph\npaths, which the graph lane prunes by resolving every source a path\ncites and dropping the paths that touch one failing the predicate\n(disallowedGraphSources). Product decision 2026-09-04: `attributes`\nbehaves like `metadata_filters` on every part of the response.",
            "type": "object"
          },
          "code_search": {
            "description": "CodeSearch forces the repository code-search branch on (true) or off\n(false) for this query, overriding the classifier. Nil = let the\nclassifier decide. Only meaningful where the branch is enabled.",
            "example": true,
            "type": "boolean"
          },
          "collection": {
            "description": "Collection scope. Defaults to the default collection when omitted. Formerly `sub_tenant_id`; the `sub_tenant_id` alias is still accepted (deprecated).",
            "example": "team_docs",
            "type": "string"
          },
          "collections": {
            "description": "Preferred /query scope selector. Send either a list of collection IDs for equal normalized weighting, or an object mapping collection ID to a positive relative ranking weight with at most one decimal place. Do not send together with the deprecated sub_tenant_ids or sub_tenant_id.",
            "example": [
              "team_docs",
              "engineering"
            ],
            "oneOf": [
              {
                "example": [
                  "finance",
                  "legal"
                ],
                "items": {
                  "type": "string"
                },
                "maxItems": 100,
                "minItems": 1,
                "type": "array"
              },
              {
                "additionalProperties": {
                  "exclusiveMinimum": 0,
                  "multipleOf": 0.1,
                  "type": "number"
                },
                "example": {
                  "finance": 1.5,
                  "legal": 0.8
                },
                "maxProperties": 100,
                "minProperties": 1,
                "type": "object"
              }
            ],
            "x-preferred": true
          },
          "database": {
            "description": "Database is the canonical v2 name for the tenant scope. TenantID is its\ndeprecated alias and remains fully accepted. The TenantAliases middleware\nreconciles the two before binding, so TenantID is always populated and the\nhandler reads it; Database/Collection are carried only for docs/OpenAPI.",
            "example": "acme_corp",
            "type": "string"
          },
          "graph_context": {
            "description": "Whether to include graph context in the response. Defaults to true for /query when omitted.",
            "example": true,
            "type": "boolean"
          },
          "graph_vector_prune": {
            "description": "GraphVectorPrune switches the graph-connected-chunks lane from \"fetch\ngraph-selected chunks and let the fusion reranker sort them out\" to \"fetch\na wider graph-selected candidate pool, then rank that pool by Milvus vector\nsimilarity, fully replacing the final chunk list.\" Works in either fast or\nthinking mode. Default false preserves existing behavior. Also gated\nserver-side by a repo-level config flag (SearchService's\ngraphVectorPruneEnabled) — if that flag is off, this is forced to false\nregardless of what the request sets, so a deployment can disable the\nmechanism without any client-side change.",
            "example": true,
            "type": "boolean"
          },
          "graph_vector_prune_spacy_entities": {
            "description": "GraphVectorPruneSpacyEntities: when GraphVectorPrune is also set, swaps the\ngraph lane's entity-extraction source from the default LLM-based extractor\nto a local spaCy subprocess (faster, no network round trip, but a\nnarrower/mismatched entity vocabulary versus the graph's own LLM-extracted\nnode names). No-op if GraphVectorPrune is false (including when forced\nfalse by the server-level flag) or no spaCy extractor was configured at\nstartup.",
            "example": true,
            "type": "boolean"
          },
          "ids": {
            "description": "IDs optionally scopes retrieval to specific source ids. The v2 wire field is\n`ids` (matching /context/list); empty means search the whole corpus. Applied\nas a Milvus `source_id in [...]` pre-filter that is preserved across the\nmetadata zero-result retry, so a source-scoped search that matches nothing\nreturns nothing rather than silently widening to the whole corpus.",
            "example": [
              "HydraDoc1234",
              "HydraDoc4567"
            ],
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false
          },
          "max_results": {
            "description": "Maximum number of chunks to return.",
            "example": 10,
            "type": "integer"
          },
          "metadata_filters": {
            "$ref": "#/components/schemas/search.MetadataFilters",
            "deprecated": true,
            "x-deprecated": true
          },
          "mode": {
            "$ref": "#/components/schemas/search.RecallMode",
            "example": "thinking"
          },
          "num_related_chunks": {
            "description": "Number of adjacent chunks to pull alongside each matched chunk for additional context.",
            "example": 3,
            "type": "integer"
          },
          "operator": {
            "$ref": "#/components/schemas/search.Operator",
            "example": "and"
          },
          "profile_entity_type": {
            "description": "ProfileEntityType/ProfileNamespace refine the subject's graph identity;\ndefaults (\"PERSON\"/\"users\") cover the common case of a person subject.",
            "type": "string"
          },
          "profile_namespace": {
            "type": "string"
          },
          "profile_subject": {
            "description": "ProfileSubject names the entity whose compiled profile should ride the\nresponse as profile_context/profile_filter (PRO-1797). Payload-only:\nchunk ranking is never altered. Omitted = no profile block. Dark until\nthe repo-level ENTITY_PROFILE_CONTEXT_ENABLED flag is on.",
            "type": "string"
          },
          "query": {
            "description": "Natural-language search query.",
            "example": "Which mode does the user prefer?",
            "type": "string"
          },
          "query_apps": {
            "description": "Whether to include app-aware knowledge retrieval. Applies to knowledge hybrid queries. Defaults to true when omitted; pass false to search files only.",
            "example": true,
            "type": "boolean"
          },
          "query_by": {
            "$ref": "#/components/schemas/search.QueryBy",
            "description": "Retrieval method to use for the query.",
            "example": "hybrid"
          },
          "query_forceful_relations": {
            "description": "Whether to force relation expansion for graph-aware query retrieval. Defaults to true when omitted.",
            "example": true,
            "type": "boolean"
          },
          "recency_bias": {
            "description": "Recency boost applied to ranking (0.0-1.0). Omit it to get the always-on default baseline of 0.40 (a bounded \u003c=40% swing on normalized relevance — it reorders within a relevance gap of up to 0.40 but never buries a more strongly relevant result); send 0 to disable recency entirely; higher values favour more recent sources more strongly.",
            "example": 0.2,
            "type": "number"
          },
          "sub_tenant_id": {
            "deprecated": true,
            "description": "Deprecated for /query (since 2.0.1). Use collection for a single scope or collections for multiple. Backwards-compatible and will be removed in a future version. Do not send together with a multi-scope selector.",
            "example": "sub_tenant_4567",
            "type": "string",
            "x-deprecated-since": "2.0.1"
          },
          "sub_tenant_ids": {
            "deprecated": true,
            "description": "Deprecated for /query (since 2.0.1). Use collections instead; it accepts the same list or weighted-object shape. Backwards-compatible and will be removed in a future version. Do not send together with collections.",
            "example": [
              "sub_tenant_4567",
              "sub_tenant_8901"
            ],
            "oneOf": [
              {
                "example": [
                  "finance",
                  "legal"
                ],
                "items": {
                  "type": "string"
                },
                "maxItems": 100,
                "minItems": 1,
                "type": "array"
              },
              {
                "additionalProperties": {
                  "exclusiveMinimum": 0,
                  "multipleOf": 0.1,
                  "type": "number"
                },
                "example": {
                  "finance": 1.5,
                  "legal": 0.8
                },
                "maxProperties": 100,
                "minProperties": 1,
                "type": "object"
              }
            ],
            "x-deprecated": "true",
            "x-deprecated-since": "2.0.1"
          },
          "temporal_intent": {
            "$ref": "#/components/schemas/search.TemporalIntentOverride",
            "example": {
              "duration_to_now": true,
              "mode": "thinking"
            }
          },
          "temporal_now": {
            "description": "TemporalNow optionally anchors \"now\" for temporal reasoning (ISO-8601).\nCallers replaying past conversations (or backfilling) must supply it or\nto-now durations and recency windows resolve against the server's wall\nclock (LongMemEval measured 0 exact to-now durations from this alone).",
            "type": "string"
          },
          "temporal_reasoning": {
            "description": "TemporalReasoning activates the temporal read path: the query is classified\ninto a temporal mode (current/as-of/range/upcoming...), matching edge-level\ntemporal facts are resolved from the edge_temporal store and ride back on\nthe response (temporal_facts / temporal_duration / temporal_filter).\nCONTRACT: chunk ranking is NEVER altered — ON returns the same chunks as\nOFF; the layer is additive payload + computed answers only (rank shaping\nmeasured net-negative on BEAM/LongMemEval/TEMPO; see temporal_filters.go).\nOptional; ON by default — pass temporal_reasoning:false to disable.\nResolved by GetTemporalReasoningOrDefault (ownership rule).",
            "example": true,
            "type": "boolean"
          },
          "tenant_id": {
            "deprecated": true,
            "description": "deprecated: use database",
            "example": "tenant_1234",
            "type": "string",
            "x-deprecated": "true"
          },
          "titles": {
            "description": "Optional exact document-title filter. Values are matched case-insensitively and ORed, resolved to source IDs, then the normal query pipeline runs within that source scope. When ids is also supplied, the two filters are intersected.",
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false
          },
          "type": {
            "$ref": "#/components/schemas/search.SourceType",
            "description": "Corpus to query: knowledge (the default), memory, or all (both, merged)."
          }
        },
        "type": "object"
      },
      "search.RecallMode": {
        "enum": [
          "fast",
          "thinking",
          "auto"
        ],
        "type": "string",
        "x-enum-varnames": [
          "RecallModeFast",
          "RecallModeThinking",
          "RecallModeAuto"
        ]
      },
      "search.RelationVia": {
        "properties": {
          "from": {
            "type": "string"
          },
          "to": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "search.ScoredPathResponse": {
        "properties": {
          "combined_context": {
            "description": "Merged text from all chunk passages in this relation path.",
            "example": "Acme Corp deploys HydraDB in production for context retrieval.",
            "type": "string"
          },
          "group_id": {
            "description": "Unique identifier for this relation group.",
            "example": "grp_1234",
            "type": "string"
          },
          "relevancy_score": {
            "description": "Relevance score for this item against the query.",
            "example": 0.87,
            "type": "number"
          },
          "source_chunk_ids": {
            "description": "IDs of the chunks that contribute to this relation path.",
            "example": [
              "HydraEmbeddings123_0",
              "HydraEmbeddings123_1"
            ],
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false
          },
          "triplets": {
            "description": "Knowledge-graph triplets that make up this relation path.",
            "example": [
              {
                "relation": {
                  "confidence": 0.92,
                  "predicate": "works_at"
                },
                "source": {
                  "entity_id": "entity_1a2b",
                  "name": "Ada",
                  "type": "person"
                },
                "target": {
                  "entity_id": "entity_3c4d",
                  "name": "Acme Corp",
                  "type": "organization"
                }
              }
            ],
            "items": {
              "$ref": "#/components/schemas/search.PathTriplet"
            },
            "type": "array",
            "uniqueItems": false
          }
        },
        "type": "object"
      },
      "search.SourceFact": {
        "properties": {
          "actor": {
            "type": "string"
          },
          "actor_role": {
            "type": "string"
          },
          "app_kind": {
            "description": "App integration category, populated for connector-synced sources.",
            "example": "slack",
            "type": "string"
          },
          "chunk_id": {
            "description": "Chunk that provides evidence for this relation.",
            "example": "HydraEmbeddings123_0",
            "type": "string"
          },
          "connector": {
            "type": "string"
          },
          "container": {
            "type": "string"
          },
          "provider": {
            "description": "External provider being synced (e.g. `slack`, `github`, `linear`, `notion`, `gmail`).",
            "example": "slack",
            "type": "string"
          },
          "relation": {
            "type": "string"
          },
          "relationship_id": {
            "description": "Unique identifier for this relationship instance.",
            "example": "rel_1234",
            "type": "string"
          },
          "source_id": {
            "example": "HydraDoc1234",
            "type": "string"
          },
          "synced_at": {
            "example": 1,
            "type": "integer"
          },
          "thread_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "search.SourceFilterInfo": {
        "description": "SourceFilter reports what the source layer did for this request.",
        "properties": {
          "actor_scope": {
            "type": "string"
          },
          "applied": {
            "example": true,
            "type": "boolean"
          },
          "container_scope": {
            "type": "string"
          },
          "degraded": {
            "example": true,
            "type": "boolean"
          },
          "matched_facts": {
            "example": 1,
            "type": "integer"
          },
          "mode": {
            "example": "thinking",
            "type": "string"
          },
          "provider": {
            "description": "External provider being synced (e.g. `slack`, `github`, `linear`, `notion`, `gmail`).",
            "example": "slack",
            "type": "string"
          },
          "thread_scope": {
            "example": true,
            "type": "boolean"
          },
          "truncated": {
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "search.SourceInfo": {
        "properties": {
          "additional_metadata": {
            "additionalProperties": {},
            "description": "Per-document free-form metadata.",
            "example": {
              "author": "ada",
              "doc_version": 3
            },
            "type": "object"
          },
          "app_external_id": {
            "description": "Provider-assigned identifier for this source (e.g. Slack channel ID).",
            "example": "C0123456789",
            "type": "string"
          },
          "app_kind": {
            "description": "App-source fields (populated when the source comes from an app integration).\nDefault null on the wire when absent.",
            "example": "slack",
            "type": "string"
          },
          "app_provider": {
            "description": "Provider name for app-sourced items (e.g. `slack`, `github`).",
            "example": "slack",
            "type": "string"
          },
          "collection": {
            "description": "Collection this source belongs to. Canonical name; mirrors the deprecated `sub_tenant_id` alias.",
            "example": "team_docs",
            "type": "string"
          },
          "description": {
            "description": "Human-readable description of the source.",
            "example": "Internal overview of the Project Phoenix rollout.",
            "type": "string"
          },
          "id": {
            "description": "Unique identifier for this resource.",
            "example": "HydraDoc1234",
            "type": "string"
          },
          "metadata": {
            "additionalProperties": {},
            "description": "Pydantic aliases (see VectorStoreChunk). Source metadata defaults to {} on\nthe wire (Python default_factory=dict), unlike chunk metadata which is null.",
            "example": {
              "department": "finance",
              "priority": 7
            },
            "type": "object"
          },
          "sub_tenant_id": {
            "deprecated": true,
            "description": "deprecated: use collection",
            "example": "sub_tenant_4567",
            "type": "string",
            "x-deprecated": "true"
          },
          "timestamp": {
            "description": "RFC3339 timestamp associated with this item.",
            "example": "2026-07-02T10:00:00Z",
            "type": "string"
          },
          "title": {
            "description": "Title or name of the source.",
            "example": "Project Phoenix Overview",
            "type": "string"
          },
          "type": {
            "description": "Source content category (e.g. `knowledge`, `memory`).",
            "example": "knowledge",
            "type": "string"
          },
          "url": {
            "description": "URL to the original source, if available.",
            "example": "https://docs.hydradb.com/phoenix",
            "type": "string"
          }
        },
        "type": "object"
      },
      "search.SourceType": {
        "description": "Source is the wire field `type` (Python QueryRequest.source has alias=\"type\").\nSourceLegacy accepts the pre-rename `source` key (Python populate_by_name=True\nkeeps the field name valid on input); resolveSourceAlias folds it into Source.",
        "enum": [
          "knowledge",
          "memory",
          "all"
        ],
        "type": "string",
        "x-enum-varnames": [
          "SourceKnowledge",
          "SourceMemory",
          "SourceAll"
        ]
      },
      "search.TemporalDuration": {
        "description": "TemporalDuration is the computed event-duration answer, when resolved.",
        "properties": {
          "approximate": {
            "description": "Approximate is set when either endpoint's granularity is coarser than a\nday (month/year brackets) — the day count is then a floor-to-floor\nestimate, not an exact span; consumers should not present it as exact.",
            "example": true,
            "type": "boolean"
          },
          "days": {
            "example": 1,
            "type": "integer"
          },
          "from": {
            "$ref": "#/components/schemas/search.TemporalFact",
            "example": {
              "chunk_id": "HydraEmbeddings123_0",
              "event_end": 1,
              "event_start": 1,
              "relationship_id": "rel_1234",
              "source_id": "HydraDoc1234",
              "status": "completed"
            }
          },
          "from_date": {
            "type": "string"
          },
          "pairing_confidence": {
            "description": "PairingConfidence is the normalized pair-scorer margin (0..1); low values\nmean the endpoints were weakly anchored to the question. Durations whose\nendpoints share no entity token with the question are suppressed\nentirely (P4: a wrong confident day count misleads answerers).",
            "example": 0.5,
            "type": "number"
          },
          "to": {
            "$ref": "#/components/schemas/search.TemporalFact",
            "example": {
              "chunk_id": "HydraEmbeddings123_0",
              "event_end": 1,
              "event_start": 1,
              "relationship_id": "rel_1234",
              "source_id": "HydraDoc1234",
              "status": "completed"
            }
          },
          "to_date": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "search.TemporalFact": {
        "properties": {
          "chunk_id": {
            "description": "Chunk that provides evidence for this relation.",
            "example": "HydraEmbeddings123_0",
            "type": "string"
          },
          "date_precision": {
            "description": "DatePrecision is the resolution of the resolved dates: \"day\", \"month\",\n\"year\" (coarser-than-day dates are floored to bracket starts).",
            "type": "string"
          },
          "event_end": {
            "example": 1,
            "type": "integer"
          },
          "event_start": {
            "example": 1,
            "type": "integer"
          },
          "evidence_phrase": {
            "description": "EvidencePhrase is the verbatim source phrase the dates were resolved\nfrom (e.g. \"today\", \"two weeks ago\").",
            "type": "string"
          },
          "fact_type": {
            "type": "string"
          },
          "object": {
            "type": "string"
          },
          "relation": {
            "type": "string"
          },
          "relationship_id": {
            "description": "Unique identifier for this relationship instance.",
            "example": "rel_1234",
            "type": "string"
          },
          "source_id": {
            "example": "HydraDoc1234",
            "type": "string"
          },
          "status": {
            "description": "Current lifecycle or processing state.",
            "example": "completed",
            "type": "string"
          },
          "subject": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "search.TemporalFilterInfo": {
        "description": "TemporalFilter reports what the temporal layer did for this request.",
        "properties": {
          "applied": {
            "description": "Applied is true when the temporal layer engaged for a classified temporal\nquery — including when it matched zero dated facts; MatchedFacts carries the\nactual count. It is false only when the fact lookup degraded (Degraded).",
            "example": true,
            "type": "boolean"
          },
          "chunk_scope": {
            "example": 1,
            "type": "integer"
          },
          "degraded": {
            "description": "Degraded is true when the fact lookup FAILED (as opposed to matching\nnothing) — callers must not read an empty payload as \"no temporal facts\nexist\" when this is set.",
            "example": true,
            "type": "boolean"
          },
          "matched_facts": {
            "example": 1,
            "type": "integer"
          },
          "mode": {
            "example": "thinking",
            "type": "string"
          },
          "promoted": {
            "example": 1,
            "type": "integer"
          },
          "scope": {
            "description": "Scope reports how the chunk scope was applied: \"soft\" (bounded ranking\npromotion) or \"\" (no scope). Hard scoping was removed after TEMPO.",
            "type": "string"
          },
          "truncated": {
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "search.TemporalIntentOverride": {
        "description": "TemporalIntent (EXPERIMENTAL) lets the caller supply the classification\n(mode/window/phrases) directly, bypassing the regex classifier — for\nagents whose own LLM already understands the query, and for non-English\nqueries. Invalid overrides fall back to the classifier.",
        "properties": {
          "cutoff": {
            "type": "string"
          },
          "duration_to_now": {
            "example": true,
            "type": "boolean"
          },
          "event_phrases": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false
          },
          "mode": {
            "example": "thinking",
            "type": "string"
          },
          "window_end": {
            "type": "string"
          },
          "window_start": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "search.V2Chunk": {
        "properties": {
          "additional_metadata": {
            "additionalProperties": {},
            "description": "Pydantic aliases (see VectorStoreChunk): document_metadata→additional_metadata,\ntenant_metadata→metadata. FastAPI serializes by_alias, so the wire uses the aliases.",
            "example": {
              "author": "ada",
              "doc_version": 3
            },
            "type": "object"
          },
          "chunk_content": {
            "description": "Text content of this chunk.",
            "example": "HydraDB supports hybrid retrieval across knowledge and memories.",
            "type": "string"
          },
          "chunk_uuid": {
            "description": "Unique identifier for this individual chunk.",
            "example": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
            "type": "string"
          },
          "collection": {
            "description": "Collection this chunk belongs to. Canonical name; mirrors the deprecated `sub_tenant_id` alias.",
            "example": "team_docs",
            "type": "string"
          },
          "extra_context_ids": {
            "description": "IDs of adjacent chunks pulled in as surrounding context.",
            "example": [
              "HydraEmbeddings123_2",
              "HydraEmbeddings123_3"
            ],
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false
          },
          "id": {
            "description": "Unique identifier for this resource.",
            "example": "HydraDoc1234",
            "type": "string"
          },
          "layout": {
            "description": "Layout classification for this chunk (e.g. `text`, `table`, `image`).",
            "example": "text",
            "type": "string"
          },
          "metadata": {
            "additionalProperties": {},
            "description": "Schema-backed tenant metadata attached to the source.",
            "example": {
              "department": "finance",
              "priority": 7
            },
            "type": "object"
          },
          "relevancy_score": {
            "description": "Relevance score for this item against the query.",
            "example": 0.87,
            "type": "number"
          },
          "source_last_updated_time": {
            "description": "RFC3339 timestamp when the source was last modified.",
            "example": "2026-07-02T12:30:00Z",
            "type": "string"
          },
          "source_title": {
            "description": "Title of the parent source document.",
            "example": "Project Phoenix Overview",
            "type": "string"
          },
          "source_type": {
            "description": "Type of the parent source (e.g. `file`, `slack`, `notion`).",
            "example": "file",
            "type": "string"
          },
          "source_upload_time": {
            "description": "RFC3339 timestamp when the source was ingested.",
            "example": "2026-07-02T10:00:00Z",
            "type": "string"
          },
          "sub_tenant_id": {
            "deprecated": true,
            "description": "deprecated: use collection",
            "example": "sub_tenant_4567",
            "type": "string",
            "x-deprecated": "true"
          }
        },
        "type": "object"
      },
      "search.V2RetrievalResult": {
        "properties": {
          "additional_context": {
            "additionalProperties": {
              "$ref": "#/components/schemas/search.V2Chunk"
            },
            "deprecated": true,
            "description": "deprecated: use forceful_relations",
            "example": "The user is a senior engineer onboarding to the platform.",
            "type": "object",
            "x-deprecated": "true"
          },
          "alias_expansions": {
            "description": "AliasExpansions is the alias layer's honesty stamp (V0): which nickname\nwas expanded to which canonical name for this answer.",
            "items": {
              "$ref": "#/components/schemas/search.AliasExpansionNote"
            },
            "type": "array",
            "uniqueItems": false
          },
          "app_search_fusion": {
            "$ref": "#/components/schemas/search.AppSearchFusionDiagnostics",
            "description": "App-search fusion diagnostics for unscoped requests: final returned chunk attribution and pre-postprocessing fusion counts. Omitted for ACL-scoped requests and when no attributed chunks remain.",
            "example": {
              "stats": {
                "app_chunks": 1,
                "app_has_exact_ids": true,
                "app_lane_empty_text": true,
                "consensus": 1,
                "exact_candidates": 1,
                "exact_promoted": 1,
                "limit": 1,
                "normal_chunks": 1,
                "normal_displaced": 1,
                "tail_added": 1,
                "tail_candidates": 1
              },
              "stats_by_pass": [
                {
                  "app_chunks": 1,
                  "app_has_exact_ids": true,
                  "app_lane_empty_text": true,
                  "consensus": 1,
                  "exact_candidates": 1,
                  "exact_promoted": 1,
                  "limit": 1,
                  "normal_chunks": 1,
                  "normal_displaced": 1,
                  "tail_added": 1,
                  "tail_candidates": 1
                }
              ]
            }
          },
          "chunks": {
            "description": "Retrieved and ranked chunks from the knowledge store or memories.",
            "example": [
              {
                "additional_metadata": {
                  "author": "ada",
                  "doc_version": 3
                },
                "chunk_content": "HydraDB supports hybrid retrieval across knowledge and memories.",
                "chunk_uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
                "collection": "team_docs",
                "extra_context_ids": [
                  "HydraEmbeddings123_2",
                  "HydraEmbeddings123_3"
                ],
                "id": "HydraDoc1234",
                "layout": "text",
                "metadata": {
                  "department": "finance",
                  "priority": 7
                },
                "relevancy_score": 0.87,
                "source_last_updated_time": "2026-07-02T12:30:00Z",
                "source_title": "Project Phoenix Overview",
                "source_type": "file",
                "source_upload_time": "2026-07-02T10:00:00Z",
                "sub_tenant_id": "sub_tenant_4567"
              }
            ],
            "items": {
              "$ref": "#/components/schemas/search.V2Chunk"
            },
            "type": "array",
            "uniqueItems": false
          },
          "code_search": {
            "$ref": "#/components/schemas/search.CodeSearchResult",
            "example": {
              "duration_ms": 0.5,
              "repos": [
                {
                  "duration_ms": 0.5,
                  "error": "",
                  "status": "completed",
                  "truncated": true,
                  "unsigned": true
                }
              ],
              "status": "completed"
            }
          },
          "forceful_relations": {
            "$ref": "#/components/schemas/search.ForcefulRelationsBucket",
            "example": {
              "declared": [
                {
                  "chunk": {
                    "additional_metadata": {
                      "author": "ada",
                      "doc_version": 3
                    },
                    "chunk_content": "HydraDB supports hybrid retrieval across knowledge and memories.",
                    "chunk_uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
                    "collection": "team_docs",
                    "extra_context_ids": [
                      "HydraEmbeddings123_2",
                      "HydraEmbeddings123_3"
                    ],
                    "id": "HydraDoc1234",
                    "layout": "text",
                    "metadata": {
                      "department": "finance",
                      "priority": 7
                    },
                    "relevancy_score": 0.87,
                    "source_last_updated_time": "2026-07-02T12:30:00Z",
                    "source_title": "Project Phoenix Overview",
                    "source_type": "file",
                    "source_upload_time": "2026-07-02T10:00:00Z",
                    "sub_tenant_id": "sub_tenant_4567"
                  }
                }
              ],
              "inferred": [
                {
                  "chunk": {
                    "additional_metadata": {
                      "author": "ada",
                      "doc_version": 3
                    },
                    "chunk_content": "HydraDB supports hybrid retrieval across knowledge and memories.",
                    "chunk_uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
                    "collection": "team_docs",
                    "extra_context_ids": [
                      "HydraEmbeddings123_2",
                      "HydraEmbeddings123_3"
                    ],
                    "id": "HydraDoc1234",
                    "layout": "text",
                    "metadata": {
                      "department": "finance",
                      "priority": 7
                    },
                    "relevancy_score": 0.87,
                    "source_last_updated_time": "2026-07-02T12:30:00Z",
                    "source_title": "Project Phoenix Overview",
                    "source_type": "file",
                    "source_upload_time": "2026-07-02T10:00:00Z",
                    "sub_tenant_id": "sub_tenant_4567"
                  }
                }
              ]
            }
          },
          "graph": {
            "$ref": "#/components/schemas/search.GraphPlane",
            "example": {
              "paths": [
                {
                  "chunk_ids": [
                    "HydraEmbeddings123_0",
                    "HydraEmbeddings123_1"
                  ],
                  "combined_context": "Acme Corp deploys HydraDB in production for context retrieval.",
                  "relevancy_score": 0.87,
                  "triplets": [
                    {
                      "relation": {
                        "confidence": 0.92,
                        "predicate": "works_at"
                      },
                      "source": {
                        "entity_id": "entity_1a2b",
                        "name": "Ada",
                        "type": "person"
                      },
                      "target": {
                        "entity_id": "entity_3c4d",
                        "name": "Acme Corp",
                        "type": "organization"
                      }
                    }
                  ]
                }
              ]
            }
          },
          "graph_context": {
            "$ref": "#/components/schemas/search.GraphContext",
            "example": {
              "chunk_id_to_group_ids": {
                "HydraEmbeddings123_0": [
                  "grp_1234"
                ]
              },
              "chunk_relations": [
                {
                  "combined_context": "Acme Corp deploys HydraDB in production for context retrieval.",
                  "group_id": "grp_1234",
                  "relevancy_score": 0.87,
                  "source_chunk_ids": [
                    "HydraEmbeddings123_0",
                    "HydraEmbeddings123_1"
                  ],
                  "triplets": [
                    {
                      "relation": {
                        "confidence": 0.92,
                        "predicate": "works_at"
                      },
                      "source": {
                        "entity_id": "entity_1a2b",
                        "name": "Ada",
                        "type": "person"
                      },
                      "target": {
                        "entity_id": "entity_3c4d",
                        "name": "Acme Corp",
                        "type": "organization"
                      }
                    }
                  ]
                }
              ],
              "query_paths": [
                {
                  "combined_context": "Acme Corp deploys HydraDB in production for context retrieval.",
                  "group_id": "grp_1234",
                  "relevancy_score": 0.87,
                  "source_chunk_ids": [
                    "HydraEmbeddings123_0",
                    "HydraEmbeddings123_1"
                  ],
                  "triplets": [
                    {
                      "relation": {
                        "confidence": 0.92,
                        "predicate": "works_at"
                      },
                      "source": {
                        "entity_id": "entity_1a2b",
                        "name": "Ada",
                        "type": "person"
                      },
                      "target": {
                        "entity_id": "entity_3c4d",
                        "name": "Acme Corp",
                        "type": "organization"
                      }
                    }
                  ]
                }
              ]
            }
          },
          "profile_context": {
            "$ref": "#/components/schemas/search.ProfileContext",
            "example": {
              "entity_id": "entity_1a2b",
              "entries": [
                {
                  "confidence": 0.92
                }
              ],
              "name": "general",
              "version": 1
            }
          },
          "profile_filter": {
            "$ref": "#/components/schemas/search.ProfileFilterInfo",
            "example": {
              "applied": true,
              "degraded": true,
              "entity_id": "entity_1a2b",
              "found": true,
              "selected_entries": 1,
              "version": 1
            }
          },
          "source_facts": {
            "description": "SourceFacts surface the matched app-native (edge_source) facts when\nsource_reasoning was active; omitted otherwise (PRO-1602).",
            "example": [
              {
                "app_kind": "slack",
                "chunk_id": "HydraEmbeddings123_0",
                "provider": "slack",
                "relationship_id": "rel_1234",
                "source_id": "HydraDoc1234",
                "synced_at": 1
              }
            ],
            "items": {
              "$ref": "#/components/schemas/search.SourceFact"
            },
            "type": "array",
            "uniqueItems": false
          },
          "source_filter": {
            "$ref": "#/components/schemas/search.SourceFilterInfo",
            "example": {
              "applied": true,
              "degraded": true,
              "matched_facts": 1,
              "mode": "thinking",
              "provider": "slack",
              "thread_scope": true,
              "truncated": true
            }
          },
          "sources": {
            "description": "Deduplicated source-level metadata for all returned chunks.",
            "example": [
              {
                "additional_metadata": {
                  "author": "ada",
                  "doc_version": 3
                },
                "app_external_id": "C0123456789",
                "app_kind": "slack",
                "app_provider": "slack",
                "collection": "team_docs",
                "description": "Internal overview of the Project Phoenix rollout.",
                "id": "HydraDoc1234",
                "metadata": {
                  "department": "finance",
                  "priority": 7
                },
                "sub_tenant_id": "sub_tenant_4567",
                "timestamp": "2026-07-02T10:00:00Z",
                "title": "Project Phoenix Overview",
                "type": "knowledge",
                "url": "https://docs.hydradb.com/phoenix"
              }
            ],
            "items": {
              "$ref": "#/components/schemas/search.SourceInfo"
            },
            "type": "array",
            "uniqueItems": false
          },
          "temporal_duration": {
            "$ref": "#/components/schemas/search.TemporalDuration",
            "example": {
              "approximate": true,
              "days": 1,
              "from": {
                "chunk_id": "HydraEmbeddings123_0",
                "event_end": 1,
                "event_start": 1,
                "relationship_id": "rel_1234",
                "source_id": "HydraDoc1234",
                "status": "completed"
              },
              "pairing_confidence": 0.5,
              "to": {
                "chunk_id": "HydraEmbeddings123_0",
                "event_end": 1,
                "event_start": 1,
                "relationship_id": "rel_1234",
                "source_id": "HydraDoc1234",
                "status": "completed"
              }
            }
          },
          "temporal_facts": {
            "description": "TemporalFacts surface the matched edge-level temporal facts when\ntemporal_reasoning was requested; omitted otherwise.",
            "example": [
              {
                "chunk_id": "HydraEmbeddings123_0",
                "event_end": 1,
                "event_start": 1,
                "relationship_id": "rel_1234",
                "source_id": "HydraDoc1234",
                "status": "completed"
              }
            ],
            "items": {
              "$ref": "#/components/schemas/search.TemporalFact"
            },
            "type": "array",
            "uniqueItems": false
          },
          "temporal_filter": {
            "$ref": "#/components/schemas/search.TemporalFilterInfo",
            "example": {
              "applied": true,
              "chunk_scope": 1,
              "degraded": true,
              "matched_facts": 1,
              "mode": "thinking",
              "promoted": 1,
              "truncated": true
            }
          }
        },
        "type": "object"
      },
      "search.VectorStoreChunk": {
        "properties": {
          "additional_metadata": {
            "additionalProperties": {},
            "description": "Pydantic aliases: document_metadata→additional_metadata, tenant_metadata→metadata.\nFastAPI serializes responses by_alias, so the wire uses the alias names.",
            "example": {
              "author": "ada",
              "doc_version": 3
            },
            "type": "object"
          },
          "chunk_content": {
            "description": "Text content of this chunk.",
            "example": "HydraDB supports hybrid retrieval across knowledge and memories.",
            "type": "string"
          },
          "chunk_uuid": {
            "description": "Unique identifier for this individual chunk.",
            "example": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
            "type": "string"
          },
          "extra_context_ids": {
            "description": "IDs of adjacent chunks pulled in as surrounding context.",
            "example": [
              "HydraEmbeddings123_2",
              "HydraEmbeddings123_3"
            ],
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false
          },
          "layout": {
            "description": "Layout classification for this chunk (e.g. `text`, `table`, `image`).",
            "example": "text",
            "type": "string"
          },
          "metadata": {
            "additionalProperties": {},
            "example": {
              "department": "finance",
              "priority": 7
            },
            "type": "object"
          },
          "relevancy_score": {
            "description": "Relevance score for this item against the query.",
            "example": 0.87,
            "type": "number"
          },
          "source_id": {
            "example": "HydraDoc1234",
            "type": "string"
          },
          "source_last_updated_time": {
            "description": "RFC3339 timestamp when the source was last modified.",
            "example": "2026-07-02T12:30:00Z",
            "type": "string"
          },
          "source_title": {
            "description": "Title of the parent source document.",
            "example": "Project Phoenix Overview",
            "type": "string"
          },
          "source_type": {
            "description": "Type of the parent source (e.g. `file`, `slack`, `notion`).",
            "example": "file",
            "type": "string"
          },
          "source_upload_time": {
            "description": "RFC3339 timestamp when the source was ingested.",
            "example": "2026-07-02T10:00:00Z",
            "type": "string"
          },
          "sub_tenant_id": {
            "example": "sub_tenant_4567",
            "type": "string"
          }
        },
        "type": "object"
      },
      "sources.MemoryDeleteResponse": {
        "properties": {
          "deleted_count": {
            "description": "Total number of items successfully deleted.",
            "example": 1,
            "type": "integer"
          },
          "message": {
            "description": "Human-readable result message.",
            "example": "Success",
            "type": "string"
          },
          "results": {
            "description": "Per-item results.",
            "example": [
              {
                "deleted": true,
                "error": "",
                "id": "HydraDoc1234"
              }
            ],
            "items": {
              "$ref": "#/components/schemas/sources.SourceDeleteResultItem"
            },
            "type": "array",
            "uniqueItems": false
          },
          "success": {
            "deprecated": true,
            "description": "Deprecated for API clients: whether the REQUEST succeeded is the HTTP\nstatus code, or equivalently the envelope's top-level `success`. Whether\nanything was actually removed is deleted_count (0 means the ids matched\nnothing) and per-id results[].deleted / results[].error. This flag is\ntrue even for a delete that removed nothing, so it cannot answer either\nquestion on its own. Still emitted unchanged for existing clients\n(PRO-1208).",
            "example": true,
            "type": "boolean",
            "x-deprecated": "true"
          },
          "user_memory_deleted": {
            "description": "Number of memory items deleted.",
            "example": 1,
            "type": "integer"
          }
        },
        "type": "object"
      },
      "sources.SourceDeleteResultItem": {
        "properties": {
          "deleted": {
            "description": "Whether this specific item was deleted.",
            "example": true,
            "type": "boolean"
          },
          "error": {
            "description": "Error message for this item, empty string on success.",
            "example": "",
            "type": "string"
          },
          "id": {
            "description": "Unique identifier for this resource.",
            "example": "HydraDoc1234",
            "type": "string"
          }
        },
        "type": "object"
      },
      "sources.V2SourceDeleteRequest": {
        "properties": {
          "collection": {
            "description": "Collection scope. Defaults to the default collection when omitted. Formerly `sub_tenant_id`; the `sub_tenant_id` alias is still accepted (deprecated).",
            "example": "team_docs",
            "type": "string"
          },
          "database": {
            "description": "Database/Collection are the canonical v2 names; TenantID/SubTenantID are\ntheir deprecated aliases, reconciled by the TenantAliases middleware before\nbinding so TenantID is always populated.",
            "example": "acme_corp",
            "type": "string"
          },
          "ids": {
            "description": "IDs of the sources or memories to delete.",
            "example": [
              "HydraDoc1234",
              "HydraDoc4567"
            ],
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false
          },
          "sub_tenant_id": {
            "deprecated": true,
            "description": "deprecated: use collection",
            "example": "sub_tenant_4567",
            "type": "string",
            "x-deprecated": "true"
          },
          "tenant_id": {
            "deprecated": true,
            "description": "deprecated: use database",
            "example": "tenant_1234",
            "type": "string",
            "x-deprecated": "true"
          },
          "type": {
            "description": "Type names the corpus: knowledge (default) or memory.",
            "enum": [
              "knowledge",
              "memory",
              "all"
            ],
            "example": "knowledge",
            "type": "string"
          }
        },
        "type": "object"
      },
      "tenants.CollectionStats": {
        "properties": {
          "row_count": {
            "description": "Total number of indexed rows in this collection.",
            "example": 1280,
            "type": "integer"
          }
        },
        "type": "object"
      },
      "tenants.CustomPropertyDefinition": {
        "properties": {
          "data_type": {
            "$ref": "#/components/schemas/tenants.MilvusDataType",
            "description": "Milvus data type for this metadata field.",
            "example": "VARCHAR"
          },
          "enable_dense_embedding": {
            "description": "Whether to enable semantic (dense) embedding search on this field.",
            "example": true,
            "type": "boolean"
          },
          "enable_match": {
            "description": "Whether to enable exact-match filtering on this field.",
            "example": true,
            "type": "boolean"
          },
          "enable_sparse_embedding": {
            "description": "Whether to enable BM25 (sparse) embedding search on this field.",
            "example": false,
            "type": "boolean"
          },
          "max_length": {
            "description": "Maximum string length in bytes for VARCHAR fields.",
            "example": 256,
            "type": "integer"
          },
          "name": {
            "description": "Field name. Immutable after database creation.",
            "example": "category",
            "type": "string"
          }
        },
        "type": "object"
      },
      "tenants.DatabaseDetail": {
        "properties": {
          "database": {
            "description": "Owning database. Formerly `tenant_id`; the `tenant_id` alias is still accepted (deprecated).",
            "example": "acme_corp",
            "type": "string"
          },
          "type": {
            "description": "Type is the storage layout the database was created with: \"split\" (a\nknowledge and a memory corpus, selected by `type` on every call).\nAbsent where the deployment does not expose the layout.",
            "enum": [
              "split"
            ],
            "example": "split",
            "type": "string"
          }
        },
        "type": "object"
      },
      "tenants.FailedTenant": {
        "properties": {
          "database": {
            "description": "Database identifier that failed provisioning.",
            "example": "acme_corp",
            "type": "string"
          },
          "error": {
            "description": "Error message explaining why the database failed.",
            "example": "",
            "type": "string"
          },
          "tenant_id": {
            "deprecated": true,
            "example": "tenant_1234",
            "type": "string",
            "x-deprecated": "true"
          }
        },
        "type": "object"
      },
      "tenants.InfraStatusResponseV2": {
        "properties": {
          "database": {
            "description": "Owning database. Formerly `tenant_id`; the `tenant_id` alias is still accepted (deprecated).",
            "example": "acme_corp",
            "type": "string"
          },
          "infra": {
            "$ref": "#/components/schemas/tenants.InfraV2",
            "example": {
              "graph_status": true,
              "ready_for_ingestion": true,
              "scheduler_status": true,
              "vectorstore_status": {
                "knowledge": true,
                "memories": true
              }
            }
          },
          "message": {
            "description": "Human-readable result message.",
            "example": "Success",
            "type": "string"
          },
          "org_id": {
            "description": "Organization that owns this resource.",
            "example": "org_1a2b3c",
            "type": "string"
          },
          "tenant_id": {
            "deprecated": true,
            "example": "tenant_1234",
            "type": "string",
            "x-deprecated": "true"
          },
          "type": {
            "description": "Type is the storage layout the database was created with; absent while the\ndatabase is deleting or unknown.",
            "enum": [
              "split"
            ],
            "example": "split",
            "type": "string"
          }
        },
        "type": "object"
      },
      "tenants.InfraV2": {
        "properties": {
          "graph_status": {
            "description": "Whether the graph store is healthy for this database.",
            "example": true,
            "type": "boolean"
          },
          "ready_for_ingestion": {
            "description": "Derived readiness flag: true only when scheduler_status (lifecycle provisioning finished), graph_status, and both vectorstore_status.knowledge and vectorstore_status.memories are true — i.e. the database is fully provisioned and ready to accept ingestion and serve queries. Database creation is asynchronous: collections may appear before provisioning completes, so poll GET /databases/status until this is true before ingesting or querying.",
            "example": true,
            "type": "boolean"
          },
          "scheduler_status": {
            "description": "Whether lifecycle provisioning has finished for this database (creation_status is ready). False while the database is still being created, even if individual collections already exist.",
            "example": true,
            "type": "boolean"
          },
          "vectorstore_status": {
            "$ref": "#/components/schemas/tenants.VectorstoreStatusV2",
            "example": {
              "knowledge": true,
              "memories": true
            }
          }
        },
        "type": "object"
      },
      "tenants.MilvusDataType": {
        "description": "Declared type of a database metadata schema field. ARRAY appears in this enum because schemas persisted before it was rejected still read back and rebuild, but it CANNOT be declared on a new or evolved field: both the create and the update-metadata-schema endpoints answer 400 for it. For a field holding several values, declare VARCHAR and store the values comma-joined, then filter one member with the contains operator.",
        "enum": [
          "BOOL",
          "INT8",
          "INT16",
          "INT32",
          "INT64",
          "FLOAT",
          "DOUBLE",
          "VARCHAR",
          "JSON",
          "ARRAY"
        ],
        "type": "string",
        "x-enum-varnames": [
          "DataTypeBool",
          "DataTypeInt8",
          "DataTypeInt16",
          "DataTypeInt32",
          "DataTypeInt64",
          "DataTypeFloat",
          "DataTypeDouble",
          "DataTypeVarchar",
          "DataTypeJSON",
          "DataTypeArray"
        ]
      },
      "tenants.SubTenantDeleteResponse": {
        "properties": {
          "collection": {
            "description": "Collection scope. Defaults to the default collection when omitted. Formerly `sub_tenant_id`; the `sub_tenant_id` alias is still accepted (deprecated).",
            "example": "team_docs",
            "type": "string"
          },
          "database": {
            "description": "Owning database. Formerly `tenant_id`; the `tenant_id` alias is still accepted (deprecated).",
            "example": "acme_corp",
            "type": "string"
          },
          "message": {
            "description": "Human-readable result message.",
            "example": "Success",
            "type": "string"
          },
          "status": {
            "description": "Current lifecycle or processing state.",
            "example": "completed",
            "type": "string"
          },
          "sub_tenant_id": {
            "deprecated": true,
            "example": "sub_tenant_4567",
            "type": "string",
            "x-deprecated": "true"
          },
          "tenant_id": {
            "deprecated": true,
            "example": "tenant_1234",
            "type": "string",
            "x-deprecated": "true"
          }
        },
        "type": "object"
      },
      "tenants.SubTenantIdsResponse": {
        "properties": {
          "collections": {
            "description": "List of collection identifiers for this database.",
            "example": [
              "team_docs",
              "engineering"
            ],
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false
          },
          "message": {
            "description": "Human-readable result message.",
            "example": "Success",
            "type": "string"
          },
          "sub_tenant_ids": {
            "deprecated": true,
            "description": "Deprecated alias for `collections`.",
            "example": [
              "sub_tenant_4567",
              "sub_tenant_8901"
            ],
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false,
            "x-deprecated": "true"
          }
        },
        "type": "object"
      },
      "tenants.TenantCreateAcceptedResponse": {
        "properties": {
          "database": {
            "description": "Owning database. Formerly `tenant_id`; the `tenant_id` alias is still accepted (deprecated).",
            "example": "acme_corp",
            "type": "string"
          },
          "message": {
            "description": "Human-readable result message.",
            "example": "Success",
            "type": "string"
          },
          "status": {
            "description": "Current lifecycle or processing state.",
            "example": "completed",
            "type": "string"
          },
          "tenant_id": {
            "deprecated": true,
            "example": "tenant_1234",
            "type": "string",
            "x-deprecated": "true"
          }
        },
        "type": "object"
      },
      "tenants.TenantCreateRequest": {
        "properties": {
          "database": {
            "description": "Database is the canonical v2 name; TenantID is its deprecated alias and\nremains fully accepted. The TenantAliases middleware reconciles them before\nthis binds, so TenantID is always populated.",
            "example": "acme_corp",
            "type": "string"
          },
          "database_metadata_schema": {
            "description": "Defines database-level metadata fields for exact-match filtering and semantic/BM25 search. Canonical name; `tenant_metadata_schema` is a deprecated alias. Schema field names are immutable after database creation.",
            "example": [
              {
                "data_type": "VARCHAR",
                "enable_dense_embedding": true,
                "enable_match": true,
                "enable_sparse_embedding": false,
                "max_length": 256,
                "name": "category"
              }
            ],
            "items": {
              "$ref": "#/components/schemas/tenants.CustomPropertyDefinition"
            },
            "type": "array",
            "uniqueItems": false
          },
          "embeddings_dimension": {
            "description": "Override for the embedding vector dimension. Default: 1536.",
            "example": 1536,
            "type": "integer"
          },
          "is_embeddings_tenant": {
            "description": "Internal flag for embedding-only databases.",
            "example": false,
            "type": "boolean"
          },
          "tenant_id": {
            "deprecated": true,
            "description": "deprecated: use database",
            "example": "tenant_1234",
            "type": "string",
            "x-deprecated": "true"
          },
          "tenant_metadata_schema": {
            "deprecated": true,
            "description": "deprecated: use database_metadata_schema",
            "items": {
              "$ref": "#/components/schemas/tenants.CustomPropertyDefinition"
            },
            "type": "array",
            "uniqueItems": false,
            "x-deprecated": "true"
          },
          "type": {
            "$ref": "#/components/schemas/github_com_hydradb_hydradb-application_internal_platform_storagelayout.Layout"
          }
        },
        "type": "object"
      },
      "tenants.TenantDeleteResponse": {
        "properties": {
          "database": {
            "description": "Owning database. Formerly `tenant_id`; the `tenant_id` alias is still accepted (deprecated).",
            "example": "acme_corp",
            "type": "string"
          },
          "message": {
            "description": "Human-readable result message.",
            "example": "Success",
            "type": "string"
          },
          "status": {
            "description": "Current lifecycle or processing state.",
            "example": "completed",
            "type": "string"
          },
          "tenant_id": {
            "deprecated": true,
            "example": "tenant_1234",
            "type": "string",
            "x-deprecated": "true"
          }
        },
        "type": "object"
      },
      "tenants.TenantIdsResponse": {
        "properties": {
          "databases": {
            "description": "List of database identifiers.",
            "example": [
              "acme_corp",
              "research_kb"
            ],
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false
          },
          "details": {
            "description": "Details carries one entry per live database with its storage layout.",
            "example": [
              {
                "database": "acme_corp",
                "type": "split"
              }
            ],
            "items": {
              "$ref": "#/components/schemas/tenants.DatabaseDetail"
            },
            "type": "array",
            "uniqueItems": false
          },
          "failed_databases": {
            "description": "Databases that failed provisioning, with error details.",
            "example": [
              {
                "database": "acme_corp",
                "error": "",
                "tenant_id": "tenant_1234"
              }
            ],
            "items": {
              "$ref": "#/components/schemas/tenants.FailedTenant"
            },
            "type": "array",
            "uniqueItems": false
          },
          "failed_tenant_ids": {
            "deprecated": true,
            "description": "Deprecated alias for `failed_databases`.",
            "example": [
              {
                "database": "acme_corp",
                "error": "",
                "tenant_id": "tenant_1234"
              }
            ],
            "items": {
              "$ref": "#/components/schemas/tenants.FailedTenant"
            },
            "type": "array",
            "uniqueItems": false,
            "x-deprecated": "true"
          },
          "message": {
            "description": "Human-readable result message.",
            "example": "Success",
            "type": "string"
          },
          "tenant_ids": {
            "deprecated": true,
            "description": "Deprecated alias for `databases`.",
            "example": [
              "tenant_1234",
              "tenant_5678"
            ],
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false,
            "x-deprecated": "true"
          }
        },
        "type": "object"
      },
      "tenants.TenantMetadataSchemaResponse": {
        "properties": {
          "database": {
            "description": "Owning database. Formerly `tenant_id`; the `tenant_id` alias is still accepted (deprecated).",
            "example": "acme_corp",
            "type": "string"
          },
          "fields": {
            "example": [
              {
                "data_type": "VARCHAR",
                "enable_dense_embedding": true,
                "enable_match": true,
                "enable_sparse_embedding": false,
                "max_length": 256,
                "name": "category"
              }
            ],
            "items": {
              "$ref": "#/components/schemas/tenants.CustomPropertyDefinition"
            },
            "type": "array",
            "uniqueItems": false
          },
          "tenant_id": {
            "deprecated": true,
            "example": "acme_corp",
            "type": "string",
            "x-deprecated": "true"
          }
        },
        "type": "object"
      },
      "tenants.TenantMetadataSchemaUpdateRequest": {
        "properties": {
          "add_fields": {
            "description": "New metadata schema fields to add to the database. Additive only — no deletes, renames, or type changes.",
            "example": [
              {
                "data_type": "VARCHAR",
                "enable_dense_embedding": true,
                "enable_match": true,
                "enable_sparse_embedding": false,
                "max_length": 256,
                "name": "category"
              }
            ],
            "items": {
              "$ref": "#/components/schemas/tenants.CustomPropertyDefinition"
            },
            "type": "array",
            "uniqueItems": false
          }
        },
        "type": "object"
      },
      "tenants.TenantRenameRequest": {
        "properties": {
          "new_name": {
            "description": "NewName is the database's new caller-facing name. Same rules as a\ncreate-time name (ValidateTenantName).\n\nbinding:\"required\" is read by swag, so the published schema lists the\nfield as required and generated SDKs make it a mandatory argument; it is\ninert at runtime, because the handler decodes through ParseRenameRequest,\nwhich rejects a missing or blank new_name itself.",
            "type": "string"
          }
        },
        "required": [
          "new_name"
        ],
        "type": "object"
      },
      "tenants.TenantRenameResponse": {
        "properties": {
          "connector_reassignment": {
            "description": "ConnectorReassignment reports how the rename's connector sweep ended:\n\"complete\" (every connector already targets the new name), \"queued\" (a\ndurable background reconciliation owns the remainder and retries until\ndrained), or \"failed\" (neither — contact support; the failure is also\nalerted on server-side). The rename itself has succeeded in all three\nstates.",
            "example": "complete",
            "type": "string"
          },
          "database": {
            "description": "Owning database. Formerly `tenant_id`; the `tenant_id` alias is still accepted (deprecated).",
            "example": "acme_corp",
            "type": "string"
          },
          "message": {
            "description": "Human-readable result message.",
            "example": "Success",
            "type": "string"
          },
          "old_database": {
            "type": "string"
          },
          "old_tenant_id": {
            "deprecated": true,
            "type": "string",
            "x-deprecated": "true"
          },
          "status": {
            "description": "Current lifecycle or processing state.",
            "example": "completed",
            "type": "string"
          },
          "tenant_id": {
            "deprecated": true,
            "example": "tenant_1234",
            "type": "string",
            "x-deprecated": "true"
          }
        },
        "type": "object"
      },
      "tenants.TenantStatsResponse": {
        "properties": {
          "database": {
            "description": "Owning database. Formerly `tenant_id`; the `tenant_id` alias is still accepted (deprecated).",
            "example": "acme_corp",
            "type": "string"
          },
          "knowledge_collection": {
            "$ref": "#/components/schemas/tenants.CollectionStats",
            "example": {
              "row_count": 1280
            }
          },
          "memory_collection": {
            "$ref": "#/components/schemas/tenants.CollectionStats",
            "example": {
              "row_count": 1280
            }
          },
          "message": {
            "description": "Human-readable result message.",
            "example": "Success",
            "type": "string"
          },
          "tenant_id": {
            "deprecated": true,
            "example": "tenant_1234",
            "type": "string",
            "x-deprecated": "true"
          }
        },
        "type": "object"
      },
      "tenants.VectorstoreStatusV2": {
        "properties": {
          "knowledge": {
            "description": "Whether the knowledge vector store is healthy.",
            "example": true,
            "type": "boolean"
          },
          "memories": {
            "description": "Whether the memories vector store is healthy.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "webhooks.DeliveryItem": {
        "properties": {
          "attempts": {
            "description": "Number of delivery attempts made.",
            "example": 1,
            "type": "integer"
          },
          "created_at": {
            "description": "RFC3339 timestamp when this item was created.",
            "example": "2026-07-02T10:00:00Z",
            "type": "string"
          },
          "delivery_id": {
            "description": "Unique identifier for this webhook delivery attempt.",
            "example": "dlv_9f8e7d6c",
            "type": "string"
          },
          "doc_id": {
            "description": "Source ID that triggered this delivery.",
            "example": "HydraDoc1234",
            "type": "string"
          },
          "error_code": {
            "description": "Machine-readable error code, empty string on success.",
            "example": "",
            "type": "string"
          },
          "error_message": {
            "description": "Human-readable error description, empty string on success.",
            "example": "",
            "type": "string"
          },
          "event_type": {
            "description": "Event that triggered this delivery (e.g. `indexing.status_changed`).",
            "example": "indexing.status_changed",
            "type": "string"
          },
          "indexing_status": {
            "description": "Current processing state: `queued`, `processing`, `completed`, or `failed`.",
            "example": "completed",
            "type": "string"
          },
          "status": {
            "description": "Current delivery status (e.g. `completed`, `failed`, `permanently_failed`).",
            "example": "completed",
            "type": "string"
          },
          "updated_at": {
            "description": "RFC3339 timestamp of the most recent update.",
            "example": "2026-07-02T10:00:05Z",
            "type": "string"
          },
          "webhook_url": {
            "description": "Endpoint this delivery was aimed at. Attributes history to the endpoint\nthat was registered when the delivery was created, rather than to whatever\nis registered now, so a changed URL does not inherit the old one's failures.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "webhooks.DeliveryListResponse": {
        "properties": {
          "count": {
            "description": "Total number of items returned.",
            "example": 12,
            "type": "integer"
          },
          "deliveries": {
            "description": "List of webhook delivery attempt records.",
            "example": [
              {
                "attempts": 1,
                "created_at": "2026-07-02T10:00:00Z",
                "delivery_id": "dlv_9f8e7d6c",
                "doc_id": "HydraDoc1234",
                "error_code": "",
                "error_message": "",
                "event_type": "indexing.status_changed",
                "indexing_status": "completed",
                "status": "completed",
                "updated_at": "2026-07-02T10:00:05Z"
              }
            ],
            "items": {
              "$ref": "#/components/schemas/webhooks.DeliveryItem"
            },
            "type": "array",
            "uniqueItems": false
          },
          "next_cursor": {
            "description": "Opaque pagination cursor for the next page; null or absent when no more pages.",
            "example": "eyJvZmZzZXQiOjUwfQ==",
            "type": "string"
          }
        },
        "type": "object"
      },
      "webhooks.RetryResponse": {
        "properties": {
          "delivery_id": {
            "description": "Unique identifier for this webhook delivery attempt.",
            "example": "dlv_9f8e7d6c",
            "type": "string"
          },
          "message": {
            "description": "Human-readable result message.",
            "example": "Success",
            "type": "string"
          },
          "queued": {
            "description": "Whether the retry was successfully queued.",
            "example": true,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "webhooks.SigningSecretRequest": {
        "properties": {
          "signing_secret": {
            "description": "Secret used to sign webhook payloads. Deliveries carry `X-HydraDB-Signature: sha256=\u003chex\u003e`, the HMAC-SHA256 of the raw request body keyed by this secret. Minimum 16 characters when you supply your own; omit it and one is generated for you. On registration, omitting this field preserves any existing secret - to disable signing, call DELETE /webhooks/indexing/signing-secret.",
            "example": "whsec_EXAMPLE_ONLY_THIS_IS_NOT_A_REAL_SIGNING_KEY",
            "type": "string"
          }
        },
        "type": "object"
      },
      "webhooks.SigningSecretResponse": {
        "properties": {
          "generated": {
            "description": "Whether the returned secret was generated by HydraDB rather than supplied by you.",
            "example": true,
            "type": "boolean"
          },
          "message": {
            "description": "Human-readable result message.",
            "example": "Success",
            "type": "string"
          },
          "signing_secret": {
            "description": "Secret used to sign webhook payloads. Deliveries carry `X-HydraDB-Signature: sha256=\u003chex\u003e`, the HMAC-SHA256 of the raw request body keyed by this secret. Minimum 16 characters when you supply your own; omit it and one is generated for you. On registration, omitting this field preserves any existing secret - to disable signing, call DELETE /webhooks/indexing/signing-secret.",
            "example": "whsec_EXAMPLE_ONLY_THIS_IS_NOT_A_REAL_SIGNING_KEY",
            "type": "string"
          }
        },
        "type": "object"
      },
      "webhooks.WebhookDeleteResponse": {
        "properties": {
          "deleted": {
            "description": "Whether this specific item was deleted.",
            "example": true,
            "type": "boolean"
          },
          "message": {
            "description": "Human-readable result message.",
            "example": "Success",
            "type": "string"
          }
        },
        "type": "object"
      },
      "webhooks.WebhookGetResponse": {
        "properties": {
          "event_types": {
            "description": "Event types to subscribe to (e.g. `[\"indexing.status_changed\"]`).",
            "example": [
              "indexing.status_changed"
            ],
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false
          },
          "registered": {
            "description": "Whether a webhook is registered for this API key.",
            "example": true,
            "type": "boolean"
          },
          "signing_secret_configured": {
            "description": "Whether a signing secret has been configured for payload verification.",
            "example": true,
            "type": "boolean"
          },
          "url": {
            "description": "Registered endpoint URL that receives webhook event deliveries.",
            "example": "https://docs.hydradb.com/phoenix",
            "type": "string"
          }
        },
        "type": "object"
      },
      "webhooks.WebhookRegisterRequest": {
        "properties": {
          "event_types": {
            "description": "Event types to subscribe to (e.g. `[\"indexing.status_changed\"]`).",
            "example": [
              "indexing.status_changed"
            ],
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false
          },
          "generate_signing_secret": {
            "description": "Generate a signing secret as part of this request, so registering and enabling signing are one atomic operation. The secret is returned once on the response and cannot be retrieved later. Mutually exclusive with `signing_secret`.",
            "example": true,
            "type": "boolean"
          },
          "signing_secret": {
            "description": "Secret used to sign webhook payloads. Deliveries carry `X-HydraDB-Signature: sha256=\u003chex\u003e`, the HMAC-SHA256 of the raw request body keyed by this secret. Minimum 16 characters when you supply your own; omit it and one is generated for you. On registration, omitting this field preserves any existing secret - to disable signing, call DELETE /webhooks/indexing/signing-secret.",
            "example": "whsec_EXAMPLE_ONLY_THIS_IS_NOT_A_REAL_SIGNING_KEY",
            "type": "string"
          },
          "url": {
            "description": "Endpoint URL to deliver webhook events to.",
            "example": "https://docs.hydradb.com/phoenix",
            "type": "string"
          }
        },
        "type": "object"
      },
      "webhooks.WebhookRegisterResponse": {
        "properties": {
          "event_types": {
            "description": "Event types to subscribe to (e.g. `[\"indexing.status_changed\"]`).",
            "example": [
              "indexing.status_changed"
            ],
            "items": {
              "type": "string"
            },
            "type": "array",
            "uniqueItems": false
          },
          "message": {
            "description": "Human-readable result message.",
            "example": "Success",
            "type": "string"
          },
          "registered": {
            "description": "Whether a webhook is registered for this API key.",
            "example": true,
            "type": "boolean"
          },
          "signing_secret": {
            "description": "Secret used to sign webhook payloads. Deliveries carry `X-HydraDB-Signature: sha256=\u003chex\u003e`, the HMAC-SHA256 of the raw request body keyed by this secret. Minimum 16 characters when you supply your own; omit it and one is generated for you. On registration, omitting this field preserves any existing secret - to disable signing, call DELETE /webhooks/indexing/signing-secret.",
            "example": "whsec_EXAMPLE_ONLY_THIS_IS_NOT_A_REAL_SIGNING_KEY",
            "type": "string"
          },
          "signing_secret_configured": {
            "description": "Whether a signing secret has been configured for payload verification.",
            "example": true,
            "type": "boolean"
          },
          "url": {
            "description": "Registered endpoint URL that receives webhook event deliveries.",
            "example": "https://docs.hydradb.com/phoenix",
            "type": "string"
          }
        },
        "type": "object"
      },
      "webhooks.WebhookTestResponse": {
        "properties": {
          "delivered": {
            "description": "Whether the test delivery was accepted by the endpoint.",
            "example": true,
            "type": "boolean"
          },
          "message": {
            "description": "Human-readable result message.",
            "example": "Success",
            "type": "string"
          },
          "status_code": {
            "description": "HTTP status code returned by the webhook endpoint.",
            "example": 200,
            "type": "integer"
          }
        },
        "type": "object"
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "bearerFormat": "API key",
        "description": "API key sent as a Bearer token: \"Bearer prefix.secret\"",
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "externalDocs": {
    "description": "",
    "url": ""
  },
  "info": {
    "contact": {
      "email": "support@hydradb.com",
      "name": "HydraDB Support"
    },
    "description": "HydraDB Application API — knowledge ingestion, search, and memory management.",
    "license": {
      "name": "Proprietary"
    },
    "title": "HydraDB Application API",
    "version": "0.1.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/connector-catalog": {
      "get": {
        "description": "List every provider in the supported_connectors control-plane table (availability, sync engine, maturity, category) for the dashboard connector catalog.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.connectorCatalogResponse"
                }
              }
            },
            "description": "OK"
          }
        },
        "summary": "List the connector catalog",
        "tags": [
          "connectors"
        ],
        "x-fern-sdk-method-name": "catalog"
      }
    },
    "/connector-discovery": {
      "post": {
        "description": "List a provider's resources directly from supplied credentials, before creating a connector. Passing cursor or limit opts into pagination (currently Notion only): the response then adds next_cursor and has_more, a page may hold fewer than limit resources, and clients must continue while has_more is true. Without either param the full resource list is returned.",
        "parameters": [
          {
            "description": "Opaque pagination cursor from a previous response's next_cursor",
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Max resources per page, 1-100 (values above 100 are clamped)",
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/handler.discoverPreviewReq"
              }
            }
          },
          "description": "Provider and credentials",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.discoverResponseBody"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "502": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Gateway"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Preview provider resources",
        "tags": [
          "connectors"
        ],
        "x-fern-sdk-group-name": "connectors",
        "x-fern-sdk-method-name": "discover_preview"
      }
    },
    "/connectors": {
      "get": {
        "description": "List all connectors for the authenticated org, optionally filtered by provider.",
        "parameters": [
          {
            "description": "Filter by provider",
            "in": "query",
            "name": "provider",
            "schema": {
              "example": "slack",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.connectorListResponse"
                }
              }
            },
            "description": "OK"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "List connectors",
        "tags": [
          "connectors"
        ],
        "x-fern-sdk-group-name": "connectors",
        "x-fern-sdk-method-name": "list"
      },
      "post": {
        "description": "Create a connector for a provider and store its credentials.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/handler.connectorCreateReq"
              }
            }
          },
          "description": "Connector configuration",
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.connectorCreateResponse"
                }
              }
            },
            "description": "Created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Service Unavailable"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Create a connector",
        "tags": [
          "connectors"
        ],
        "x-fern-sdk-group-name": "connectors",
        "x-fern-sdk-method-name": "create"
      }
    },
    "/connectors/providers": {
      "get": {
        "description": "Without ?id: returns every supported connector with its availability, maturity, category, and sync engine (the connector catalog). With ?id=\u003cprovider\u003e: returns what that provider stores and how to use it — indexed_object_types (the streams that become searchable documents), searchable_fields (rendered into the indexed text), filterable_fields (each with the exact filter_key to pass in a query's metadata_filters), the credential_schema for connecting it, and setup_guide (present for providers whose configuration goes beyond the credential schema — e.g. bigquery's per-table cursor/change-history settings and the one-time ALTER statement they may require).",
        "parameters": [
          {
            "description": "Provider name (e.g. slack, gmail). Omit to list all.",
            "in": "query",
            "name": "id",
            "schema": {
              "example": "HydraDoc1234",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.providerListResponse"
                }
              }
            },
            "description": "OK"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          }
        },
        "summary": "List supported providers, or describe one in detail",
        "tags": [
          "connectors"
        ],
        "x-fern-sdk-method-name": "listProviders"
      }
    },
    "/connectors/{id}": {
      "delete": {
        "description": "Delete a connector, its resources, and stored credentials.",
        "parameters": [
          {
            "description": "Connector ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "example": "HydraDoc1234",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.connectorDeleteResponse"
                }
              }
            },
            "description": "OK"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Delete a connector",
        "tags": [
          "connectors"
        ],
        "x-fern-sdk-group-name": "connectors",
        "x-fern-sdk-method-name": "delete"
      },
      "get": {
        "description": "Fetch a single connector by ID.",
        "parameters": [
          {
            "description": "Connector ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "example": "HydraDoc1234",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.connectorAPIView"
                }
              }
            },
            "description": "OK"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Get a connector",
        "tags": [
          "connectors"
        ],
        "x-fern-sdk-group-name": "connectors",
        "x-fern-sdk-method-name": "get"
      },
      "patch": {
        "description": "Update a connector's mutable settings. `sync_interval_seconds` sets the cadence at which the scheduler starts incremental syncs: the allowed range is provider-aware and returned in the response; values outside it are rejected rather than clamped; 0 resets to the provider default; changing it re-anchors the next sync so a shorter cadence takes effect immediately. `credentials` reconnects the connector in place: send the provider's full credential set (what create accepts); supplied keys replace their stored values, other stored keys survive, the bundle is re-validated against the provider's credential schema, and a pending needs-reauth flag is cleared — the connector keeps its id, resources, and sync cursors. `custom_instructions` replaces the free-text steering applied when this connector's documents are ingested (an explicit empty string clears it); the change applies from the next sync cycle and does not re-process already-ingested documents. When several fields are supplied together they are validated up front and applied atomically: an invalid value rejects the whole request with nothing changed.",
        "parameters": [
          {
            "description": "Connector ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "example": "HydraDoc1234",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/handler.connectorUpdateReq"
              }
            }
          },
          "description": "Connector update request",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.connectorUpdateResponse"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Update a connector",
        "tags": [
          "connectors"
        ],
        "x-fern-sdk-group-name": "connectors",
        "x-fern-sdk-method-name": "update"
      }
    },
    "/connectors/{id}/configure": {
      "post": {
        "description": "Save the selected resources for a connector and trigger initial sync/backfill.",
        "parameters": [
          {
            "description": "Connector ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "example": "HydraDoc1234",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/handler.configureReq"
              }
            }
          },
          "description": "Resource selection and sync options",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.configureResponse"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Configure connector resources",
        "tags": [
          "connectors"
        ],
        "x-fern-sdk-group-name": "connectors",
        "x-fern-sdk-method-name": "configure"
      }
    },
    "/connectors/{id}/credentials": {
      "patch": {
        "description": "Internal endpoint. It is not callable with a customer API key and always returns 403 for external callers. Persists a rotated refresh_token for OAuth-bundle connectors: providers that rotate the refresh token on each exchange invalidate the previously stored one, so the new token must be written back or the next sync fails with invalid_grant. Only refresh_token is merged onto the current stored credential bundle and re-encrypted under the connector's identity context; credentials are never returned. It has no automated caller and is disabled by default: until an operator enables it, every call returns 500.",
        "parameters": [
          {
            "description": "Connector ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "example": "HydraDoc1234",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.credentialsUpdateResponse"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Forbidden"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Service Unavailable"
          }
        },
        "summary": "Rotate a connector's stored OAuth refresh token (internal use only)",
        "tags": [
          "connectors"
        ]
      }
    },
    "/connectors/{id}/discover": {
      "get": {
        "description": "List a connected provider's resources using the connector's stored credentials. Passing cursor or limit opts into pagination (currently Notion only): the response then adds next_cursor and has_more, a page may hold fewer than limit resources, and clients must continue while has_more is true. Without either param the full resource list is returned.",
        "parameters": [
          {
            "description": "Connector ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "example": "HydraDoc1234",
              "type": "string"
            }
          },
          {
            "description": "Opaque pagination cursor from a previous response's next_cursor",
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Max resources per page, 1-100 (values above 100 are clamped)",
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.discoverResponseBody"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          },
          "502": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Gateway"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Service Unavailable"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Discover connector resources",
        "tags": [
          "connectors"
        ],
        "x-fern-sdk-group-name": "connectors",
        "x-fern-sdk-method-name": "discover"
      }
    },
    "/connectors/{id}/pause": {
      "post": {
        "description": "Stop scheduling syncs and backfills for a connector until it is resumed. A sync already running is allowed to finish. Cursors are preserved, so resuming continues from where each resource left off.",
        "parameters": [
          {
            "description": "Connector ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "example": "HydraDoc1234",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.connectorPauseResponse"
                }
              }
            },
            "description": "OK"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Conflict"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Pause a connector",
        "tags": [
          "connectors"
        ],
        "x-fern-sdk-group-name": "connectors",
        "x-fern-sdk-method-name": "pause"
      }
    },
    "/connectors/{id}/resources": {
      "get": {
        "description": "List the configured resources for a connector.",
        "parameters": [
          {
            "description": "Connector ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "example": "HydraDoc1234",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.connectorResourcesResponse"
                }
              }
            },
            "description": "OK"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "List connector resources",
        "tags": [
          "connectors"
        ],
        "x-fern-sdk-group-name": "connectors",
        "x-fern-sdk-method-name": "list_resources"
      },
      "post": {
        "description": "Add a resource mapping to a connector.",
        "parameters": [
          {
            "description": "Connector ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "example": "HydraDoc1234",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/handler.resourceCreateReq"
              }
            }
          },
          "description": "Resource configuration",
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/connectors.Resource"
                }
              }
            },
            "description": "Created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Create a connector resource",
        "tags": [
          "connectors"
        ],
        "x-fern-sdk-group-name": "connectors",
        "x-fern-sdk-method-name": "create_resource"
      }
    },
    "/connectors/{id}/resources/{resource_id}": {
      "delete": {
        "description": "Remove a resource mapping from a connector.",
        "parameters": [
          {
            "description": "Connector ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "example": "HydraDoc1234",
              "type": "string"
            }
          },
          {
            "description": "Resource ID",
            "in": "path",
            "name": "resource_id",
            "required": true,
            "schema": {
              "example": "C0123456789",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.resourceDeleteResponse"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Delete a connector resource",
        "tags": [
          "connectors"
        ],
        "x-fern-sdk-group-name": "connectors",
        "x-fern-sdk-method-name": "delete_resource"
      },
      "patch": {
        "description": "Updates per-resource settings. `acl` sets the customer-declared ACL for one connector resource (PRO-1684): the rule is normalized (emails prefixed, __public__ dominates, explicit-empty becomes __private__), persisted on the resource, and applied to enforcement immediately via the resource's ACL row, every already-indexed document of the resource is governed by it on the next query, with no re-sync. For providers with provider-derived ACL capture enabled, the provider's own ACL takes precedence again at the next sync; the rule is the standing fallback. `custom_instructions` sets the resource-level ingestion-instructions override (max 4000 characters): when set it replaces the connector-level custom_instructions for documents synced from this resource, an explicit empty string clears the override back to inheriting the connector's value, and changes apply from the next sync cycle. At least one field must be supplied; omitted fields are left unchanged.",
        "parameters": [
          {
            "description": "Connector ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "example": "HydraDoc1234",
              "type": "string"
            }
          },
          {
            "description": "Resource ID",
            "in": "path",
            "name": "resource_id",
            "required": true,
            "schema": {
              "example": "C0123456789",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": {},
                  "type": "object"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Update a resource's ACL rule or custom instructions",
        "tags": [
          "connectors"
        ],
        "x-fern-sdk-group-name": "connectors",
        "x-fern-sdk-method-name": "update_resource_acl"
      }
    },
    "/connectors/{id}/resume": {
      "post": {
        "description": "Return a paused connector to the schedule and make it due immediately. Each resource continues from its committed cursor, so data created during the pause is collected on the next cycle rather than skipped.",
        "parameters": [
          {
            "description": "Connector ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "example": "HydraDoc1234",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.connectorPauseResponse"
                }
              }
            },
            "description": "OK"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Conflict"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Resume a paused connector",
        "tags": [
          "connectors"
        ],
        "x-fern-sdk-group-name": "connectors",
        "x-fern-sdk-method-name": "resume"
      }
    },
    "/connectors/{id}/status": {
      "get": {
        "description": "Report whether a connector is working, in one call: a rollup status (healthy, degraded, failed, checking) plus per-resource detail. `degraded` means the connector is scheduled but not fully working: at least one configured resource is failing, or the latest sync cycle failed after the resources reported (in which case `error` carries the failure and `retryable` says whether waiting can fix it). `failed` means only the user can fix it: a rejected credential, a blocked connector, or a terminal cycle failure.",
        "parameters": [
          {
            "description": "Connector ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "example": "HydraDoc1234",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.connectorStatusResponse"
                }
              }
            },
            "description": "OK"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Get a connector's health",
        "tags": [
          "connectors"
        ],
        "x-fern-sdk-group-name": "connectors",
        "x-fern-sdk-method-name": "status"
      }
    },
    "/connectors/{id}/sync": {
      "post": {
        "description": "Start a manual sync workflow for a connector.",
        "parameters": [
          {
            "description": "Connector ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "example": "HydraDoc1234",
              "type": "string"
            }
          }
        ],
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.connectorSyncResponse"
                }
              }
            },
            "description": "Accepted"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Conflict"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Service Unavailable"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Trigger a connector sync",
        "tags": [
          "connectors"
        ],
        "x-fern-sdk-group-name": "connectors",
        "x-fern-sdk-method-name": "sync"
      }
    },
    "/context": {
      "delete": {
        "description": "Delete one or more knowledge sources or memories by ID.\n\nBy default this endpoint answers 200 for every outcome, including a delete\nthat removed nothing — check `data.deleted_count` and `data.results` rather\nthan the status code.\n\nSend `X-HydraDB-Delete-Status: strict` to opt in to honest status codes: a\ndelete that did not happen then answers 404/409/500 and never 200. This is\nthe recommended mode for new integrations. On those failures the response\n`data` still carries the same `results` / `deleted_count` payload a 200\ncarries, so per-id outcomes stay readable either way.\n\nThe default is expected to become strict in a future release, at which\npoint `X-HydraDB-Delete-Status: legacy` keeps the unconditional 200 for a\ncaller that is not ready.",
        "parameters": [
          {
            "description": "Selects the status behaviour for this request. `strict` opts in to honest 404/409/500 codes when the delete did not happen; `legacy` forces the unconditional 200. Omitted, the server default applies — currently `legacy`.",
            "in": "header",
            "name": "X-HydraDB-Delete-Status",
            "schema": {
              "enum": [
                "strict",
                "legacy"
              ],
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/sources.V2SourceDeleteRequest"
              }
            }
          },
          "description": "Delete request",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.Envelope-sources_MemoryDeleteResponse"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorEnvelope-sources_MemoryDeleteResponse"
                }
              }
            },
            "description": "Strict mode only. No source matched the given ids; `data` carries the same results/deleted_count payload a 200 carries"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorEnvelope-sources_MemoryDeleteResponse"
                }
              }
            },
            "description": "Strict mode only. Source is still indexing; retry after ingestion completes (see Retry-After). `data` carries the same results/deleted_count payload a 200 carries"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorEnvelope-sources_MemoryDeleteResponse"
                }
              }
            },
            "description": "Strict mode only. A store failed to delete the source; the delete is retryable. `data` carries the same results/deleted_count payload a 200 carries"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Delete documents or memories",
        "tags": [
          "context"
        ],
        "x-fern-sdk-group-name": "context",
        "x-fern-sdk-method-name": "delete"
      }
    },
    "/context/chunks": {
      "get": {
        "description": "Return the indexed chunk text for a source, or for a specific set of chunk ids (the ids a graph relation cites as its evidence). Chunk rows are read from the document store first and from the vector store for anything it does not hold. Chunks whose source the request's principals may not see are omitted, and so are chunks whose source cannot be established.",
        "parameters": [
          {
            "description": "Database (canonical name for the tenant scope)",
            "in": "query",
            "name": "database",
            "required": true,
            "schema": {
              "example": "acme_corp",
              "type": "string"
            }
          },
          {
            "description": "Collection (canonical name for the sub-tenant scope)",
            "in": "query",
            "name": "collection",
            "schema": {
              "example": "team_docs",
              "type": "string"
            }
          },
          {
            "description": "Deprecated alias for database",
            "in": "query",
            "name": "tenant_id",
            "schema": {
              "deprecated": true,
              "example": "tenant_1234",
              "type": "string",
              "x-deprecated": "true"
            }
          },
          {
            "description": "Deprecated alias for collection",
            "in": "query",
            "name": "sub_tenant_id",
            "schema": {
              "deprecated": true,
              "example": "sub_tenant_4567",
              "type": "string",
              "x-deprecated": "true"
            }
          },
          {
            "description": "Source ID whose chunks to return. Required unless chunk_ids is given.",
            "in": "query",
            "name": "id",
            "schema": {
              "example": "HydraDoc1234",
              "type": "string"
            }
          },
          {
            "description": "Chunk IDs to return. Repeated (chunk_ids=a\u0026chunk_ids=b) or comma-separated. Takes precedence over id.",
            "in": "query",
            "name": "chunk_ids",
            "schema": {
              "example": [
                "HydraEmbeddings123_0",
                "HydraEmbeddings123_1"
              ],
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "style": "form"
          },
          {
            "description": "Corpus type: 'knowledge' (default), 'memory', or 'all'. This read addresses one corpus, so 'all' answers from knowledge and meta.source_type reports which corpus answered.",
            "in": "query",
            "name": "type",
            "schema": {
              "enum": [
                "knowledge",
                "memory",
                "all"
              ],
              "type": "string"
            }
          },
          {
            "description": "Max chunks to return",
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 50,
              "type": "integer"
            }
          },
          {
            "description": "Principals to answer as (PRO-1684 document ACLs): only chunks whose source they may see are returned. Repeated (acl=a\u0026acl=b) or comma-separated. Omit for no ACL scoping.",
            "in": "query",
            "name": "acl",
            "schema": {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "style": "form"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.Envelope-search_ChunkInspectResult"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Get chunk text",
        "tags": [
          "context"
        ],
        "x-fern-sdk-group-name": "context",
        "x-fern-sdk-method-name": "chunks"
      }
    },
    "/context/ingest": {
      "post": {
        "description": "Ingest content for a database. `items` is the preferred shape (text or a conversation per item); the deprecated `documents`, `app_knowledge` and `memories` fields are selected by `type`. The same `items` array may also be sent as an application/json body.",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "properties": {
                  "app_knowledge": {
                    "deprecated": true,
                    "description": "App-knowledge items as a JSON array (type=knowledge). Per item, `metadata` is capped at 16 KiB and `additional_metadata` at 1 KiB, measured on the compact JSON encoding of the whole map in UTF-8 bytes (keys and punctuation count). The deprecated `tenant_metadata` / `document_metadata` spellings are accepted here and held to the same caps. Over-cap returns 400 with the actual byte count. Each item may also carry `acl`, a list of principals (`user_email:\u003cemail\u003e`, a bare email, `group:\u003cprovider\u003e:\u003cid\u003e`, `domain:\u003cdomain\u003e`, or `__public__`) restricting who may retrieve it; omit it to leave the document unrestricted, and send an empty list to restrict it to nobody. A malformed principal rejects the whole request with 400. Items may also carry `evidence_kind`/`evidence_subject` provenance labels (see document_metadata); an unknown kind returns 400.",
                    "title": "app_knowledge",
                    "type": "string",
                    "x-deprecated": "true"
                  },
                  "collection": {
                    "title": "collection",
                    "type": "string"
                  },
                  "database": {
                    "title": "database",
                    "type": "string"
                  },
                  "document_metadata": {
                    "deprecated": true,
                    "description": "Per-document metadata as a JSON array (type=knowledge). Per item, `metadata` is capped at 16 KiB and `additional_metadata` at 1 KiB. Both caps are measured on the compact JSON encoding of the whole map in UTF-8 bytes, so keys, quotes, commas and braces count toward the budget. Over-cap returns 400 with the actual byte count. Each item may also carry evidence labels (`evidence_kind`: one of assertion, record, said, done, third_party, inferred; `evidence_subject`: a stable handle for who the evidence is about, e.g. `user:kiran@acme.com`) declaring the content's provenance for entity understanding; an unknown kind returns 400.",
                    "title": "document_metadata",
                    "type": "string",
                    "x-deprecated": "true"
                  },
                  "documents": {
                    "deprecated": true,
                    "items": {
                      "format": "binary",
                      "type": "string"
                    },
                    "title": "documents",
                    "type": "array",
                    "x-deprecated": "true"
                  },
                  "graph_payload": {
                    "title": "graph_payload",
                    "type": "string"
                  },
                  "items": {
                    "description": "JSON-encoded array of ingest items -- text or a conversation per item. The same array may also be POSTed as an application/json body; that variant is not listed here so SDK generators emit this form, which carries every field.",
                    "title": "items",
                    "type": "string"
                  },
                  "memories": {
                    "deprecated": true,
                    "description": "Memory items as a JSON array (type=memory). Per item, `metadata` is capped at 16 KiB and `additional_metadata` at 1 KiB, measured on the compact JSON encoding of the whole map in UTF-8 bytes (keys and punctuation count). Over-cap returns 400 with the actual byte count. Items may also carry `evidence_kind`/`evidence_subject` provenance labels (see document_metadata); an unknown kind returns 400.",
                    "title": "memories",
                    "type": "string",
                    "x-deprecated": "true"
                  },
                  "sub_tenant_id": {
                    "deprecated": true,
                    "title": "sub_tenant_id",
                    "type": "string",
                    "x-deprecated": "true"
                  },
                  "tenant_id": {
                    "deprecated": true,
                    "title": "tenant_id",
                    "type": "string",
                    "x-deprecated": "true"
                  },
                  "type": {
                    "enum": [
                      "knowledge",
                      "memory"
                    ],
                    "title": "type",
                    "type": "string"
                  },
                  "upsert": {
                    "default": "true",
                    "title": "upsert",
                    "type": "string"
                  }
                },
                "required": [
                  "database"
                ],
                "type": "object"
              }
            }
          },
          "description": "Items[] body: the application/json alternative to this form. | Corpus to write to: 'knowledge' (default) or 'memory'. 'all' is refused here: an ingest must name the one corpus it writes to. | Items as a JSON array; each item carries `text` or `conversation` (role/content turns), optional `context_id`, `title`, `attributes`, `custom_attributes`, `happened_at`, `enrich`, `context_category` (auto|user_preference|business_knowledge|decision_trace), and `acl` (principal list, PRO-1684: same contract as an app_knowledge item; omit for unrestricted). Items land in the memory corpus. | Database (canonical name for the tenant scope) | Collection (canonical name for the sub-tenant scope) | Deprecated alias for database | Deprecated alias for collection | Upsert existing content (true/false/1/0) | Deprecated: knowledge files to ingest (repeatable; type=knowledge, split databases only) | Deprecated: per-document metadata as a JSON array (type=knowledge, split databases only). Per item: metadata \u003c= 16 KiB, additional_metadata \u003c= 1 KiB. | Deprecated: app-knowledge items as a JSON array (type=knowledge, split databases only). Per item: metadata \u003c= 16 KiB, additional_metadata \u003c= 1 KiB, optional acl principal list (PRO-1684). | Deprecated: memory items as a JSON array (type=memory, split databases only); use items. Per item: metadata \u003c= 16 KiB, additional_metadata \u003c= 1 KiB. | Optional bring-your-own-graph payload as JSON",
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.Envelope-ingestion_V2IngestResponse"
                }
              }
            },
            "description": "Accepted"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "413": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Request Entity Too Large"
          },
          "415": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Body is neither multipart/form-data nor application/json"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Unprocessable Entity"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Ingest content",
        "tags": [
          "context"
        ],
        "x-fern-sdk-group-name": "context",
        "x-fern-sdk-method-name": "ingest"
      }
    },
    "/context/inspect": {
      "get": {
        "description": "Fetch a previously ingested source's content, inferred content, and a downloadable URL.",
        "parameters": [
          {
            "description": "Source ID",
            "in": "query",
            "name": "id",
            "required": true,
            "schema": {
              "example": "HydraDoc1234",
              "type": "string"
            }
          },
          {
            "description": "Database (canonical name for the tenant scope)",
            "in": "query",
            "name": "database",
            "required": true,
            "schema": {
              "example": "acme_corp",
              "type": "string"
            }
          },
          {
            "description": "Collection (canonical name for the sub-tenant scope)",
            "in": "query",
            "name": "collection",
            "schema": {
              "example": "team_docs",
              "type": "string"
            }
          },
          {
            "description": "Deprecated alias for database",
            "in": "query",
            "name": "tenant_id",
            "schema": {
              "deprecated": true,
              "example": "tenant_1234",
              "type": "string",
              "x-deprecated": "true"
            }
          },
          {
            "description": "Deprecated alias for collection",
            "in": "query",
            "name": "sub_tenant_id",
            "schema": {
              "deprecated": true,
              "example": "sub_tenant_4567",
              "type": "string",
              "x-deprecated": "true"
            }
          },
          {
            "description": "Presigned URL expiry in seconds",
            "in": "query",
            "name": "expiry_seconds",
            "schema": {
              "default": 3600,
              "type": "integer"
            }
          },
          {
            "description": "Fetch mode",
            "in": "query",
            "name": "mode",
            "schema": {
              "example": "thinking",
              "type": "string"
            }
          },
          {
            "description": "Principals to answer as (PRO-1684 document ACLs): the source must be visible to them, or the response is 404. Repeated (acl=a\u0026acl=b) or comma-separated. Omit for no ACL scoping.",
            "in": "query",
            "name": "acl",
            "schema": {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "style": "form"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.Envelope-fetch_V2SourceFetchResponse"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Fetch document content",
        "tags": [
          "context"
        ],
        "x-fern-sdk-group-name": "context",
        "x-fern-sdk-method-name": "inspect"
      }
    },
    "/context/list": {
      "post": {
        "description": "List items (id + metadata) for a database: knowledge sources (default) or memories, selected by `type`.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/list.V2ListContentRequest"
              }
            }
          },
          "description": "List request",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.Envelope-list_V2ListResponse"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "List documents",
        "tags": [
          "context"
        ],
        "x-fern-sdk-group-name": "context",
        "x-fern-sdk-method-name": "list"
      }
    },
    "/context/profile": {
      "get": {
        "description": "Return the compiled profile of one entity in one collection: identity headline, a cited summary, and the current admitted entries (each pointing at the statements behind it). Profiles are maintained continuously by the ingestion pipeline's entity keeper; this endpoint reads the materialized view and never triggers recomputation.",
        "parameters": [
          {
            "description": "Database (canonical name for the tenant scope)",
            "in": "query",
            "name": "database",
            "required": true,
            "schema": {
              "example": "acme_corp",
              "type": "string"
            }
          },
          {
            "description": "Collection (canonical name for the sub-tenant scope)",
            "in": "query",
            "name": "collection",
            "required": true,
            "schema": {
              "example": "team_docs",
              "type": "string"
            }
          },
          {
            "description": "Deprecated alias for database",
            "in": "query",
            "name": "tenant_id",
            "schema": {
              "deprecated": true,
              "example": "tenant_1234",
              "type": "string",
              "x-deprecated": "true"
            }
          },
          {
            "description": "Deprecated alias for collection",
            "in": "query",
            "name": "sub_tenant_id",
            "schema": {
              "deprecated": true,
              "example": "sub_tenant_4567",
              "type": "string",
              "x-deprecated": "true"
            }
          },
          {
            "description": "Entity whose profile to return (e.g. a person's name)",
            "in": "query",
            "name": "subject",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Corpus type: 'knowledge' or 'memory'",
            "in": "query",
            "name": "type",
            "schema": {
              "default": "memory",
              "enum": [
                "knowledge",
                "memory"
              ],
              "type": "string"
            }
          },
          {
            "description": "Graph entity type of the subject",
            "in": "query",
            "name": "entity_type",
            "schema": {
              "default": "PERSON",
              "type": "string"
            }
          },
          {
            "description": "Graph namespace of the subject",
            "in": "query",
            "name": "namespace",
            "schema": {
              "default": "users",
              "example": "organization",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.Envelope-search_EntityProfileView"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "No profile compiled for this subject yet, or the feature is not enabled"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Get entity profile",
        "tags": [
          "context"
        ],
        "x-fern-sdk-group-name": "context",
        "x-fern-sdk-method-name": "profile"
      }
    },
    "/context/relations": {
      "get": {
        "description": "Return knowledge-graph relations for a tenant or a single source.",
        "parameters": [
          {
            "description": "Database (canonical name for the tenant scope)",
            "in": "query",
            "name": "database",
            "required": true,
            "schema": {
              "example": "acme_corp",
              "type": "string"
            }
          },
          {
            "description": "Collection (canonical name for the sub-tenant scope)",
            "in": "query",
            "name": "collection",
            "schema": {
              "example": "team_docs",
              "type": "string"
            }
          },
          {
            "description": "Deprecated alias for database",
            "in": "query",
            "name": "tenant_id",
            "schema": {
              "deprecated": true,
              "example": "tenant_1234",
              "type": "string",
              "x-deprecated": "true"
            }
          },
          {
            "description": "Deprecated alias for collection",
            "in": "query",
            "name": "sub_tenant_id",
            "schema": {
              "deprecated": true,
              "example": "sub_tenant_4567",
              "type": "string",
              "x-deprecated": "true"
            }
          },
          {
            "description": "Source ID (omit for database-wide relations)",
            "in": "query",
            "name": "id",
            "schema": {
              "example": "HydraDoc1234",
              "type": "string"
            }
          },
          {
            "description": "Corpus type: 'knowledge' (default), 'memory', or 'all'. This read addresses one corpus, so 'all' answers from knowledge and meta.source_type reports which corpus answered.",
            "in": "query",
            "name": "type",
            "schema": {
              "enum": [
                "knowledge",
                "memory",
                "all"
              ],
              "type": "string"
            }
          },
          {
            "description": "Max relations to return",
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 5000,
              "type": "integer"
            }
          },
          {
            "description": "Pagination cursor",
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "number"
            }
          },
          {
            "description": "Principals to answer as (PRO-1684 document ACLs): only relations attributable to sources they may see are returned. Repeated (acl=a\u0026acl=b) or comma-separated. Omit for no ACL scoping.",
            "in": "query",
            "name": "acl",
            "schema": {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "style": "form"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.Envelope-graph_GraphRelationsResponse"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Get graph relations",
        "tags": [
          "context"
        ],
        "x-fern-sdk-group-name": "context",
        "x-fern-sdk-method-name": "relations"
      }
    },
    "/context/status": {
      "get": {
        "description": "Return the processing status for one or more source IDs.",
        "parameters": [
          {
            "description": "Single source ID",
            "in": "query",
            "name": "id",
            "schema": {
              "example": "HydraDoc1234",
              "type": "string"
            }
          },
          {
            "description": "One or more source IDs",
            "in": "query",
            "name": "ids",
            "schema": {
              "example": [
                "HydraDoc1234",
                "HydraDoc4567"
              ],
              "items": {
                "type": "string"
              },
              "type": "array"
            }
          },
          {
            "description": "Database (canonical name for the tenant scope)",
            "in": "query",
            "name": "database",
            "required": true,
            "schema": {
              "example": "acme_corp",
              "type": "string"
            }
          },
          {
            "description": "Collection (canonical name for the sub-tenant scope)",
            "in": "query",
            "name": "collection",
            "schema": {
              "example": "team_docs",
              "type": "string"
            }
          },
          {
            "description": "Deprecated alias for database",
            "in": "query",
            "name": "tenant_id",
            "schema": {
              "deprecated": true,
              "example": "tenant_1234",
              "type": "string",
              "x-deprecated": "true"
            }
          },
          {
            "description": "Deprecated alias for collection",
            "in": "query",
            "name": "sub_tenant_id",
            "schema": {
              "deprecated": true,
              "example": "sub_tenant_4567",
              "type": "string",
              "x-deprecated": "true"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.Envelope-ingestion_V2BatchProcessingStatus"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Check processing status",
        "tags": [
          "context"
        ],
        "x-fern-sdk-group-name": "context",
        "x-fern-sdk-method-name": "status"
      }
    },
    "/context/subgraph": {
      "get": {
        "description": "Query-string form of GET /context/{id}/subgraph: the same parameters, the same response, and the same rules. It exists for an id that contains '/', which cannot be spelled as one path segment; generated SDKs call this form for every id. Return the connected subgraph of one ingested item: every item reachable from it through item-level relations (explicit `relates_to` links, a shared thread, parent/child hierarchy, traversed breadth-first up to `depth` hops), the relations among those members, and the structural graph around them (entities, comments, attachments, actors). Chunk-level entity relations are not included; use Inspecting Context Relations for those. An unknown id returns an empty subgraph, not an error.",
        "parameters": [
          {
            "description": "Item ID: the ingested item whose connected subgraph to return. This form takes any id, including one that contains '/'.",
            "in": "query",
            "name": "id",
            "required": true,
            "schema": {
              "example": "HydraDoc1234",
              "type": "string"
            }
          },
          {
            "description": "Database (canonical name for the tenant scope)",
            "in": "query",
            "name": "database",
            "required": true,
            "schema": {
              "example": "acme_corp",
              "type": "string"
            }
          },
          {
            "description": "Collection (canonical name for the sub-tenant scope)",
            "in": "query",
            "name": "collection",
            "schema": {
              "example": "team_docs",
              "type": "string"
            }
          },
          {
            "description": "Deprecated alias for database",
            "in": "query",
            "name": "tenant_id",
            "schema": {
              "deprecated": true,
              "example": "tenant_1234",
              "type": "string",
              "x-deprecated": "true"
            }
          },
          {
            "description": "Deprecated alias for collection",
            "in": "query",
            "name": "sub_tenant_id",
            "schema": {
              "deprecated": true,
              "example": "sub_tenant_4567",
              "type": "string",
              "x-deprecated": "true"
            }
          },
          {
            "description": "Corpus type: 'knowledge' (default), 'memory', or 'all'. This read addresses one corpus, so 'all' answers from knowledge and meta.source_type reports which corpus answered.",
            "in": "query",
            "name": "type",
            "schema": {
              "enum": [
                "knowledge",
                "memory",
                "all"
              ],
              "type": "string"
            }
          },
          {
            "description": "Max traversal depth in hops",
            "in": "query",
            "name": "depth",
            "schema": {
              "default": 5,
              "maximum": 10,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "Max members returned; `is_truncated` reports when this clipped the traversal",
            "in": "query",
            "name": "max_sources",
            "schema": {
              "default": 200,
              "maximum": 1000,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "Principals to answer as (document ACLs): the subgraph contains only items they may see, filtered at every hop. Repeated (acl=a\u0026acl=b) or comma-separated. Omit for no ACL scoping.",
            "in": "query",
            "name": "acl",
            "schema": {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "style": "form"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.Envelope-graph_SourceSubgraphResponse"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Get connected subgraph",
        "tags": [
          "context"
        ],
        "x-fern-sdk-group-name": "context",
        "x-fern-sdk-method-name": "subgraph"
      }
    },
    "/context/{id}/metadata": {
      "patch": {
        "description": "Merge/upsert database_metadata and additional_metadata for one source. collection is required.",
        "parameters": [
          {
            "description": "Source ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "example": "HydraDoc1234",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/handler.contextMetadataUpdateRequest"
              }
            }
          },
          "description": "Metadata update request",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.Envelope-github_com_hydradb_hydradb-application_internal_service_MetadataEditResult"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Update source metadata",
        "tags": [
          "context"
        ],
        "x-fern-sdk-group-name": "context"
      }
    },
    "/context/{id}/subgraph": {
      "get": {
        "description": "Return the connected subgraph of one ingested item: every item reachable from it through item-level relations (explicit `relates_to` links, a shared thread, parent/child hierarchy, traversed breadth-first up to `depth` hops), the relations among those members, and the structural graph around them (entities, comments, attachments, actors). Chunk-level entity relations are not included; use Inspecting Context Relations for those. An unknown id returns an empty subgraph, not an error.",
        "parameters": [
          {
            "description": "Item ID: the ingested item whose connected subgraph to return. URL-encode it. An id containing a literal '/' cannot be spelled as one path segment; address those with the query form, GET /context/subgraph?id=.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "example": "HydraDoc1234",
              "type": "string"
            }
          },
          {
            "description": "Database (canonical name for the tenant scope)",
            "in": "query",
            "name": "database",
            "required": true,
            "schema": {
              "example": "acme_corp",
              "type": "string"
            }
          },
          {
            "description": "Collection (canonical name for the sub-tenant scope)",
            "in": "query",
            "name": "collection",
            "schema": {
              "example": "team_docs",
              "type": "string"
            }
          },
          {
            "description": "Deprecated alias for database",
            "in": "query",
            "name": "tenant_id",
            "schema": {
              "deprecated": true,
              "example": "tenant_1234",
              "type": "string",
              "x-deprecated": "true"
            }
          },
          {
            "description": "Deprecated alias for collection",
            "in": "query",
            "name": "sub_tenant_id",
            "schema": {
              "deprecated": true,
              "example": "sub_tenant_4567",
              "type": "string",
              "x-deprecated": "true"
            }
          },
          {
            "description": "Corpus type: 'knowledge' (default), 'memory', or 'all'. This read addresses one corpus, so 'all' answers from knowledge and meta.source_type reports which corpus answered.",
            "in": "query",
            "name": "type",
            "schema": {
              "enum": [
                "knowledge",
                "memory",
                "all"
              ],
              "type": "string"
            }
          },
          {
            "description": "Max traversal depth in hops",
            "in": "query",
            "name": "depth",
            "schema": {
              "default": 5,
              "maximum": 10,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "Max members returned; `is_truncated` reports when this clipped the traversal",
            "in": "query",
            "name": "max_sources",
            "schema": {
              "default": 200,
              "maximum": 1000,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "Principals to answer as (document ACLs): the subgraph contains only items they may see, filtered at every hop. Repeated (acl=a\u0026acl=b) or comma-separated. Omit for no ACL scoping.",
            "in": "query",
            "name": "acl",
            "schema": {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "style": "form"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.Envelope-graph_SourceSubgraphResponse"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Get connected subgraph",
        "tags": [
          "context"
        ],
        "x-fern-ignore": true
      }
    },
    "/credential-vault": {
      "get": {
        "description": "List metadata and field names for credentials already used by connectors in the current workspace.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.vaultCredentialListResponse"
                }
              }
            },
            "description": "OK"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "List connector credentials",
        "tags": [
          "connectors"
        ]
      }
    },
    "/credential-vault/{id}": {
      "patch": {
        "description": "Update fields on the credential currently used by a connector. Owner-only human action.",
        "parameters": [
          {
            "description": "Connector ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "example": "HydraDoc1234",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/handler.vaultCredentialUpdateReq"
              }
            }
          },
          "description": "Credential fields",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.vaultCredentialUpdateResponse"
                }
              }
            },
            "description": "OK"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Update connector credentials",
        "tags": [
          "connectors"
        ]
      }
    },
    "/credential-vault/{id}/reveal": {
      "post": {
        "description": "Reveal one field from the credential currently used by a connector in the workspace. The response must never be cached.",
        "parameters": [
          {
            "description": "Connector ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "example": "HydraDoc1234",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/handler.vaultCredentialRevealReq"
              }
            }
          },
          "description": "Credential field",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.vaultCredentialRevealResponse"
                }
              }
            },
            "description": "OK"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Reveal a connector credential value",
        "tags": [
          "connectors"
        ]
      }
    },
    "/databases": {
      "delete": {
        "description": "Delete a database and all associated data",
        "parameters": [
          {
            "description": "Database identifier to delete",
            "in": "query",
            "name": "database",
            "required": true,
            "schema": {
              "example": "acme_corp",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.Envelope-tenants_TenantDeleteResponse"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Delete a database",
        "tags": [
          "database-management"
        ],
        "x-fern-sdk-group-name": "databases",
        "x-fern-sdk-method-name": "delete"
      },
      "get": {
        "description": "List all databases for the authenticated user",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.Envelope-tenants_TenantIdsResponse"
                }
              }
            },
            "description": "OK"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "List databases",
        "tags": [
          "database-management"
        ],
        "x-fern-sdk-group-name": "databases",
        "x-fern-sdk-method-name": "list"
      },
      "post": {
        "description": "Create a new database with optional custom metadata schema",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/tenants.TenantCreateRequest"
              }
            }
          },
          "description": "Database creation request",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.Envelope-tenants_TenantCreateAcceptedResponse"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Forbidden"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Conflict"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Create a database",
        "tags": [
          "database-management"
        ],
        "x-fern-sdk-group-name": "databases",
        "x-fern-sdk-method-name": "create"
      }
    },
    "/databases/collections": {
      "delete": {
        "description": "Permanently remove one collection and all of its data from a database. The database itself is left intact.",
        "parameters": [
          {
            "description": "Database identifier",
            "in": "query",
            "name": "database",
            "required": true,
            "schema": {
              "example": "acme_corp",
              "type": "string"
            }
          },
          {
            "description": "Collection identifier",
            "in": "query",
            "name": "collection",
            "required": true,
            "schema": {
              "example": "team_docs",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.Envelope-tenants_SubTenantDeleteResponse"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Delete a collection",
        "tags": [
          "database-management"
        ],
        "x-fern-sdk-group-name": "databases",
        "x-fern-sdk-method-name": "deleteCollection"
      },
      "get": {
        "description": "List all collections for a given database",
        "parameters": [
          {
            "description": "Database identifier",
            "in": "query",
            "name": "database",
            "required": true,
            "schema": {
              "example": "acme_corp",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.Envelope-tenants_SubTenantIdsResponse"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "List collections",
        "tags": [
          "database-management"
        ],
        "x-fern-sdk-group-name": "databases",
        "x-fern-sdk-method-name": "collections"
      }
    },
    "/databases/stats": {
      "get": {
        "description": "Get collection statistics for a database",
        "parameters": [
          {
            "description": "Database identifier",
            "in": "query",
            "name": "database",
            "required": true,
            "schema": {
              "example": "acme_corp",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.Envelope-tenants_TenantStatsResponse"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Get database statistics",
        "tags": [
          "database-management"
        ],
        "x-fern-sdk-group-name": "databases",
        "x-fern-sdk-method-name": "stats"
      }
    },
    "/databases/status": {
      "get": {
        "description": "Check the infrastructure provisioning status for a database",
        "parameters": [
          {
            "description": "Database identifier",
            "in": "query",
            "name": "database",
            "required": true,
            "schema": {
              "example": "acme_corp",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.Envelope-tenants_InfraStatusResponseV2"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Get infrastructure status",
        "tags": [
          "database-management"
        ],
        "x-fern-sdk-group-name": "databases",
        "x-fern-sdk-method-name": "status"
      }
    },
    "/databases/{database}": {
      "patch": {
        "description": "Rename a database in place. The internal identity (and therefore all indexed data, graphs and documents) is unchanged — only the caller-facing name moves, atomically. Connectors syncing into the database are repointed at the new name. The old name stops resolving immediately, so callers must switch to the new name in the same rollout.",
        "parameters": [
          {
            "description": "Current database identifier",
            "in": "path",
            "name": "database",
            "required": true,
            "schema": {
              "example": "acme_corp",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/tenants.TenantRenameRequest"
              }
            }
          },
          "description": "New database name",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.Envelope-tenants_TenantRenameResponse"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Conflict"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Rename a database",
        "tags": [
          "database-management"
        ],
        "x-fern-sdk-group-name": "databases",
        "x-fern-sdk-method-name": "rename"
      }
    },
    "/databases/{database}/instructions": {
      "get": {
        "description": "Read the custom ingestion instructions configured for a database and for its collections.",
        "parameters": [
          {
            "description": "Database identifier",
            "in": "path",
            "name": "database",
            "required": true,
            "schema": {
              "example": "acme_corp",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.instructionsResponse"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Get ingestion instructions",
        "tags": [
          "database-management"
        ],
        "x-fern-sdk-group-name": "databases",
        "x-fern-sdk-method-name": "get_instructions"
      },
      "patch": {
        "description": "Set or clear the custom ingestion instructions for a database and its collections. Database instructions apply to every document; a collection's instructions apply on top of them. Both stack with any connector- or resource-level instructions rather than replacing them. Applies from the next ingestion; already-indexed data is not reprocessed.",
        "parameters": [
          {
            "description": "Database identifier",
            "in": "path",
            "name": "database",
            "required": true,
            "schema": {
              "example": "acme_corp",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/handler.instructionsUpdateReq"
              }
            }
          },
          "description": "Instructions to set or clear",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.instructionsResponse"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Update ingestion instructions",
        "tags": [
          "database-management"
        ],
        "x-fern-sdk-group-name": "databases",
        "x-fern-sdk-method-name": "update_instructions"
      }
    },
    "/databases/{database}/metadata-schema": {
      "get": {
        "description": "Read the database's declared metadata schema fields. Returns the same field shape accepted by database creation and by Update Metadata Schema, so the response round-trips into add_fields.",
        "parameters": [
          {
            "description": "Database identifier",
            "in": "path",
            "name": "database",
            "required": true,
            "schema": {
              "example": "acme_corp",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.Envelope-tenants_TenantMetadataSchemaResponse"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Get metadata schema",
        "tags": [
          "database-management"
        ],
        "x-fern-sdk-group-name": "databases",
        "x-fern-sdk-method-name": "get_metadata_schema"
      },
      "patch": {
        "description": "Add new metadata schema fields to an existing database. Additive only — existing fields cannot be deleted or retyped.",
        "parameters": [
          {
            "description": "Database identifier",
            "in": "path",
            "name": "database",
            "required": true,
            "schema": {
              "example": "acme_corp",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/tenants.TenantMetadataSchemaUpdateRequest"
              }
            }
          },
          "description": "Metadata schema fields to add",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.metadataSchemaUpdateResponse"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Conflict"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Update metadata schema",
        "tags": [
          "database-management"
        ],
        "x-fern-sdk-group-name": "databases",
        "x-fern-sdk-method-name": "update_metadata_schema"
      }
    },
    "/feedback": {
      "post": {
        "description": "Record feedback about a query that already ran, correlated by the `request_id` returned in that query's `response.meta.request_id`. Accepts a free-text comment plus an optional positive/negative/neutral rating, and is intended for both end users and agents (`source`). Feeds internal retrieval-quality validation; it does not change the result of the original query.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/feedback.SubmitRequest"
              }
            }
          },
          "description": "Feedback submission",
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.Envelope-feedback_SubmitResponse"
                }
              }
            },
            "description": "Created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Submit feedback for a query",
        "tags": [
          "feedback"
        ],
        "x-fern-sdk-group-name": "feedback",
        "x-fern-sdk-method-name": "submit"
      }
    },
    "/query": {
      "post": {
        "description": "Unified query endpoint that dispatches across type and query_by (hybrid/text). Optionally filter by one or more exact document titles with `titles`; these are resolved to source IDs before normal retrieval. Filter with `attributes` (an operator language, pushed into the vector search); `metadata_filters` is deprecated in favour of it and still works. `type` is knowledge (the default), memory, or all (both, merged). Prefer sub_tenant_ids for sub-tenant scoping; legacy sub_tenant_id is deprecated for /query and cannot be sent together with sub_tenant_ids.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/search.QueryRequest"
              }
            }
          },
          "description": "Unified query request",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.Envelope-search_V2RetrievalResult"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Unified query",
        "tags": [
          "query"
        ],
        "x-fern-sdk-method-name": "query"
      }
    },
    "/webhooks/indexing": {
      "delete": {
        "description": "Unregister the indexing webhook for this API key.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.Envelope-webhooks_WebhookDeleteResponse"
                }
              }
            },
            "description": "OK"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Delete the registered webhook for this API key",
        "tags": [
          "webhooks"
        ],
        "x-fern-sdk-group-name": "webhooks",
        "x-fern-sdk-method-name": "delete"
      },
      "get": {
        "description": "Get the registered indexing webhook configuration for this API key.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.Envelope-webhooks_WebhookGetResponse"
                }
              }
            },
            "description": "OK"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Get the registered webhook for this API key",
        "tags": [
          "webhooks"
        ],
        "x-fern-sdk-group-name": "webhooks",
        "x-fern-sdk-method-name": "get"
      },
      "post": {
        "description": "Register the indexing webhook for this API key's org. Set `generate_signing_secret` to register and enable signing in one request; the secret is returned once on the response. Omitting `signing_secret` preserves any secret already configured - to disable signing, call DELETE /webhooks/indexing/signing-secret.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/webhooks.WebhookRegisterRequest"
              }
            }
          },
          "description": "Webhook registration request",
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.Envelope-webhooks_WebhookRegisterResponse"
                }
              }
            },
            "description": "Created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Register a webhook",
        "tags": [
          "webhooks"
        ],
        "x-fern-sdk-group-name": "webhooks",
        "x-fern-sdk-method-name": "register"
      }
    },
    "/webhooks/indexing/deliveries": {
      "get": {
        "description": "List recent webhook delivery attempts with optional cursor-based pagination.",
        "parameters": [
          {
            "description": "Max deliveries to return",
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer"
            }
          },
          {
            "description": "Pagination cursor",
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Filter by delivery status",
            "in": "query",
            "name": "status",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.Envelope-webhooks_DeliveryListResponse"
                }
              }
            },
            "description": "OK"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "List recent webhook delivery attempts",
        "tags": [
          "webhooks"
        ],
        "x-fern-sdk-group-name": "webhooks",
        "x-fern-sdk-method-name": "list_deliveries"
      }
    },
    "/webhooks/indexing/deliveries/{delivery_id}": {
      "get": {
        "description": "Get a single webhook delivery attempt by ID.",
        "parameters": [
          {
            "description": "Delivery ID",
            "in": "path",
            "name": "delivery_id",
            "required": true,
            "schema": {
              "example": "dlv_9f8e7d6c",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.Envelope-webhooks_DeliveryItem"
                }
              }
            },
            "description": "OK"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Get a single webhook delivery attempt",
        "tags": [
          "webhooks"
        ],
        "x-fern-sdk-group-name": "webhooks",
        "x-fern-sdk-method-name": "get_delivery"
      }
    },
    "/webhooks/indexing/deliveries/{delivery_id}/retry": {
      "post": {
        "description": "Queue a failed or permanently-failed delivery for retry.",
        "parameters": [
          {
            "description": "Delivery ID",
            "in": "path",
            "name": "delivery_id",
            "required": true,
            "schema": {
              "example": "dlv_9f8e7d6c",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.Envelope-webhooks_RetryResponse"
                }
              }
            },
            "description": "OK"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Retry a failed or permanently failed delivery",
        "tags": [
          "webhooks"
        ],
        "x-fern-sdk-group-name": "webhooks",
        "x-fern-sdk-method-name": "retry_delivery"
      }
    },
    "/webhooks/indexing/signing-secret": {
      "delete": {
        "description": "Removes the stored signing secret. Deliveries stop carrying the X-HydraDB-Signature header. This is the only way to disable signing - editing a registration never clears the secret.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.Envelope-webhooks_WebhookRegisterResponse"
                }
              }
            },
            "description": "OK"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Disable webhook signing",
        "tags": [
          "webhooks"
        ],
        "x-fern-sdk-group-name": "webhooks",
        "x-fern-sdk-method-name": "clearSigningSecret"
      },
      "post": {
        "description": "Generates a signing secret, or stores one you supply. The plaintext is returned exactly once and cannot be retrieved afterwards. Takes effect immediately, so rotate only once your receiver accepts the new secret.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/webhooks.SigningSecretRequest"
              }
            }
          },
          "description": "Omit the body to have a secret generated for you"
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.Envelope-webhooks_SigningSecretResponse"
                }
              }
            },
            "description": "OK"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Unprocessable Entity"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Generate or set the webhook signing secret",
        "tags": [
          "webhooks"
        ],
        "x-fern-sdk-group-name": "webhooks",
        "x-fern-sdk-method-name": "setSigningSecret"
      }
    },
    "/webhooks/indexing/test": {
      "post": {
        "description": "Send a test webhook event to the registered endpoint to verify connectivity.",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.Envelope-webhooks_WebhookTestResponse"
                }
              }
            },
            "description": "OK"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Send a test webhook delivery",
        "tags": [
          "webhooks"
        ],
        "x-fern-sdk-group-name": "webhooks",
        "x-fern-sdk-method-name": "test"
      }
    },
    "/webhooks/supabase": {
      "post": {
        "description": "Ingest a Supabase INSERT/UPDATE/DELETE row change into the graph.",
        "parameters": [
          {
            "description": "Connector id",
            "in": "header",
            "name": "X-HydraDB-Connector",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            },
            "text/plain": {
              "schema": {
                "title": "request",
                "type": "object"
              }
            }
          },
          "description": "Supabase Database Webhook payload",
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.Envelope-handler_supabaseWebhookAck"
                }
              }
            },
            "description": "Accepted"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Bad Request"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/handler.ErrorResponse"
                }
              }
            },
            "description": "Not Found"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "summary": "Supabase row-change webhook",
        "tags": [
          "webhooks"
        ]
      }
    }
  },
  "servers": [
    {
      "description": "Production server",
      "url": "https://api.hydradb.com"
    }
  ],
  "x-fern-global-headers": [
    {
      "header": "API-Version",
      "name": "api_version",
      "x-fern-default": "2"
    }
  ]
}