{
  "components": {
    "schemas": {
      "AliasTargetsBody": {
        "properties": {
          "alias_keys": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "user_id": {
            "type": "string"
          }
        },
        "required": [
          "user_id",
          "alias_keys"
        ],
        "type": "object"
      },
      "AliasView": {
        "properties": {
          "alias": {
            "type": "string"
          },
          "aliasId": {
            "type": "string"
          },
          "aliasKey": {
            "type": "string"
          },
          "createdAt": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "entityId": {
            "type": "string"
          },
          "normalizedAlias": {
            "type": "string"
          }
        },
        "required": [
          "aliasId",
          "aliasKey",
          "alias",
          "normalizedAlias",
          "entityId"
        ],
        "type": "object"
      },
      "CleanupBody": {
        "properties": {
          "batch_size": {
            "format": "int64",
            "type": "integer"
          }
        },
        "required": [
          "batch_size"
        ],
        "type": "object"
      },
      "ContactEmailBody": {
        "properties": {
          "contact_email": {
            "type": "string"
          },
          "user_id": {
            "type": "string"
          }
        },
        "required": [
          "user_id",
          "contact_email"
        ],
        "type": "object"
      },
      "CreateAliasRow": {
        "properties": {
          "alias": {
            "type": "string"
          },
          "alias_id": {
            "type": "string"
          },
          "alias_key": {
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "entity_id": {
            "type": "string"
          },
          "normalized_alias": {
            "type": "string"
          },
          "user_id": {
            "type": "string"
          }
        },
        "required": [
          "alias_id",
          "user_id",
          "entity_id",
          "alias",
          "normalized_alias",
          "alias_key",
          "created_at"
        ],
        "type": "object"
      },
      "CreateEntityRow": {
        "properties": {
          "contact_email": {
            "type": [
              "string",
              "null"
            ]
          },
          "contact_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "deleted_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "embedding": {
            "items": {
              "format": "float",
              "type": "number"
            },
            "type": "array"
          },
          "entity_id": {
            "type": "string"
          },
          "entity_info": {
            "type": "string"
          },
          "entity_key": {
            "type": "string"
          },
          "entity_type": {
            "type": "string"
          },
          "merged_into_entity_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "metadata": {
            "additionalProperties": true,
            "type": "object"
          },
          "name": {
            "type": "string"
          },
          "normalized_name": {
            "type": "string"
          },
          "source": {
            "type": [
              "string",
              "null"
            ]
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          },
          "user_id": {
            "type": "string"
          }
        },
        "required": [
          "entity_id",
          "user_id",
          "name",
          "normalized_name",
          "entity_key",
          "entity_type",
          "entity_info",
          "embedding",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "CreateObservationRow": {
        "properties": {
          "content": {
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "ended_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "entity_id": {
            "type": "string"
          },
          "metadata": {
            "additionalProperties": true,
            "type": "object"
          },
          "normalized_content": {
            "type": "string"
          },
          "observation_id": {
            "type": "string"
          },
          "observation_key": {
            "type": "string"
          },
          "source": {
            "type": [
              "string",
              "null"
            ]
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          },
          "user_id": {
            "type": "string"
          },
          "valid_from": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "valid_to": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "observation_id",
          "user_id",
          "entity_id",
          "observation_key",
          "content",
          "normalized_content",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "CreateRelationRow": {
        "properties": {
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "from_entity_id": {
            "type": "string"
          },
          "metadata": {
            "additionalProperties": true,
            "type": "object"
          },
          "relation_id": {
            "type": "string"
          },
          "relation_key": {
            "type": "string"
          },
          "relation_type": {
            "type": "string"
          },
          "source": {
            "type": [
              "string",
              "null"
            ]
          },
          "to_entity_id": {
            "type": "string"
          },
          "user_id": {
            "type": "string"
          },
          "weight": {
            "format": "double",
            "type": [
              "number",
              "null"
            ]
          }
        },
        "required": [
          "relation_id",
          "user_id",
          "relation_type",
          "relation_key",
          "from_entity_id",
          "to_entity_id",
          "created_at"
        ],
        "type": "object"
      },
      "DeleteBatchBody": {
        "properties": {
          "entity_ids": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "observations": {
            "items": {
              "$ref": "#/components/schemas/DeleteObservationRow"
            },
            "type": "array"
          },
          "relations": {
            "items": {
              "$ref": "#/components/schemas/DeleteRelationRow"
            },
            "type": "array"
          },
          "user_id": {
            "type": "string"
          }
        },
        "required": [
          "user_id"
        ],
        "type": "object"
      },
      "DeleteObservationRow": {
        "properties": {
          "observation_id": {
            "type": "string"
          },
          "user_id": {
            "type": "string"
          }
        },
        "required": [
          "user_id",
          "observation_id"
        ],
        "type": "object"
      },
      "DeleteRelationRow": {
        "properties": {
          "relation_id": {
            "type": "string"
          },
          "user_id": {
            "type": "string"
          }
        },
        "required": [
          "user_id",
          "relation_id"
        ],
        "type": "object"
      },
      "EnrichedEntity": {
        "properties": {
          "aliases": {
            "items": {
              "$ref": "#/components/schemas/AliasView"
            },
            "type": "array"
          },
          "entity": {
            "$ref": "#/components/schemas/EntityView"
          },
          "observations": {
            "items": {
              "$ref": "#/components/schemas/ObservationView"
            },
            "type": "array"
          },
          "query": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/QueryEntityMeta"
              }
            ]
          }
        },
        "required": [
          "entity",
          "observations",
          "aliases"
        ],
        "type": "object"
      },
      "EnrichedRelation": {
        "properties": {
          "query": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/QueryRelationMeta"
              }
            ]
          },
          "relation": {
            "$ref": "#/components/schemas/RelationView"
          },
          "source_entity_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "target_entity_name": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "relation"
        ],
        "type": "object"
      },
      "EntityView": {
        "properties": {
          "contactEmail": {
            "type": [
              "string",
              "null"
            ]
          },
          "contactName": {
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "deletedAt": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "distance": {
            "description": "Cosine distance from the query embedding when this entity was returned\nby `vector_search_nodes_with`. Lower is better. `None` for hits that\ndid not come from a vector search.",
            "format": "float",
            "type": [
              "number",
              "null"
            ]
          },
          "embedding": {
            "items": {
              "format": "float",
              "type": "number"
            },
            "type": "array"
          },
          "entityId": {
            "type": "string"
          },
          "entityInfo": {
            "type": "string"
          },
          "entityKey": {
            "type": "string"
          },
          "entityType": {
            "type": "string"
          },
          "mergedIntoEntityId": {
            "type": [
              "string",
              "null"
            ]
          },
          "metadata": {
            "additionalProperties": true,
            "type": "object"
          },
          "name": {
            "type": "string"
          },
          "normalizedName": {
            "type": "string"
          },
          "source": {
            "type": [
              "string",
              "null"
            ]
          },
          "updatedAt": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "userId": {
            "type": "string"
          }
        },
        "required": [
          "entityId",
          "userId",
          "name",
          "normalizedName",
          "entityKey",
          "entityType",
          "entityInfo"
        ],
        "type": "object"
      },
      "ErrorResponse": {
        "additionalProperties": false,
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ],
        "type": "object"
      },
      "ExpireObservationRow": {
        "properties": {
          "ended_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "observation_id": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          },
          "user_id": {
            "type": "string"
          },
          "valid_to": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "user_id",
          "observation_id",
          "updated_at"
        ],
        "type": "object"
      },
      "ExpiredObservationInput": {
        "properties": {
          "ended_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "entity_name": {
            "type": "string"
          },
          "observation_content": {
            "type": "string"
          }
        },
        "required": [
          "entity_name",
          "observation_content"
        ],
        "type": "object"
      },
      "GetBody": {
        "properties": {
          "entity_ids": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "include_historical": {
            "type": "boolean"
          },
          "user_id": {
            "type": "string"
          }
        },
        "required": [
          "user_id",
          "entity_ids"
        ],
        "type": "object"
      },
      "KnowledgeGraph": {
        "properties": {
          "entities": {
            "items": {
              "$ref": "#/components/schemas/EnrichedEntity"
            },
            "type": "array"
          },
          "query": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/KnowledgeGraphQueryMetadata"
              }
            ]
          },
          "relations": {
            "items": {
              "$ref": "#/components/schemas/EnrichedRelation"
            },
            "type": "array"
          }
        },
        "required": [
          "entities",
          "relations"
        ],
        "type": "object"
      },
      "KnowledgeGraphQueryMetadata": {
        "properties": {
          "evidence": {
            "items": {
              "$ref": "#/components/schemas/QueryEvidenceStatus"
            },
            "type": "array"
          },
          "warnings": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "ListEntitiesBody": {
        "properties": {
          "limit": {
            "format": "int64",
            "type": "integer"
          },
          "offset": {
            "format": "int64",
            "type": "integer"
          },
          "user_id": {
            "type": "string"
          }
        },
        "required": [
          "user_id",
          "limit",
          "offset"
        ],
        "type": "object"
      },
      "MemoryFactCategory": {
        "enum": [
          "personal",
          "work",
          "relationship",
          "preference",
          "context",
          "other"
        ],
        "type": "string"
      },
      "MemoryFactEvidence": {
        "properties": {
          "chat_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "excerpt": {
            "type": "string"
          },
          "message_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "observed_at": {
            "format": "double",
            "type": "number"
          },
          "source_type": {
            "type": "string"
          }
        },
        "required": [
          "source_type",
          "excerpt",
          "observed_at"
        ],
        "type": "object"
      },
      "MemoryFactSource": {
        "enum": [
          "user_stated",
          "inferred",
          "corrected"
        ],
        "type": "string"
      },
      "MemoryFactStability": {
        "enum": [
          "permanent",
          "long_lived",
          "short_lived"
        ],
        "type": "string"
      },
      "MemoryFactView": {
        "properties": {
          "category": {
            "$ref": "#/components/schemas/MemoryFactCategory"
          },
          "confidence": {
            "format": "double",
            "type": [
              "number",
              "null"
            ]
          },
          "entity_id": {
            "type": "string"
          },
          "fact": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "learned_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "source": {
            "$ref": "#/components/schemas/MemoryFactSource"
          }
        },
        "required": [
          "id",
          "fact",
          "category",
          "source",
          "entity_id"
        ],
        "type": "object"
      },
      "MemoryForgetInput": {
        "properties": {
          "categories": {
            "items": {
              "$ref": "#/components/schemas/MemoryFactCategory"
            },
            "type": "array"
          },
          "fact": {
            "type": [
              "string",
              "null"
            ]
          },
          "fact_ids": {
            "items": {
              "type": "string"
            },
            "type": [
              "array",
              "null"
            ]
          },
          "user_id": {
            "type": "string"
          }
        },
        "required": [
          "user_id"
        ],
        "type": "object"
      },
      "MemoryForgetResult": {
        "properties": {
          "removed_count": {
            "minimum": 0,
            "type": "integer"
          },
          "removed_fact_ids": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "removed_count",
          "removed_fact_ids"
        ],
        "type": "object"
      },
      "MemoryLearnBatchInput": {
        "properties": {
          "facts": {
            "items": {
              "$ref": "#/components/schemas/MemoryLearnInput"
            },
            "type": "array"
          },
          "user_id": {
            "type": "string"
          }
        },
        "required": [
          "user_id",
          "facts"
        ],
        "type": "object"
      },
      "MemoryLearnBatchResult": {
        "properties": {
          "fact_ids": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "new_count": {
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "fact_ids",
          "new_count"
        ],
        "type": "object"
      },
      "MemoryLearnInput": {
        "properties": {
          "category": {
            "$ref": "#/components/schemas/MemoryFactCategory"
          },
          "confidence": {
            "format": "double",
            "type": [
              "number",
              "null"
            ]
          },
          "context": {
            "type": [
              "string",
              "null"
            ]
          },
          "evidence": {
            "items": {
              "$ref": "#/components/schemas/MemoryFactEvidence"
            },
            "type": "array"
          },
          "fact": {
            "type": "string"
          },
          "key": {
            "type": [
              "string",
              "null"
            ]
          },
          "replaces": {
            "type": [
              "string",
              "null"
            ]
          },
          "source": {
            "$ref": "#/components/schemas/MemoryFactSource"
          },
          "stability": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/MemoryFactStability"
              }
            ]
          },
          "user_id": {
            "type": "string"
          }
        },
        "required": [
          "user_id",
          "category",
          "fact",
          "source"
        ],
        "type": "object"
      },
      "MemoryPersonInput": {
        "properties": {
          "company": {
            "type": [
              "string",
              "null"
            ]
          },
          "context": {
            "type": [
              "string",
              "null"
            ]
          },
          "email": {
            "type": [
              "string",
              "null"
            ]
          },
          "name": {
            "type": "string"
          },
          "relationship": {
            "type": "string"
          },
          "user_id": {
            "type": "string"
          }
        },
        "required": [
          "user_id",
          "name",
          "relationship"
        ],
        "type": "object"
      },
      "MemoryPersonResult": {
        "properties": {
          "added": {
            "type": "boolean"
          },
          "reason": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "added"
        ],
        "type": "object"
      },
      "MemoryRecallInput": {
        "properties": {
          "categories": {
            "items": {
              "$ref": "#/components/schemas/MemoryFactCategory"
            },
            "type": "array"
          },
          "limit": {
            "format": "int64",
            "type": "integer"
          },
          "query": {
            "type": [
              "string",
              "null"
            ]
          },
          "user_id": {
            "type": "string"
          }
        },
        "required": [
          "user_id"
        ],
        "type": "object"
      },
      "MemorySummary": {
        "properties": {
          "fact_count": {
            "minimum": 0,
            "type": "integer"
          },
          "recent_facts": {
            "items": {
              "$ref": "#/components/schemas/MemoryFactView"
            },
            "type": "array"
          }
        },
        "required": [
          "recent_facts",
          "fact_count"
        ],
        "type": "object"
      },
      "MemoryUpdateProfileInput": {
        "properties": {
          "communication": {
            "additionalProperties": true,
            "type": "object"
          },
          "personal": {
            "additionalProperties": true,
            "type": "object"
          },
          "user_id": {
            "type": "string"
          },
          "work": {
            "additionalProperties": true,
            "type": "object"
          }
        },
        "required": [
          "user_id"
        ],
        "type": "object"
      },
      "MergeEntityFullBody": {
        "properties": {
          "canonical_entity_id": {
            "type": "string"
          },
          "duplicate_entity_id": {
            "type": "string"
          },
          "user_id": {
            "type": "string"
          }
        },
        "required": [
          "user_id",
          "canonical_entity_id",
          "duplicate_entity_id"
        ],
        "type": "object"
      },
      "MergeResult": {
        "properties": {
          "aliases_repointed": {
            "minimum": 0,
            "type": "integer"
          },
          "canonical_entity_id": {
            "type": "string"
          },
          "duplicate_entity_id": {
            "type": "string"
          },
          "observations_moved": {
            "minimum": 0,
            "type": "integer"
          },
          "relations_rewired": {
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "canonical_entity_id",
          "duplicate_entity_id",
          "observations_moved",
          "aliases_repointed",
          "relations_rewired"
        ],
        "type": "object"
      },
      "NormalizedNamesBody": {
        "properties": {
          "normalized_names": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "user_id": {
            "type": "string"
          }
        },
        "required": [
          "user_id",
          "normalized_names"
        ],
        "type": "object"
      },
      "ObservationView": {
        "properties": {
          "content": {
            "type": "string"
          },
          "createdAt": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "endedReason": {
            "type": [
              "string",
              "null"
            ]
          },
          "metadata": {
            "additionalProperties": true,
            "type": "object"
          },
          "normalizedContent": {
            "type": "string"
          },
          "observationId": {
            "type": "string"
          },
          "observationKey": {
            "type": "string"
          },
          "source": {
            "type": [
              "string",
              "null"
            ]
          },
          "updatedAt": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "validFrom": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "validTo": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "observationId",
          "observationKey",
          "content",
          "normalizedContent"
        ],
        "type": "object"
      },
      "ObservationsForEntitiesBody": {
        "properties": {
          "entity_ids": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "include_historical": {
            "type": "boolean"
          },
          "user_id": {
            "type": "string"
          }
        },
        "required": [
          "user_id",
          "entity_ids",
          "include_historical"
        ],
        "type": "object"
      },
      "ObservationsForEntityBody": {
        "properties": {
          "entity_id": {
            "type": "string"
          },
          "include_historical": {
            "type": "boolean"
          },
          "user_id": {
            "type": "string"
          }
        },
        "required": [
          "user_id",
          "entity_id",
          "include_historical"
        ],
        "type": "object"
      },
      "QueryChunkBody": {
        "properties": {
          "query": {
            "type": "string"
          },
          "weight": {
            "format": "double",
            "type": "number"
          }
        },
        "required": [
          "query"
        ],
        "type": "object"
      },
      "QueryEntityMeta": {
        "properties": {
          "distance": {
            "format": "int32",
            "minimum": 0,
            "type": "integer"
          },
          "role": {
            "$ref": "#/components/schemas/QueryRole"
          },
          "sources": {
            "items": {
              "$ref": "#/components/schemas/QuerySource"
            },
            "type": "array"
          }
        },
        "required": [
          "role",
          "distance",
          "sources"
        ],
        "type": "object"
      },
      "QueryEvidenceStatus": {
        "properties": {
          "directObservationMissingForQuery": {
            "type": "boolean"
          },
          "entityName": {
            "type": "string"
          },
          "hasAdjacentRelevantContext": {
            "type": "boolean"
          },
          "hasDirectRelevantObservation": {
            "type": "boolean"
          }
        },
        "required": [
          "entityName",
          "hasDirectRelevantObservation",
          "hasAdjacentRelevantContext",
          "directObservationMissingForQuery"
        ],
        "type": "object"
      },
      "QueryRelationMeta": {
        "properties": {
          "distanceFromSeed": {
            "format": "int32",
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "distanceFromSeed"
        ],
        "type": "object"
      },
      "QueryRole": {
        "enum": [
          "seed",
          "adjacent"
        ],
        "type": "string"
      },
      "QuerySource": {
        "enum": [
          "exact",
          "text_search",
          "rag",
          "contact"
        ],
        "type": "string"
      },
      "RecomputeSearchStateBody": {
        "properties": {
          "entity_ids": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "user_id": {
            "type": "string"
          }
        },
        "required": [
          "user_id",
          "entity_ids"
        ],
        "type": "object"
      },
      "RelationByIdBody": {
        "properties": {
          "relation_id": {
            "type": "string"
          },
          "user_id": {
            "type": "string"
          }
        },
        "required": [
          "user_id",
          "relation_id"
        ],
        "type": "object"
      },
      "RelationView": {
        "properties": {
          "createdAt": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "fromEntityId": {
            "type": "string"
          },
          "metadata": {
            "additionalProperties": true,
            "type": "object"
          },
          "relationId": {
            "type": "string"
          },
          "relationKey": {
            "type": "string"
          },
          "relationType": {
            "type": "string"
          },
          "source": {
            "type": [
              "string",
              "null"
            ]
          },
          "toEntityId": {
            "type": "string"
          },
          "weight": {
            "format": "double",
            "type": [
              "number",
              "null"
            ]
          }
        },
        "required": [
          "relationId",
          "relationType",
          "relationKey",
          "fromEntityId",
          "toEntityId"
        ],
        "type": "object"
      },
      "RepointAliasRow": {
        "properties": {
          "alias_id": {
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "entity_id": {
            "type": "string"
          },
          "user_id": {
            "type": "string"
          }
        },
        "required": [
          "alias_id",
          "user_id",
          "entity_id",
          "created_at"
        ],
        "type": "object"
      },
      "ResolveCandidate": {
        "properties": {
          "confidence": {
            "format": "double",
            "type": "number"
          },
          "entity_id": {
            "type": "string"
          },
          "entity_type": {
            "type": "string"
          },
          "match_method": {
            "type": "string"
          },
          "name": {
            "type": "string"
          }
        },
        "required": [
          "entity_id",
          "name",
          "entity_type",
          "confidence",
          "match_method"
        ],
        "type": "object"
      },
      "ResolveEntitiesBody": {
        "properties": {
          "contact_emails": {
            "items": {
              "type": [
                "string",
                "null"
              ]
            },
            "type": "array"
          },
          "entity_types": {
            "items": {
              "type": [
                "string",
                "null"
              ]
            },
            "type": "array"
          },
          "names": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "user_id": {
            "type": "string"
          }
        },
        "required": [
          "user_id",
          "names"
        ],
        "type": "object"
      },
      "ResolveResult": {
        "properties": {
          "candidates": {
            "items": {
              "$ref": "#/components/schemas/ResolveCandidate"
            },
            "type": "array"
          },
          "query_name": {
            "type": "string"
          }
        },
        "required": [
          "query_name",
          "candidates"
        ],
        "type": "object"
      },
      "RewireRelationRow": {
        "properties": {
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "from_entity_id": {
            "type": "string"
          },
          "metadata": {
            "additionalProperties": true,
            "type": "object"
          },
          "old_relation_id": {
            "type": "string"
          },
          "relation_id": {
            "type": "string"
          },
          "relation_key": {
            "type": "string"
          },
          "relation_type": {
            "type": "string"
          },
          "source": {
            "type": [
              "string",
              "null"
            ]
          },
          "to_entity_id": {
            "type": "string"
          },
          "user_id": {
            "type": "string"
          },
          "weight": {
            "format": "double",
            "type": [
              "number",
              "null"
            ]
          }
        },
        "required": [
          "old_relation_id",
          "relation_id",
          "user_id",
          "relation_type",
          "relation_key",
          "from_entity_id",
          "to_entity_id",
          "created_at"
        ],
        "type": "object"
      },
      "SearchAnnotation": {
        "properties": {
          "combined_score": {
            "format": "double",
            "type": "number"
          },
          "entity_id": {
            "type": "string"
          },
          "temporal_decay": {
            "format": "double",
            "type": "number"
          },
          "text_score": {
            "format": "double",
            "type": [
              "number",
              "null"
            ]
          },
          "vector_score": {
            "format": "double",
            "type": [
              "number",
              "null"
            ]
          },
          "vector_similarity": {
            "description": "Best (max) cosine similarity in `[0.0, 1.0]` across all chunks that\nhit this entity via vector search. `None` if no vector hit cleared the\n`min_vector_similarity` floor or if the entity was found by text only.",
            "format": "double",
            "type": [
              "number",
              "null"
            ]
          }
        },
        "required": [
          "entity_id",
          "combined_score",
          "temporal_decay"
        ],
        "type": "object"
      },
      "SearchBody": {
        "description": "Polymorphic search body. Provide one or more selectors (queries / query_vector /\ncontact_emails / normalized_names / seed_entity_ids); seeds from each selector\nare unioned and expanded automatically up to `depth`.",
        "properties": {
          "contact_emails": {
            "description": "Look up entities by contact email (replaces /entity/by-contact-emails[/direct]).",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "depth": {
            "description": "Expansion depth. `0` skips neighborhood expansion (replaces \"direct\" variants).",
            "format": "int64",
            "type": "integer"
          },
          "include_relations": {
            "description": "When false, skip relation enrichment (used for the legacy direct contact lookup).",
            "type": "boolean"
          },
          "limit": {
            "format": "int64",
            "type": "integer"
          },
          "max_entities": {
            "format": "int64",
            "type": "integer"
          },
          "normalized_names": {
            "description": "Look up entities by normalized name (replaces /entity/by-names).",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "queries": {
            "description": "Weighted semantic chunks. Each chunk is searched in parallel and merged.",
            "items": {
              "$ref": "#/components/schemas/QueryChunkBody"
            },
            "type": "array"
          },
          "query": {
            "description": "Single text query (legacy). Merged into `queries` if both are provided.",
            "type": [
              "string",
              "null"
            ]
          },
          "query_vector": {
            "description": "Direct embedding vector (replaces /search-entities-vector).",
            "items": {
              "format": "float",
              "type": "number"
            },
            "type": [
              "array",
              "null"
            ]
          },
          "rewrite_query": {
            "description": "When true (default), the gateway runs `chunk_user_query` on the\nlegacy `query` string before fanning out (so a single \"who's ryan\" is\nexpanded into multiple weighted chunks server-side). Pre-built\n`queries` are passed through unchanged regardless of this flag.",
            "type": "boolean"
          },
          "seed_entity_ids": {
            "description": "Seed expansion from known entity ids (replaces /expand-neighborhood).",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "session_id": {
            "description": "Optional conversation/session id. When present, the gateway merges\nthe seed entities returned by previous calls with this `session_id`\ninto `seed_entity_ids` before searching, and records new seed-role\nentities afterwards. Lets multi-turn callers carry entity context\nacross requests without managing their own cache.",
            "type": [
              "string",
              "null"
            ]
          },
          "user_id": {
            "type": "string"
          }
        },
        "required": [
          "user_id"
        ],
        "type": "object"
      },
      "SearchResult": {
        "properties": {
          "annotations": {
            "items": {
              "$ref": "#/components/schemas/SearchAnnotation"
            },
            "type": "array"
          },
          "graph": {
            "$ref": "#/components/schemas/KnowledgeGraph"
          },
          "stage_timings": {
            "description": "Per-stage timing in milliseconds. Populated by the search service for\ndiagnostics; empty for non-search callers. Skipped from the wire when\nempty so legacy clients are unaffected.",
            "type": "object"
          }
        },
        "required": [
          "graph",
          "annotations"
        ],
        "type": "object"
      },
      "SoftMergeBody": {
        "properties": {
          "canonical_id": {
            "type": "string"
          },
          "duplicate_id": {
            "type": "string"
          },
          "merged_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "duplicate_id",
          "canonical_id",
          "merged_at"
        ],
        "type": "object"
      },
      "SyncEntityInput": {
        "properties": {
          "contact_email": {
            "type": [
              "string",
              "null"
            ]
          },
          "contact_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "entity_type": {
            "type": "string"
          },
          "metadata": {
            "additionalProperties": true,
            "type": "object"
          },
          "name": {
            "type": "string"
          },
          "observations": {
            "items": {
              "$ref": "#/components/schemas/SyncObservationInput"
            },
            "type": "array"
          },
          "source": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "name",
          "entity_type",
          "observations"
        ],
        "type": "object"
      },
      "SyncInput": {
        "properties": {
          "entities": {
            "items": {
              "$ref": "#/components/schemas/SyncEntityInput"
            },
            "type": "array"
          },
          "expired_observations": {
            "items": {
              "$ref": "#/components/schemas/ExpiredObservationInput"
            },
            "type": "array"
          },
          "relations": {
            "items": {
              "$ref": "#/components/schemas/SyncRelationInput"
            },
            "type": "array"
          },
          "user_id": {
            "type": "string"
          }
        },
        "required": [
          "user_id",
          "entities"
        ],
        "type": "object"
      },
      "SyncObservationInput": {
        "description": "A single observation in a sync request.\n\nWire format accepts either a bare string (legacy) or an object with\n`content`, optional `valid_from`, `valid_to`, `ended_reason`. When provided,\n`valid_from` pins the observation to a caller-supplied timestamp (e.g. the\nemail's received date) instead of the gateway's `now()` at write time.",
        "oneOf": [
          {
            "properties": {
              "content": {
                "type": "string"
              },
              "ended_reason": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "valid_from": {
                "format": "date-time",
                "type": [
                  "string",
                  "null"
                ]
              },
              "valid_to": {
                "format": "date-time",
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "content"
            ],
            "type": "object"
          },
          {
            "type": "string"
          }
        ]
      },
      "SyncRelationInput": {
        "properties": {
          "from_name": {
            "type": "string"
          },
          "metadata": {
            "additionalProperties": true,
            "type": "object"
          },
          "relation_type": {
            "type": "string"
          },
          "source": {
            "type": [
              "string",
              "null"
            ]
          },
          "to_name": {
            "type": "string"
          },
          "weight": {
            "format": "double",
            "type": [
              "number",
              "null"
            ]
          }
        },
        "required": [
          "from_name",
          "to_name",
          "relation_type"
        ],
        "type": "object"
      },
      "SyncResult": {
        "properties": {
          "aliases_created": {
            "minimum": 0,
            "type": "integer"
          },
          "entities_created": {
            "minimum": 0,
            "type": "integer"
          },
          "entities_existing": {
            "minimum": 0,
            "type": "integer"
          },
          "observations_added": {
            "minimum": 0,
            "type": "integer"
          },
          "observations_deduplicated": {
            "minimum": 0,
            "type": "integer"
          },
          "observations_expired": {
            "minimum": 0,
            "type": "integer"
          },
          "relations_created": {
            "minimum": 0,
            "type": "integer"
          },
          "relations_deduplicated": {
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "entities_created",
          "entities_existing",
          "observations_added",
          "observations_deduplicated",
          "observations_expired",
          "relations_created",
          "relations_deduplicated",
          "aliases_created"
        ],
        "type": "object"
      },
      "TopEntitiesBody": {
        "properties": {
          "limit": {
            "format": "int64",
            "type": "integer"
          },
          "user_id": {
            "type": "string"
          }
        },
        "required": [
          "user_id",
          "limit"
        ],
        "type": "object"
      },
      "UpdateEntitySearchStateRow": {
        "properties": {
          "embedding": {
            "items": {
              "format": "float",
              "type": "number"
            },
            "type": "array"
          },
          "entity_id": {
            "type": "string"
          },
          "entity_info": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          },
          "user_id": {
            "type": "string"
          }
        },
        "required": [
          "user_id",
          "entity_id",
          "entity_info",
          "embedding",
          "updated_at"
        ],
        "type": "object"
      },
      "UserEntityBody": {
        "properties": {
          "entity_id": {
            "type": "string"
          },
          "user_id": {
            "type": "string"
          }
        },
        "required": [
          "user_id",
          "entity_id"
        ],
        "type": "object"
      },
      "UserEntityIdsBody": {
        "properties": {
          "entity_ids": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "user_id": {
            "type": "string"
          }
        },
        "required": [
          "user_id",
          "entity_ids"
        ],
        "type": "object"
      },
      "UserIdBody": {
        "properties": {
          "user_id": {
            "type": "string"
          }
        },
        "required": [
          "user_id"
        ],
        "type": "object"
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "bearerFormat": "gateway token",
        "description": "Send the configured Helix gateway token in the Authorization header as `Bearer <token>`.",
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "contact": {
      "email": "engineering@orchid.ai",
      "name": "Orchid Engineering",
      "url": "https://github.com/orchid-ai/orchid"
    },
    "description": "HTTP gateway for Orchid's Helix-backed knowledge graph, memory, and search APIs",
    "license": {
      "identifier": "MIT",
      "name": "MIT"
    },
    "title": "Orchid Knowledge Graph Gateway",
    "version": "0.1.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/add-observations-batch": {
      "post": {
        "description": "Add Observations Batch. Internal knowledge graph building block used by sync, search, or maintenance flows.",
        "operationId": "add_observations_batch",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "items": {
                  "$ref": "#/components/schemas/CreateObservationRow"
                },
                "type": "array"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Observations added"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Add Observations Batch",
        "tags": [
          "Observation"
        ]
      }
    },
    "/admin/cleanup-orphaned-relations": {
      "post": {
        "description": "Admin Cleanup Orphaned Relations. Administrative maintenance endpoint for trusted Orchid operators.",
        "operationId": "admin_cleanup_orphaned_relations",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CleanupBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": ""
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Admin Cleanup Orphaned Relations",
        "tags": [
          "Admin"
        ]
      }
    },
    "/admin/create-indexes": {
      "post": {
        "description": "Admin Create Indexes. Administrative maintenance endpoint for trusted Orchid operators.",
        "operationId": "admin_create_indexes",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": ""
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Admin Create Indexes",
        "tags": [
          "Admin"
        ]
      }
    },
    "/admin/delete-all-knowledge": {
      "post": {
        "description": "Admin Delete All Knowledge. Administrative maintenance endpoint for trusted Orchid operators.",
        "operationId": "admin_delete_all_knowledge",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UserIdBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": ""
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Admin Delete All Knowledge",
        "tags": [
          "Admin"
        ]
      }
    },
    "/admin/merge-entity-full": {
      "post": {
        "description": "Admin Merge Entity Full. Administrative maintenance endpoint for trusted Orchid operators.",
        "operationId": "admin_merge_entity_full",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MergeEntityFullBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MergeResult"
                }
              }
            },
            "description": ""
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Admin Merge Entity Full",
        "tags": [
          "Admin"
        ]
      }
    },
    "/admin/recompute-search-state": {
      "post": {
        "description": "Admin Recompute Search State. Administrative maintenance endpoint for trusted Orchid operators.",
        "operationId": "admin_recompute_search_state",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RecomputeSearchStateBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": ""
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Admin Recompute Search State",
        "tags": [
          "Admin"
        ]
      }
    },
    "/admin/reconcile-search-state": {
      "post": {
        "description": "Admin Reconcile Search State. Administrative maintenance endpoint for trusted Orchid operators.",
        "operationId": "admin_reconcile_search_state",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UserIdBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": ""
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Admin Reconcile Search State",
        "tags": [
          "Admin"
        ]
      }
    },
    "/admin/reindex-all-knowledge": {
      "post": {
        "description": "Admin Reindex All Knowledge. Administrative maintenance endpoint for trusted Orchid operators.",
        "operationId": "admin_reindex_all_knowledge",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UserIdBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": ""
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Admin Reindex All Knowledge",
        "tags": [
          "Admin"
        ]
      }
    },
    "/admin/resolve-entities": {
      "post": {
        "description": "Admin Resolve Entities. Administrative maintenance endpoint for trusted Orchid operators.",
        "operationId": "admin_resolve_entities",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResolveEntitiesBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/ResolveResult"
                  },
                  "type": "array"
                }
              }
            },
            "description": ""
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Admin Resolve Entities",
        "tags": [
          "Admin"
        ]
      }
    },
    "/admin/top-entities": {
      "post": {
        "description": "Admin Top Entities. Administrative maintenance endpoint for trusted Orchid operators.",
        "operationId": "admin_top_entities",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TopEntitiesBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": ""
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Admin Top Entities",
        "tags": [
          "Admin"
        ]
      }
    },
    "/create-aliases-batch": {
      "post": {
        "description": "Create Aliases Batch. Internal knowledge graph building block used by sync, search, or maintenance flows.",
        "operationId": "create_aliases_batch",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "items": {
                  "$ref": "#/components/schemas/CreateAliasRow"
                },
                "type": "array"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Aliases created"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Create Aliases Batch",
        "tags": [
          "Alias"
        ]
      }
    },
    "/create-entities-batch": {
      "post": {
        "description": "Create Entities Batch. Internal knowledge graph building block used by sync, search, or maintenance flows.",
        "operationId": "create_entities_batch",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "items": {
                  "$ref": "#/components/schemas/CreateEntityRow"
                },
                "type": "array"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Entities created"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Create Entities Batch",
        "tags": [
          "Entity"
        ]
      }
    },
    "/create-relations-batch": {
      "post": {
        "description": "Create Relations Batch. Internal knowledge graph building block used by sync, search, or maintenance flows.",
        "operationId": "create_relations_batch",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "items": {
                  "$ref": "#/components/schemas/CreateRelationRow"
                },
                "type": "array"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Relations created"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Create Relations Batch",
        "tags": [
          "Relation"
        ]
      }
    },
    "/delete": {
      "post": {
        "description": "Unified delete: any subset of `entity_ids`, `observations`, `relations` may be present.. Public knowledge graph endpoint for Orchid service callers.",
        "operationId": "delete",
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "entity_ids": [
                  "entity_123"
                ],
                "observations": [],
                "relations": [],
                "user_id": "connection_123"
              },
              "schema": {
                "$ref": "#/components/schemas/DeleteBatchBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Entities/observations/relations deleted"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Unified delete: any subset of `entity_ids`, `observations`, `relations` may be present.",
        "tags": [
          "Public"
        ]
      }
    },
    "/delete-aliases-for-entities": {
      "post": {
        "description": "Delete Aliases For Entities. Internal knowledge graph building block used by sync, search, or maintenance flows.",
        "operationId": "delete_aliases_for_entities",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UserEntityIdsBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Aliases deleted for entities"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Delete Aliases For Entities",
        "tags": [
          "Alias"
        ]
      }
    },
    "/expire-observations-batch": {
      "post": {
        "description": "Expire Observations Batch. Internal knowledge graph building block used by sync, search, or maintenance flows.",
        "operationId": "expire_observations_batch",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "items": {
                  "$ref": "#/components/schemas/ExpireObservationRow"
                },
                "type": "array"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Observations expired"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Expire Observations Batch",
        "tags": [
          "Observation"
        ]
      }
    },
    "/get": {
      "post": {
        "description": "Get Subgraph. Public knowledge graph endpoint for Orchid service callers.",
        "operationId": "get_subgraph",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GetBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Entity subgraph with observations and relations"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Get Subgraph",
        "tags": [
          "Public"
        ]
      }
    },
    "/get-active-entities-by-ids": {
      "post": {
        "description": "Get Active Entities By IDs. Internal knowledge graph building block used by sync, search, or maintenance flows.",
        "operationId": "get_active_entities_by_ids",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UserEntityIdsBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Active (non-merged, non-deleted) entities"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Get Active Entities By IDs",
        "tags": [
          "Entity"
        ]
      }
    },
    "/get-alias-targets": {
      "post": {
        "description": "Get Alias Targets. Internal knowledge graph building block used by sync, search, or maintenance flows.",
        "operationId": "get_alias_targets",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AliasTargetsBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Alias target entities"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Get Alias Targets",
        "tags": [
          "Alias"
        ]
      }
    },
    "/get-entities-by-contact-email": {
      "post": {
        "description": "Get Entities By Contact Email. Internal knowledge graph building block used by sync, search, or maintenance flows.",
        "operationId": "get_entities_by_contact_email",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContactEmailBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Entities matching contact email"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Get Entities By Contact Email",
        "tags": [
          "Entity"
        ]
      }
    },
    "/get-entities-by-ids": {
      "post": {
        "description": "Get Entities By IDs. Internal knowledge graph building block used by sync, search, or maintenance flows.",
        "operationId": "get_entities_by_ids",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UserEntityIdsBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Entities found"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Get Entities By IDs",
        "tags": [
          "Entity"
        ]
      }
    },
    "/get-entities-by-normalized-names": {
      "post": {
        "description": "Get Entities By Normalized Names. Internal knowledge graph building block used by sync, search, or maintenance flows.",
        "operationId": "get_entities_by_normalized_names",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NormalizedNamesBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Entities matching normalized names"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Get Entities By Normalized Names",
        "tags": [
          "Entity"
        ]
      }
    },
    "/get-entity-by-id": {
      "post": {
        "description": "Get Entity By ID. Internal knowledge graph building block used by sync, search, or maintenance flows.",
        "operationId": "get_entity_by_id",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UserEntityBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Entity found"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Get Entity By ID",
        "tags": [
          "Entity"
        ]
      }
    },
    "/get-observations-for-entities": {
      "post": {
        "description": "Get Observations For Entities. Internal knowledge graph building block used by sync, search, or maintenance flows.",
        "operationId": "get_observations_for_entities",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ObservationsForEntitiesBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Observations for multiple entities"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Get Observations For Entities",
        "tags": [
          "Observation"
        ]
      }
    },
    "/get-observations-for-entity": {
      "post": {
        "description": "Get Observations For Entity. Internal knowledge graph building block used by sync, search, or maintenance flows.",
        "operationId": "get_observations_for_entity",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ObservationsForEntityBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Observations for entity"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Get Observations For Entity",
        "tags": [
          "Observation"
        ]
      }
    },
    "/get-relation-by-id": {
      "post": {
        "description": "Get Relation By ID. Internal knowledge graph building block used by sync, search, or maintenance flows.",
        "operationId": "get_relation_by_id",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RelationByIdBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Relation found"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Get Relation By ID",
        "tags": [
          "Relation"
        ]
      }
    },
    "/get-relations-for-entity": {
      "post": {
        "description": "Get Relations For Entity. Internal knowledge graph building block used by sync, search, or maintenance flows.",
        "operationId": "get_relations_for_entity",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UserEntityBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Relations for entity"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Get Relations For Entity",
        "tags": [
          "Relation"
        ]
      }
    },
    "/get-relations-touching-entities": {
      "post": {
        "description": "Get Relations Touching Entities. Internal knowledge graph building block used by sync, search, or maintenance flows.",
        "operationId": "get_relations_touching_entities",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UserEntityIdsBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Relations touching any of the given entities"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Get Relations Touching Entities",
        "tags": [
          "Relation"
        ]
      }
    },
    "/list-entities": {
      "post": {
        "description": "List Entities. Internal knowledge graph building block used by sync, search, or maintenance flows.",
        "operationId": "list_entities",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ListEntitiesBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Paginated entity list"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "List Entities",
        "tags": [
          "Entity"
        ]
      }
    },
    "/memory/clear": {
      "post": {
        "description": "Memory Clear. Memory endpoint scoped by the supplied user_id.",
        "operationId": "memory_clear",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UserIdBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Memory cleared"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Memory Clear",
        "tags": [
          "Memory"
        ]
      }
    },
    "/memory/forget": {
      "post": {
        "description": "Memory Forget. Memory endpoint scoped by the supplied user_id.",
        "operationId": "memory_forget",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MemoryForgetInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MemoryForgetResult"
                }
              }
            },
            "description": "Memory facts forgotten"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Memory Forget",
        "tags": [
          "Memory"
        ]
      }
    },
    "/memory/learn": {
      "post": {
        "description": "Always returns a `MemoryLearnBatchResult`. Accepts:\n  - `{ facts: [...] }` (batch form, replaces /memory/learn-batch)\n  - a bare `MemoryLearnInput` (single form; result wraps it in a 1-element batch). Memory endpoint scoped by the supplied user_id.",
        "operationId": "memory_learn",
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "facts": [
                  {
                    "category": "preference",
                    "fact": "Prefers concise meeting prep.",
                    "source": "user_stated",
                    "stability": "long_lived",
                    "user_id": "connection_123"
                  }
                ],
                "user_id": "connection_123"
              },
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/MemoryLearnBatchInput"
                  },
                  {
                    "$ref": "#/components/schemas/MemoryLearnInput"
                  }
                ]
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MemoryLearnBatchResult"
                }
              }
            },
            "description": "Memory facts learned"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Always returns a `MemoryLearnBatchResult`. Accepts:\n  - `{ facts: [...] }` (batch form, replaces /memory/learn-batch)\n  - a bare `MemoryLearnInput` (single form; result wraps it in a 1-element batch)",
        "tags": [
          "Memory"
        ]
      }
    },
    "/memory/recall": {
      "post": {
        "description": "Memory Recall. Memory endpoint scoped by the supplied user_id.",
        "operationId": "memory_recall",
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "categories": [
                  "preference"
                ],
                "limit": 10,
                "query": "meeting preferences",
                "user_id": "connection_123"
              },
              "schema": {
                "$ref": "#/components/schemas/MemoryRecallInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/MemoryFactView"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Memory facts recalled"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Memory Recall",
        "tags": [
          "Memory"
        ]
      }
    },
    "/memory/summary": {
      "post": {
        "description": "Memory Summary. Memory endpoint scoped by the supplied user_id.",
        "operationId": "memory_summary",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UserIdBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MemorySummary"
                }
              }
            },
            "description": "Memory summary"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Memory Summary",
        "tags": [
          "Memory"
        ]
      }
    },
    "/memory/update-profile": {
      "post": {
        "description": "Memory Update Profile. Memory endpoint scoped by the supplied user_id.",
        "operationId": "memory_update_profile",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MemoryUpdateProfileInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Memory profile updated"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Memory Update Profile",
        "tags": [
          "Memory"
        ]
      }
    },
    "/memory/upsert-person": {
      "post": {
        "description": "Memory Upsert Person. Memory endpoint scoped by the supplied user_id.",
        "operationId": "memory_upsert_person",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MemoryPersonInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MemoryPersonResult"
                }
              }
            },
            "description": "Memory person upserted"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Memory Upsert Person",
        "tags": [
          "Memory"
        ]
      }
    },
    "/repoint-aliases-to-canonical": {
      "post": {
        "description": "Repoint Aliases To Canonical. Internal knowledge graph building block used by sync, search, or maintenance flows.",
        "operationId": "repoint_aliases_to_canonical",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "items": {
                  "$ref": "#/components/schemas/RepointAliasRow"
                },
                "type": "array"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Aliases repointed"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Repoint Aliases To Canonical",
        "tags": [
          "Alias"
        ]
      }
    },
    "/rewire-relations-to-canonical": {
      "post": {
        "description": "Rewire Relations To Canonical. Internal knowledge graph building block used by sync, search, or maintenance flows.",
        "operationId": "rewire_relations_to_canonical",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "items": {
                  "$ref": "#/components/schemas/RewireRelationRow"
                },
                "type": "array"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Relations rewired to canonical entity"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Rewire Relations To Canonical",
        "tags": [
          "Relation"
        ]
      }
    },
    "/search": {
      "post": {
        "description": "`depth=0` skips neighborhood expansion. `include_relations=false` skips relation\nenrichment (used for the legacy direct-contact lookup pattern).",
        "operationId": "search",
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "depth": 1,
                "include_relations": true,
                "limit": 10,
                "max_entities": 50,
                "query": "what should I know about Ada before the meeting?",
                "user_id": "connection_123"
              },
              "schema": {
                "$ref": "#/components/schemas/SearchBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResult"
                }
              }
            },
            "description": "Search results merged across selectors"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Polymorphic search. Supports any combination of:\n  - `queries` / `query` (text chunks)\n  - `query_vector` (raw embedding)\n  - `contact_emails` (lookup by contact)\n  - `normalized_names` (lookup by name)\n  - `seed_entity_ids` (expand-only)",
        "tags": [
          "Public"
        ]
      }
    },
    "/soft-merge-entity": {
      "post": {
        "description": "Soft Merge Entity. Internal knowledge graph building block used by sync, search, or maintenance flows.",
        "operationId": "soft_merge_entity",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SoftMergeBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Entity soft-merged"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Soft Merge Entity",
        "tags": [
          "Entity"
        ]
      }
    },
    "/sync": {
      "post": {
        "description": "Sync. Public knowledge graph endpoint for Orchid service callers.",
        "operationId": "sync",
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "entities": [
                  {
                    "entity_type": "person",
                    "name": "Ada Lovelace",
                    "observations": [
                      {
                        "content": "Ada prefers morning meetings.",
                        "valid_from": "2026-05-12T09:00:00Z"
                      }
                    ],
                    "source": "email"
                  }
                ],
                "expired_observations": [],
                "relations": [
                  {
                    "from_name": "Ada Lovelace",
                    "relation_type": "works_at",
                    "to_name": "Analytical Engines Inc"
                  }
                ],
                "user_id": "connection_123"
              },
              "schema": {
                "$ref": "#/components/schemas/SyncInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SyncResult"
                }
              }
            },
            "description": "Knowledge synced"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Sync",
        "tags": [
          "Public"
        ]
      }
    },
    "/update-entities-info-and-embeddings-batch": {
      "post": {
        "description": "Update Entities Info And Embeddings Batch. Internal knowledge graph building block used by sync, search, or maintenance flows.",
        "operationId": "update_entities_info_and_embeddings_batch",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "items": {
                  "$ref": "#/components/schemas/UpdateEntitySearchStateRow"
                },
                "type": "array"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Entity search state updated"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Invalid request body or parameters"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request body or parameters"
          },
          "401": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Missing or invalid bearer token"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Missing or invalid bearer token"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Host or origin is not allowed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Host or origin is not allowed"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "error": "Gateway or upstream service error"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Gateway or upstream service error"
          }
        },
        "summary": "Update Entities Info And Embeddings Batch",
        "tags": [
          "Entity"
        ]
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "servers": [
    {
      "description": "Production Helix gateway",
      "url": "https://supersalience.com"
    }
  ]
}