> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequency.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Historical analogs as analog_overlay annotations for the chart lab



## OpenAPI

````yaml /api/openapi.json post /api/graph/v1/analysis/analogs
openapi: 3.1.0
info:
  title: Sequency Graph API
  description: >

    # Sequency Graph-Native Trading API


    Graph-native API for trading intelligence, built on FalkorDB.


    ## Features


    - **Screener**: Filter stocks using graph-native queries with relationship
    expansion

    - **Stock Detail**: Complete stock context with all relationships

    - **Confluence Scoring**: Setup quality assessment with weighted components

    - **Strategy Matching**: Find matching options strategies via graph
    traversal

    - **Market Context**: Current market-wide context for trading decisions


    ## Data Sources


    All data is sourced from the FalkorDB knowledge graph, populated by:

    - Pattern detector (Go) - Technical indicators, patterns

    - Graph sync service - Levels, volume profiles, news, day classification
  version: 1.0.0
servers: []
security: []
paths:
  /api/graph/v1/analysis/analogs:
    post:
      tags:
        - Analysis
      summary: Historical analogs as analog_overlay annotations for the chart lab
      operationId: analogs_api_graph_v1_analysis_analogs_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalogsRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalogPathsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    AnalogsRequest:
      properties:
        symbol:
          type: string
          title: Symbol
          description: Ticker symbol (uppercased; [A-Z0-9.-]{1,10})
        anchor_time:
          type: integer
          maximum: 4102444800
          exclusiveMinimum: 0
          title: Anchor Time
          description: Overlay anchor time (unix seconds)
        anchor_price:
          type: number
          maximum: 1000000000000
          exclusiveMinimum: 0
          title: Anchor Price
          description: Overlay anchor price (finite, > 0)
        limit:
          type: integer
          maximum: 20
          minimum: 1
          title: Limit
          description: Max analogs to return
          default: 5
        outcome:
          anyOf:
            - type: string
              enum:
                - win
                - loss
                - scratch
            - type: 'null'
          title: Outcome
          description: Optional outcome filter for historical_setups
        descriptor:
          anyOf:
            - $ref: '#/components/schemas/PriceActionDescriptor'
            - type: 'null'
          description: Bounded summary of the visible or selected price-action window
        match_window_bars:
          type: integer
          maximum: 100
          minimum: 3
          title: Match Window Bars
          description: Observed source bars ending at the exact match anchor
          default: 20
        forward_bars:
          type: integer
          maximum: 50
          minimum: 1
          title: Forward Bars
          description: Bounded observed source bars after the exact match anchor
          default: 20
      type: object
      required:
        - symbol
        - anchor_time
        - anchor_price
      title: AnalogsRequest
      description: >-
        Request for historical analogs anchored at a single chart point.


        ``anchor_time`` / ``anchor_price`` are the ONLY client-influenced
        annotation

        fields (provenance is server-owned); both are validated here. ``symbol``
        is

        the paid-embedding input, so it is capped hard.
    AnalogPathsResponse:
      properties:
        schema_version:
          type: string
          const: an03-v1
          title: Schema Version
        producer:
          $ref: '#/components/schemas/AnalogPathProducer'
        current_symbol:
          type: string
          minLength: 1
          pattern: ^[A-Z][A-Z0-9.-]*$
          title: Current Symbol
        interval:
          type: string
          const: 1m
          title: Interval
        session:
          type: string
          const: regular
          title: Session
        computed_at:
          type: string
          format: date-time
          title: Computed At
        match_window_bars:
          type: integer
          maximum: 100
          minimum: 3
          title: Match Window Bars
        forward_bars:
          type: integer
          maximum: 50
          minimum: 1
          title: Forward Bars
        top_k:
          type: integer
          maximum: 5
          minimum: 1
          title: Top K
        data_mode:
          type: string
          const: historical
          title: Data Mode
        availability:
          type: string
          enum:
            - available
            - partial
            - unavailable
          title: Availability
        truncated:
          type: boolean
          title: Truncated
        explanation:
          type: string
          title: Explanation
        annotations:
          items:
            $ref: '#/components/schemas/ChartAnnotationOut'
          type: array
          title: Annotations
        paths:
          items:
            $ref: '#/components/schemas/HistoricalAnalogPath'
          type: array
          maxItems: 5
          title: Paths
      additionalProperties: false
      type: object
      required:
        - schema_version
        - producer
        - current_symbol
        - interval
        - session
        - computed_at
        - match_window_bars
        - forward_bars
        - top_k
        - data_mode
        - availability
        - truncated
        - explanation
        - annotations
        - paths
      title: AnalogPathsResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PriceActionDescriptor:
      properties:
        bars:
          type: integer
          maximum: 500
          minimum: 1
          title: Bars
        interval_seconds:
          type: integer
          maximum: 604800
          minimum: 1
          title: Interval Seconds
        return_pct:
          type: number
          maximum: 1000
          minimum: -1000
          title: Return Pct
        range_pct:
          type: number
          maximum: 1000
          minimum: 0
          title: Range Pct
        close_location:
          type: number
          maximum: 1
          minimum: 0
          title: Close Location
        realized_bar_vol_pct:
          type: number
          maximum: 1000
          minimum: 0
          title: Realized Bar Vol Pct
      type: object
      required:
        - bars
        - interval_seconds
        - return_pct
        - range_pct
        - close_location
        - realized_bar_vol_pct
      title: PriceActionDescriptor
      description: |-
        Bounded numerical summary of the visible/selected chart bars.

        This is deliberately structured rather than an arbitrary client-supplied
        prompt: the paid embedding input stays small and predictable while the
        search is grounded in the setup the user actually selected.
    AnalogPathProducer:
      properties:
        id:
          type: string
          const: analogs:qdrant+market-data
          title: Id
        kind:
          type: string
          const: model
          title: Kind
        version:
          type: string
          const: an03-v1
          title: Version
      additionalProperties: false
      type: object
      required:
        - id
        - kind
        - version
      title: AnalogPathProducer
    ChartAnnotationOut:
      properties:
        kind:
          type: string
          enum:
            - trendline
            - zone
            - pattern_region
            - level_marker
            - analog_overlay
            - note
            - order_proposal
          title: Kind
        anchors:
          items:
            $ref: '#/components/schemas/AnchorPoint'
          type: array
          minItems: 1
          title: Anchors
        label:
          anyOf:
            - type: string
            - type: 'null'
          title: Label
        body:
          anyOf:
            - type: string
            - type: 'null'
          title: Body
        confidence:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Confidence
        provenance:
          $ref: '#/components/schemas/AnnotationProvenance'
      type: object
      required:
        - kind
        - anchors
        - provenance
      title: ChartAnnotationOut
    HistoricalAnalogPath:
      properties:
        id:
          type: string
          minLength: 1
          title: Id
        revision:
          type: integer
          minimum: 1
          title: Revision
        rank:
          type: integer
          maximum: 5
          minimum: 1
          title: Rank
        source_match_id:
          type: string
          minLength: 1
          title: Source Match Id
        source_symbol:
          type: string
          minLength: 1
          pattern: ^[A-Z][A-Z0-9.-]*$
          title: Source Symbol
        source_interval:
          anyOf:
            - type: string
              const: 1m
            - type: 'null'
          title: Source Interval
        source_session:
          anyOf:
            - type: string
              const: regular
            - type: 'null'
          title: Source Session
        source_window:
          anyOf:
            - $ref: '#/components/schemas/AnalogSourceWindow'
            - type: 'null'
        source_anchor_time:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Source Anchor Time
        match_score:
          type: number
          maximum: 1
          minimum: 0
          title: Match Score
        finality:
          type: string
          enum:
            - final
            - revised
          title: Finality
        availability:
          type: string
          enum:
            - available
            - partial
            - unavailable
          title: Availability
        unavailable_reason:
          anyOf:
            - type: string
              enum:
                - summary_only_match
                - insufficient_trajectory
                - missing_anchor
                - trajectory_unavailable
                - trajectory_provider_failed
                - invalid_trajectory
                - data_rights
            - type: 'null'
          title: Unavailable Reason
        data_rights:
          $ref: '#/components/schemas/AnalogDataRights'
        normalization:
          anyOf:
            - $ref: '#/components/schemas/AnalogNormalization'
            - type: 'null'
        outcome:
          anyOf:
            - $ref: '#/components/schemas/AnalogOutcome'
            - type: 'null'
        truncated:
          type: boolean
          title: Truncated
        points:
          items:
            $ref: '#/components/schemas/AnalogSourcePoint'
          type: array
          title: Points
        gaps:
          items:
            $ref: '#/components/schemas/AnalogPathGap'
          type: array
          title: Gaps
      additionalProperties: false
      type: object
      required:
        - id
        - revision
        - rank
        - source_match_id
        - source_symbol
        - source_interval
        - source_session
        - source_window
        - source_anchor_time
        - match_score
        - finality
        - availability
        - unavailable_reason
        - data_rights
        - normalization
        - outcome
        - truncated
        - points
        - gaps
      title: HistoricalAnalogPath
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    AnchorPoint:
      properties:
        time:
          type: integer
          title: Time
        price:
          type: number
          maximum: 1000000000000
          minimum: -1000000000000
          title: Price
      type: object
      required:
        - time
        - price
      title: AnchorPoint
    AnnotationProvenance:
      properties:
        agent:
          type: string
          title: Agent
        created_at:
          type: string
          title: Created At
        confidence:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Confidence
        analysis_ref:
          type: string
          title: Analysis Ref
      type: object
      required:
        - agent
        - created_at
        - analysis_ref
      title: AnnotationProvenance
    AnalogSourceWindow:
      properties:
        from_time:
          type: string
          format: date-time
          title: From Time
        to_time:
          type: string
          format: date-time
          title: To Time
      additionalProperties: false
      type: object
      required:
        - from_time
        - to_time
      title: AnalogSourceWindow
    AnalogDataRights:
      properties:
        status:
          type: string
          enum:
            - allowed
            - redacted
          title: Status
        entitlement:
          type: string
          const: ai_chart
          title: Entitlement
        use:
          type: string
          const: chart_display_only
          title: Use
        redistribution:
          type: boolean
          const: false
          title: Redistribution
        reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Reason
      additionalProperties: false
      type: object
      required:
        - status
        - entitlement
        - use
        - redistribution
      title: AnalogDataRights
    AnalogNormalization:
      properties:
        method:
          type: string
          const: backward_split_adjusted_close_return
          title: Method
        version:
          type: string
          const: an03-v1
          title: Version
        base_source_close:
          type: number
          exclusiveMinimum: 0
          title: Base Source Close
        current_anchor_price:
          type: number
          exclusiveMinimum: 0
          title: Current Anchor Price
      additionalProperties: false
      type: object
      required:
        - method
        - version
        - base_source_close
        - current_anchor_price
      title: AnalogNormalization
    AnalogOutcome:
      properties:
        classification:
          type: string
          enum:
            - win
            - loss
            - scratch
          title: Classification
        return_pct:
          type: number
          title: Return Pct
        hold_days:
          type: number
          minimum: 0
          title: Hold Days
        source:
          type: string
          minLength: 1
          title: Source
        finality:
          type: string
          const: final
          title: Finality
      additionalProperties: false
      type: object
      required:
        - classification
        - return_pct
        - hold_days
        - source
        - finality
      title: AnalogOutcome
    AnalogSourcePoint:
      properties:
        id:
          type: string
          minLength: 1
          title: Id
        time:
          type: string
          format: date-time
          title: Time
        session_date:
          type: string
          format: date
          title: Session Date
        source_revision:
          type: integer
          minimum: 1
          title: Source Revision
        finality:
          type: string
          enum:
            - final
            - revised
          title: Finality
        raw_open:
          type: number
          exclusiveMinimum: 0
          title: Raw Open
        raw_high:
          type: number
          exclusiveMinimum: 0
          title: Raw High
        raw_low:
          type: number
          exclusiveMinimum: 0
          title: Raw Low
        raw_close:
          type: number
          exclusiveMinimum: 0
          title: Raw Close
        volume:
          type: integer
          minimum: 0
          title: Volume
        adjustment_factor:
          type: number
          exclusiveMinimum: 0
          title: Adjustment Factor
        adjusted_open:
          type: number
          exclusiveMinimum: 0
          title: Adjusted Open
        adjusted_high:
          type: number
          exclusiveMinimum: 0
          title: Adjusted High
        adjusted_low:
          type: number
          exclusiveMinimum: 0
          title: Adjusted Low
        adjusted_close:
          type: number
          exclusiveMinimum: 0
          title: Adjusted Close
        normalized_close_return:
          type: number
          title: Normalized Close Return
        ordinal:
          type: integer
          title: Ordinal
        segment:
          type: integer
          minimum: 0
          title: Segment
      additionalProperties: false
      type: object
      required:
        - id
        - time
        - session_date
        - source_revision
        - finality
        - raw_open
        - raw_high
        - raw_low
        - raw_close
        - volume
        - adjustment_factor
        - adjusted_open
        - adjusted_high
        - adjusted_low
        - adjusted_close
        - normalized_close_return
        - ordinal
        - segment
      title: AnalogSourcePoint
    AnalogPathGap:
      properties:
        from_time:
          type: string
          format: date-time
          title: From Time
        to_time:
          type: string
          format: date-time
          title: To Time
        reason:
          type: string
          enum:
            - session_break
            - missing_source_bar
          title: Reason
      additionalProperties: false
      type: object
      required:
        - from_time
        - to_time
        - reason
      title: AnalogPathGap

````