openapi.yaml

components:
  schemas:
    AgentResponse:
      properties:
        channel:
          title: Channel
          type: string
        content:
          additionalProperties: true
          title: Content
          type: object
        entity_id:
          title: Entity Id
          type: string
        entity_type:
          const: agent
          default: agent
          title: Entity Type
          type: string
        etag:
          title: Etag
          type: string
        meta:
          additionalProperties: true
          title: Meta
          type: object
        version_id:
          title: Version Id
          type: string
      required:
      - entity_id
      - version_id
      - channel
      - etag
      - meta
      - content
      title: AgentResponse
      type: object
    BatchSearchRequest:
      description: Request for batch search.
      properties:
        channel:
          default: latest
          description: Version channel to search
          title: Channel
          type: string
        entity_type:
          default: memory_card
          description: Type of entity to search
          title: Entity Type
          type: string
        hybrid_weights:
          default:
          - 0.5
          - 0.5
          maxItems: 2
          minItems: 2
          prefixItems:
          - type: number
          - type: number
          title: Hybrid Weights
          type: array
        namespace:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by namespace
          title: Namespace
        queries:
          description: List of search queries
          items:
            type: string
          maxItems: 50
          minItems: 1
          title: Queries
          type: array
        query_vectors:
          anyOf:
          - items:
              items:
                type: number
              type: array
            type: array
          - type: 'null'
          description: Pre-computed embedding vectors for vector search
          title: Query Vectors
        search_type:
          $ref: '#/components/schemas/SearchType'
          default: bm25
          description: Type of search
        tags:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          description: Filter by tags
          title: Tags
        top_k:
          default: 10
          description: Number of top results per query
          maximum: 100.0
          minimum: 1.0
          title: Top K
          type: integer
      required:
      - queries
      title: BatchSearchRequest
      type: object
    BatchSearchResponseModel:
      description: Response for batch search.
      properties:
        results:
          items:
            items:
              $ref: '#/components/schemas/SearchHit'
            type: array
          title: Results
          type: array
        search_type:
          $ref: '#/components/schemas/SearchType'
        total_queries:
          title: Total Queries
          type: integer
      required:
      - results
      - search_type
      - total_queries
      title: BatchSearchResponseModel
      type: object
    ChainResponse:
      properties:
        channel:
          title: Channel
          type: string
        content:
          additionalProperties: true
          title: Content
          type: object
        entity_id:
          title: Entity Id
          type: string
        entity_type:
          const: chain
          default: chain
          title: Entity Type
          type: string
        etag:
          title: Etag
          type: string
        meta:
          additionalProperties: true
          title: Meta
          type: object
        version_id:
          title: Version Id
          type: string
      required:
      - entity_id
      - version_id
      - channel
      - etag
      - meta
      - content
      title: ChainResponse
      type: object
    DiffResponse:
      properties:
        from_version:
          title: From Version
          type: string
        patch:
          additionalProperties: true
          title: Patch
          type: object
        to_version:
          title: To Version
          type: string
      required:
      - from_version
      - to_version
      - patch
      title: DiffResponse
      type: object
    EmbeddingsRequest:
      description: Request for text embeddings.
      properties:
        model:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional override of the default model
          title: Model
        texts:
          description: List of text strings to embed
          items:
            type: string
          maxItems: 100
          minItems: 1
          title: Texts
          type: array
      required:
      - texts
      title: EmbeddingsRequest
      type: object
    EmbeddingsResponse:
      description: Response with text embeddings.
      properties:
        dimension:
          description: Dimension of embedding vectors
          title: Dimension
          type: integer
        embeddings:
          description: List of embedding vectors, one per input text
          items:
            items:
              type: number
            type: array
          title: Embeddings
          type: array
        model:
          description: Model name used for embedding
          title: Model
          type: string
      required:
      - embeddings
      - model
      - dimension
      title: EmbeddingsResponse
      type: object
    EntityCreateRequest:
      properties:
        channel:
          default: latest
          title: Channel
          type: string
        content:
          additionalProperties: true
          title: Content
          type: object
        embedding:
          anyOf:
          - items:
              type: number
            type: array
          - type: 'null'
          title: Embedding
        evolution_meta:
          anyOf:
          - $ref: '#/components/schemas/EvolutionMeta'
          - type: 'null'
        meta:
          $ref: '#/components/schemas/EntityMeta'
        parent_version_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Parent Version Id
      required:
      - meta
      - content
      title: EntityCreateRequest
      type: object
    EntityMeta:
      properties:
        author:
          anyOf:
          - type: string
          - type: 'null'
          title: Author
        name:
          maxLength: 255
          minLength: 1
          title: Name
          type: string
        namespace:
          anyOf:
          - type: string
          - type: 'null'
          title: Namespace
        tags:
          items:
            type: string
          title: Tags
          type: array
        when_to_use:
          anyOf:
          - type: string
          - type: 'null'
          title: When To Use
      required:
      - name
      title: EntityMeta
      type: object
    EntityResponse:
      properties:
        channel:
          title: Channel
          type: string
        content:
          additionalProperties: true
          title: Content
          type: object
        entity_id:
          title: Entity Id
          type: string
        entity_type:
          title: Entity Type
          type: string
        etag:
          title: Etag
          type: string
        meta:
          additionalProperties: true
          title: Meta
          type: object
        version_id:
          title: Version Id
          type: string
      required:
      - entity_type
      - entity_id
      - version_id
      - channel
      - etag
      - meta
      - content
      title: EntityResponse
      type: object
    EntityUpdateRequest:
      properties:
        change_summary:
          anyOf:
          - type: string
          - type: 'null'
          title: Change Summary
        channel:
          default: latest
          title: Channel
          type: string
        content:
          additionalProperties: true
          title: Content
          type: object
        embedding:
          anyOf:
          - items:
              type: number
            type: array
          - type: 'null'
          title: Embedding
        evolution_meta:
          anyOf:
          - $ref: '#/components/schemas/EvolutionMeta'
          - type: 'null'
        meta:
          anyOf:
          - $ref: '#/components/schemas/EntityMeta'
          - type: 'null'
        parent_version_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Parent Version Id
      required:
      - content
      title: EntityUpdateRequest
      type: object
    EvolutionMeta:
      properties:
        behavioral_descriptors:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Behavioral Descriptors
        fitness:
          anyOf:
          - type: number
          - type: 'null'
          title: Fitness
        is_valid:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Valid
        metrics:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metrics
        mutation_kind:
          anyOf:
          - type: string
          - type: 'null'
          title: Mutation Kind
        prompt_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Prompt Ref
      title: EvolutionMeta
      type: object
    FacetsResponse:
      properties:
        authors:
          additionalProperties:
            type: integer
          title: Authors
          type: object
        entity_types:
          additionalProperties:
            type: integer
          title: Entity Types
          type: object
        namespaces:
          additionalProperties:
            type: integer
          title: Namespaces
          type: object
        tags:
          additionalProperties:
            type: integer
          title: Tags
          type: object
      title: FacetsResponse
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    MemoryCardResponse:
      properties:
        channel:
          title: Channel
          type: string
        content:
          additionalProperties: true
          title: Content
          type: object
        entity_id:
          title: Entity Id
          type: string
        entity_type:
          const: memory_card
          default: memory_card
          title: Entity Type
          type: string
        etag:
          title: Etag
          type: string
        meta:
          additionalProperties: true
          title: Meta
          type: object
        version_id:
          title: Version Id
          type: string
      required:
      - entity_id
      - version_id
      - channel
      - etag
      - meta
      - content
      title: MemoryCardResponse
      type: object
    PinRequest:
      properties:
        channel:
          title: Channel
          type: string
        version_id:
          title: Version Id
          type: string
      required:
      - channel
      - version_id
      title: PinRequest
      type: object
    PromoteRequest:
      properties:
        from_channel:
          default: latest
          title: From Channel
          type: string
        to_channel:
          default: stable
          title: To Channel
          type: string
      title: PromoteRequest
      type: object
    RevertRequest:
      properties:
        target_version_id:
          title: Target Version Id
          type: string
      required:
      - target_version_id
      title: RevertRequest
      type: object
    SearchHit:
      properties:
        channel:
          anyOf:
          - type: string
          - type: 'null'
          title: Channel
        content:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Content
        entity_id:
          title: Entity Id
          type: string
        entity_type:
          title: Entity Type
          type: string
        name:
          title: Name
          type: string
        score:
          default: 0.0
          title: Score
          type: number
        tags:
          items:
            type: string
          title: Tags
          type: array
        version_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Version Id
        when_to_use:
          anyOf:
          - type: string
          - type: 'null'
          title: When To Use
      required:
      - entity_id
      - entity_type
      - name
      title: SearchHit
      type: object
    SearchType:
      description: Search algorithm type.
      enum:
      - bm25
      - vector
      - hybrid
      title: SearchType
      type: string
    StepResponse:
      properties:
        channel:
          title: Channel
          type: string
        content:
          additionalProperties: true
          title: Content
          type: object
        entity_id:
          title: Entity Id
          type: string
        entity_type:
          const: step
          default: step
          title: Entity Type
          type: string
        etag:
          title: Etag
          type: string
        meta:
          additionalProperties: true
          title: Meta
          type: object
        version_id:
          title: Version Id
          type: string
      required:
      - entity_id
      - version_id
      - channel
      - etag
      - meta
      - content
      title: StepResponse
      type: object
    UnifiedSearchRequest:
      description: Request for unified search (BM25, vector, or hybrid).
      properties:
        channel:
          default: latest
          description: Version channel to search
          title: Channel
          type: string
        entity_type:
          default: memory_card
          description: Type of entity to search
          title: Entity Type
          type: string
        hybrid_weights:
          default:
          - 0.5
          - 0.5
          description: (bm25_weight, vector_weight) for hybrid search, must sum to
            1.0
          maxItems: 2
          minItems: 2
          prefixItems:
          - type: number
          - type: number
          title: Hybrid Weights
          type: array
        namespace:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by namespace
          title: Namespace
        query:
          anyOf:
          - type: string
          - type: 'null'
          description: Text query for BM25 or hybrid search
          title: Query
        query_vector:
          anyOf:
          - items:
              type: number
            type: array
          - type: 'null'
          description: Pre-computed embedding vector for vector search
          title: Query Vector
        search_type:
          $ref: '#/components/schemas/SearchType'
          default: bm25
          description: 'Type of search: ''bm25'', ''vector'', or ''hybrid'''
        tags:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          description: Filter by tags
          title: Tags
        top_k:
          default: 10
          description: Number of top results to return
          maximum: 100.0
          minimum: 1.0
          title: Top K
          type: integer
      title: UnifiedSearchRequest
      type: object
    UnifiedSearchResponse:
      description: Response for unified search (BM25 or vector).
      properties:
        hits:
          items:
            $ref: '#/components/schemas/SearchHit'
          title: Hits
          type: array
        search_type:
          description: Type of search performed (bm25 or vector)
          title: Search Type
          type: string
        total:
          description: Total number of hits returned
          title: Total
          type: integer
      required:
      - search_type
      - total
      title: UnifiedSearchResponse
      type: object
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
      - loc
      - msg
      - type
      title: ValidationError
      type: object
    VersionDetail:
      properties:
        author:
          anyOf:
          - type: string
          - type: 'null'
          title: Author
        change_summary:
          anyOf:
          - type: string
          - type: 'null'
          title: Change Summary
        content:
          additionalProperties: true
          title: Content
          type: object
        created_at:
          format: date-time
          title: Created At
          type: string
        entity_id:
          title: Entity Id
          type: string
        evolution_meta:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Evolution Meta
        meta:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Meta
        parents:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Parents
        version_id:
          title: Version Id
          type: string
        version_number:
          title: Version Number
          type: integer
      required:
      - version_id
      - entity_id
      - version_number
      - created_at
      - content
      title: VersionDetail
      type: object
    VersionInfo:
      properties:
        author:
          anyOf:
          - type: string
          - type: 'null'
          title: Author
        change_summary:
          anyOf:
          - type: string
          - type: 'null'
          title: Change Summary
        created_at:
          format: date-time
          title: Created At
          type: string
        entity_id:
          title: Entity Id
          type: string
        evolution_meta:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Evolution Meta
        parents:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Parents
        version_id:
          title: Version Id
          type: string
        version_number:
          title: Version Number
          type: integer
      required:
      - version_id
      - entity_id
      - version_number
      - created_at
      title: VersionInfo
      type: object
info:
  description: 'Persistent memory for CARL artifacts: steps, chains, agents, memory
    cards'
  title: GigaEvo Memory Module
  version: 0.1.0
openapi: 3.1.0
paths:
  /health:
    get:
      description: Check health of API and all dependencies.
      operationId: health_check_health_get
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful Response
      summary: Health Check
  /metrics:
    get:
      description: Prometheus-compatible metrics stub.
      operationId: metrics_metrics_get
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful Response
      summary: Metrics
  /v1/agents:
    get:
      description: List all agents with pagination.
      operationId: list_agents_v1_agents_get
      parameters:
      - in: query
        name: limit
        required: false
        schema:
          default: 50
          title: Limit
          type: integer
      - in: query
        name: offset
        required: false
        schema:
          default: 0
          title: Offset
          type: integer
      - in: query
        name: channel
        required: false
        schema:
          default: latest
          title: Channel
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/AgentResponse'
                title: Response List Agents V1 Agents Get
                type: array
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: List Agents
      tags:
      - agents
    post:
      description: Create a new agent entity with its first version.
      operationId: create_agent_v1_agents_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityCreateRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Create Agent
      tags:
      - agents
  /v1/agents/{agent_id}:
    delete:
      description: Soft-delete an agent.
      operationId: delete_agent_v1_agents__agent_id__delete
      parameters:
      - in: path
        name: agent_id
        required: true
        schema:
          format: uuid
          title: Agent Id
          type: string
      responses:
        '204':
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Delete Agent
      tags:
      - agents
    get:
      description: Get an agent by ID, resolving the channel to a specific version.
      operationId: get_agent_v1_agents__agent_id__get
      parameters:
      - in: path
        name: agent_id
        required: true
        schema:
          format: uuid
          title: Agent Id
          type: string
      - in: query
        name: channel
        required: false
        schema:
          default: latest
          title: Channel
          type: string
      - in: header
        name: if-none-match
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: If-None-Match
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get Agent
      tags:
      - agents
    put:
      description: Update an agent by creating a new immutable version.
      operationId: update_agent_v1_agents__agent_id__put
      parameters:
      - in: path
        name: agent_id
        required: true
        schema:
          format: uuid
          title: Agent Id
          type: string
      - in: header
        name: if-match
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: If-Match
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityUpdateRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Update Agent
      tags:
      - agents
  /v1/agents/{agent_id}/versions:
    get:
      description: List all versions of an agent with pagination.
      operationId: list_agent_versions_v1_agents__agent_id__versions_get
      parameters:
      - in: path
        name: agent_id
        required: true
        schema:
          format: uuid
          title: Agent Id
          type: string
      - in: query
        name: limit
        required: false
        schema:
          default: 20
          maximum: 100
          minimum: 1
          title: Limit
          type: integer
      - in: query
        name: offset
        required: false
        schema:
          default: 0
          minimum: 0
          title: Offset
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/VersionInfo'
                title: Response List Agent Versions V1 Agents  Agent Id  Versions
                  Get
                type: array
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: List Agent Versions
      tags:
      - versions
  /v1/agents/{agent_id}/versions/{version_id}:
    get:
      description: Get a specific agent version with its content.
      operationId: get_agent_version_v1_agents__agent_id__versions__version_id__get
      parameters:
      - in: path
        name: agent_id
        required: true
        schema:
          format: uuid
          title: Agent Id
          type: string
      - in: path
        name: version_id
        required: true
        schema:
          format: uuid
          title: Version Id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionDetail'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get Agent Version
      tags:
      - versions
  /v1/chains:
    get:
      description: List all chains with pagination.
      operationId: list_chains_v1_chains_get
      parameters:
      - in: query
        name: limit
        required: false
        schema:
          default: 50
          title: Limit
          type: integer
      - in: query
        name: offset
        required: false
        schema:
          default: 0
          title: Offset
          type: integer
      - in: query
        name: channel
        required: false
        schema:
          default: latest
          title: Channel
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ChainResponse'
                title: Response List Chains V1 Chains Get
                type: array
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: List Chains
      tags:
      - chains
    post:
      description: Create a new chain entity with its first version.
      operationId: create_chain_v1_chains_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityCreateRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChainResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Create Chain
      tags:
      - chains
  /v1/chains/{chain_id}:
    delete:
      description: Soft-delete a chain.
      operationId: delete_chain_v1_chains__chain_id__delete
      parameters:
      - in: path
        name: chain_id
        required: true
        schema:
          format: uuid
          title: Chain Id
          type: string
      responses:
        '204':
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Delete Chain
      tags:
      - chains
    get:
      description: Get a chain by ID, resolving the channel to a specific version.
      operationId: get_chain_v1_chains__chain_id__get
      parameters:
      - in: path
        name: chain_id
        required: true
        schema:
          format: uuid
          title: Chain Id
          type: string
      - in: query
        name: channel
        required: false
        schema:
          default: latest
          title: Channel
          type: string
      - in: header
        name: if-none-match
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: If-None-Match
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChainResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get Chain
      tags:
      - chains
    put:
      description: Update a chain by creating a new immutable version.
      operationId: update_chain_v1_chains__chain_id__put
      parameters:
      - in: path
        name: chain_id
        required: true
        schema:
          format: uuid
          title: Chain Id
          type: string
      - in: header
        name: if-match
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: If-Match
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityUpdateRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChainResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Update Chain
      tags:
      - chains
  /v1/chains/{chain_id}/versions:
    get:
      description: List all versions of a chain with pagination.
      operationId: list_chain_versions_v1_chains__chain_id__versions_get
      parameters:
      - in: path
        name: chain_id
        required: true
        schema:
          format: uuid
          title: Chain Id
          type: string
      - in: query
        name: limit
        required: false
        schema:
          default: 20
          maximum: 100
          minimum: 1
          title: Limit
          type: integer
      - in: query
        name: offset
        required: false
        schema:
          default: 0
          minimum: 0
          title: Offset
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/VersionInfo'
                title: Response List Chain Versions V1 Chains  Chain Id  Versions
                  Get
                type: array
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: List Chain Versions
      tags:
      - versions
  /v1/chains/{chain_id}/versions/{version_id}:
    get:
      description: Get a specific chain version with its content.
      operationId: get_chain_version_v1_chains__chain_id__versions__version_id__get
      parameters:
      - in: path
        name: chain_id
        required: true
        schema:
          format: uuid
          title: Chain Id
          type: string
      - in: path
        name: version_id
        required: true
        schema:
          format: uuid
          title: Version Id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionDetail'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get Chain Version
      tags:
      - versions
  /v1/embeddings:
    post:
      description: "Generate embeddings for text inputs.\n\nThis endpoint uses the\
        \ configured embedding provider to generate\nvector embeddings for the input\
        \ texts. Supports batch processing\nfor efficiency.\n\nExample request:\n\
        \    {\n        \"texts\": [\"Hello world\", \"Search query\"],\n        \"\
        model\": \"all-MiniLM-L6-v2\"  // optional\n    }\n\nExample response:\n \
        \   {\n        \"embeddings\": [[0.1, 0.2, ...], [0.3, 0.4, ...]],\n     \
        \   \"model\": \"all-MiniLM-L6-v2\",\n        \"dimension\": 384\n    }\n\n\
        Raises:\n    503: If embedding service is not available"
      operationId: create_embeddings_v1_embeddings_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmbeddingsRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmbeddingsResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Create Embeddings
      tags:
      - search
  /v1/events/stream:
    get:
      description: Server-Sent Events stream for entity change notifications.
      operationId: event_stream_v1_events_stream_get
      parameters:
      - in: query
        name: entity_type
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Entity Type
      - in: query
        name: entity_id
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Entity Id
      - in: query
        name: namespace
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Namespace
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Event Stream
      tags:
      - events
  /v1/maintenance/clear-all:
    post:
      description: "Soft-delete all entities, optionally filtered by type.\n\nArgs:\n\
        \    entity_type: Optional entity type to clear (step, chain, agent, memory_card).\n\
        \                 If not provided, clears all entity types.\n\nReturns:\n\
        \    Dictionary with counts of deleted entities per type."
      operationId: clear_all_entities_v1_maintenance_clear_all_post
      parameters:
      - in: query
        name: entity_type
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Entity Type
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Clear All Entities
      tags:
      - entities (deprecated)
  /v1/memory-cards:
    get:
      description: List all memory cards with pagination.
      operationId: list_memory_cards_v1_memory_cards_get
      parameters:
      - in: query
        name: limit
        required: false
        schema:
          default: 50
          title: Limit
          type: integer
      - in: query
        name: offset
        required: false
        schema:
          default: 0
          title: Offset
          type: integer
      - in: query
        name: channel
        required: false
        schema:
          default: latest
          title: Channel
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/MemoryCardResponse'
                title: Response List Memory Cards V1 Memory Cards Get
                type: array
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: List Memory Cards
      tags:
      - memory_cards
    post:
      description: Create a new memory card entity with its first version.
      operationId: create_memory_card_v1_memory_cards_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityCreateRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemoryCardResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Create Memory Card
      tags:
      - memory_cards
  /v1/memory-cards/{memory_card_id}:
    delete:
      description: Soft-delete a memory card.
      operationId: delete_memory_card_v1_memory_cards__memory_card_id__delete
      parameters:
      - in: path
        name: memory_card_id
        required: true
        schema:
          format: uuid
          title: Memory Card Id
          type: string
      responses:
        '204':
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Delete Memory Card
      tags:
      - memory_cards
    get:
      description: Get a memory card by ID, resolving the channel to a specific version.
      operationId: get_memory_card_v1_memory_cards__memory_card_id__get
      parameters:
      - in: path
        name: memory_card_id
        required: true
        schema:
          format: uuid
          title: Memory Card Id
          type: string
      - in: query
        name: channel
        required: false
        schema:
          default: latest
          title: Channel
          type: string
      - in: header
        name: if-none-match
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: If-None-Match
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemoryCardResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get Memory Card
      tags:
      - memory_cards
    put:
      description: Update a memory card by creating a new immutable version.
      operationId: update_memory_card_v1_memory_cards__memory_card_id__put
      parameters:
      - in: path
        name: memory_card_id
        required: true
        schema:
          format: uuid
          title: Memory Card Id
          type: string
      - in: header
        name: if-match
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: If-Match
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityUpdateRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemoryCardResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Update Memory Card
      tags:
      - memory_cards
  /v1/memory-cards/{memory_card_id}/versions:
    get:
      description: List all versions of a memory card with pagination.
      operationId: list_memory_card_versions_v1_memory_cards__memory_card_id__versions_get
      parameters:
      - in: path
        name: memory_card_id
        required: true
        schema:
          format: uuid
          title: Memory Card Id
          type: string
      - in: query
        name: limit
        required: false
        schema:
          default: 20
          maximum: 100
          minimum: 1
          title: Limit
          type: integer
      - in: query
        name: offset
        required: false
        schema:
          default: 0
          minimum: 0
          title: Offset
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/VersionInfo'
                title: Response List Memory Card Versions V1 Memory Cards  Memory
                  Card Id  Versions Get
                type: array
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: List Memory Card Versions
      tags:
      - versions
  /v1/memory-cards/{memory_card_id}/versions/{version_id}:
    get:
      description: Get a specific memory card version with its content.
      operationId: get_memory_card_version_v1_memory_cards__memory_card_id__versions__version_id__get
      parameters:
      - in: path
        name: memory_card_id
        required: true
        schema:
          format: uuid
          title: Memory Card Id
          type: string
      - in: path
        name: version_id
        required: true
        schema:
          format: uuid
          title: Version Id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionDetail'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get Memory Card Version
      tags:
      - versions
  /v1/search/batch:
    post:
      description: "Batch search for multiple queries.\n\nEfficiently processes multiple\
        \ queries in parallel using asyncio.gather.\nReturns a list of result lists,\
        \ one per query.\n\nExample request:\n    {\n        \"search_type\": \"hybrid\"\
        ,\n        \"queries\": [\"financial analysis\", \"code review\", \"documentation\"\
        ],\n        \"top_k\": 5,\n        \"entity_type\": \"memory_card\",\n   \
        \     \"hybrid_weights\": [0.4, 0.6]\n    }"
      operationId: batch_search_v1_search_batch_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchSearchRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchSearchResponseModel'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Batch Search
      tags:
      - search
  /v1/search/facets:
    get:
      description: 'Get aggregated facet counts for UI filters.


        Returns counts for:

        - entity_types: Number of entities per type

        - tags: Number of entities per tag

        - authors: Number of entities per author

        - namespaces: Number of entities per namespace'
      operationId: get_facets_v1_search_facets_get
      parameters:
      - description: Filter facets by namespace
        in: query
        name: namespace
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter facets by namespace
          title: Namespace
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FacetsResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get Facets
      tags:
      - search
  /v1/search/unified:
    post:
      description: "Unified search endpoint supporting BM25, vector, and hybrid search.\n\
        \nThis endpoint provides a single interface for three search types:\n- **bm25**:\
        \ Full-text search using PostgreSQL tsvector\n- **vector**: Semantic search\
        \ using pgvector similarity\n- **hybrid**: Combined BM25 + Vector scores with\
        \ configurable weights\n\nFor vector and hybrid search, embeddings can be\
        \ generated server-side\n(if ENABLE_VECTOR_SEARCH=true) or provided as pre-computed\
        \ vectors.\n\nExample BM25 request:\n    {\n        \"search_type\": \"bm25\"\
        ,\n        \"query\": \"financial analysis\",\n        \"top_k\": 10,\n  \
        \      \"entity_type\": \"memory_card\"\n    }\n\nExample vector request (server-side\
        \ embedding):\n    {\n        \"search_type\": \"vector\",\n        \"query\"\
        : \"semantic similarity\",\n        \"top_k\": 10,\n        \"entity_type\"\
        : \"memory_card\"\n    }\n\nExample hybrid request:\n    {\n        \"search_type\"\
        : \"hybrid\",\n        \"query\": \"analysis\",\n        \"hybrid_weights\"\
        : [0.3, 0.7],\n        \"top_k\": 10,\n        \"entity_type\": \"memory_card\"\
        \n    }\n\nExample vector request (client-side embedding):\n    {\n      \
        \  \"search_type\": \"vector\",\n        \"query_vector\": [0.1, 0.2, ...],\n\
        \        \"top_k\": 10,\n        \"entity_type\": \"memory_card\"\n    }"
      operationId: unified_search_v1_search_unified_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnifiedSearchRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnifiedSearchResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Unified Search
      tags:
      - search
  /v1/steps:
    get:
      description: List all steps with pagination.
      operationId: list_steps_v1_steps_get
      parameters:
      - in: query
        name: limit
        required: false
        schema:
          default: 50
          title: Limit
          type: integer
      - in: query
        name: offset
        required: false
        schema:
          default: 0
          title: Offset
          type: integer
      - in: query
        name: channel
        required: false
        schema:
          default: latest
          title: Channel
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/StepResponse'
                title: Response List Steps V1 Steps Get
                type: array
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: List Steps
      tags:
      - steps
    post:
      description: Create a new step entity with its first version.
      operationId: create_step_v1_steps_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityCreateRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StepResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Create Step
      tags:
      - steps
  /v1/steps/{step_id}:
    delete:
      description: Soft-delete a step.
      operationId: delete_step_v1_steps__step_id__delete
      parameters:
      - in: path
        name: step_id
        required: true
        schema:
          format: uuid
          title: Step Id
          type: string
      responses:
        '204':
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Delete Step
      tags:
      - steps
    get:
      description: Get a step by ID, resolving the channel to a specific version.
      operationId: get_step_v1_steps__step_id__get
      parameters:
      - in: path
        name: step_id
        required: true
        schema:
          format: uuid
          title: Step Id
          type: string
      - in: query
        name: channel
        required: false
        schema:
          default: latest
          title: Channel
          type: string
      - in: header
        name: if-none-match
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: If-None-Match
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StepResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get Step
      tags:
      - steps
    put:
      description: Update a step by creating a new immutable version.
      operationId: update_step_v1_steps__step_id__put
      parameters:
      - in: path
        name: step_id
        required: true
        schema:
          format: uuid
          title: Step Id
          type: string
      - in: header
        name: if-match
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: If-Match
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityUpdateRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StepResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Update Step
      tags:
      - steps
  /v1/steps/{step_id}/versions:
    get:
      description: List all versions of a step with pagination.
      operationId: list_step_versions_v1_steps__step_id__versions_get
      parameters:
      - in: path
        name: step_id
        required: true
        schema:
          format: uuid
          title: Step Id
          type: string
      - in: query
        name: limit
        required: false
        schema:
          default: 20
          maximum: 100
          minimum: 1
          title: Limit
          type: integer
      - in: query
        name: offset
        required: false
        schema:
          default: 0
          minimum: 0
          title: Offset
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/VersionInfo'
                title: Response List Step Versions V1 Steps  Step Id  Versions Get
                type: array
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: List Step Versions
      tags:
      - versions
  /v1/steps/{step_id}/versions/{version_id}:
    get:
      description: Get a specific step version with its content.
      operationId: get_step_version_v1_steps__step_id__versions__version_id__get
      parameters:
      - in: path
        name: step_id
        required: true
        schema:
          format: uuid
          title: Step Id
          type: string
      - in: path
        name: version_id
        required: true
        schema:
          format: uuid
          title: Version Id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionDetail'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get Step Version
      tags:
      - versions
  /v1/webhooks:
    post:
      description: Register a webhook (not yet implemented).
      operationId: create_webhook_v1_webhooks_post
      responses:
        '501':
          content:
            application/json:
              schema: {}
          description: Successful Response
      summary: Create Webhook
      tags:
      - events
  /v1/webhooks/{webhook_id}:
    delete:
      description: Delete a webhook (not yet implemented).
      operationId: delete_webhook_v1_webhooks__webhook_id__delete
      parameters:
      - in: path
        name: webhook_id
        required: true
        schema:
          title: Webhook Id
          type: string
      responses:
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        '501':
          content:
            application/json:
              schema: {}
          description: Successful Response
      summary: Delete Webhook
      tags:
      - events
  /v1/{entity_type}:
    post:
      description: Create a new entity with its first version.
      operationId: create_entity_v1__entity_type__post
      parameters:
      - in: path
        name: entity_type
        required: true
        schema:
          title: Entity Type
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityCreateRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Create Entity
      tags:
      - entities (deprecated)
  /v1/{entity_type}/{entity_id}:
    delete:
      description: Soft-delete an entity.
      operationId: delete_entity_v1__entity_type___entity_id__delete
      parameters:
      - in: path
        name: entity_type
        required: true
        schema:
          title: Entity Type
          type: string
      - in: path
        name: entity_id
        required: true
        schema:
          format: uuid
          title: Entity Id
          type: string
      responses:
        '204':
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Delete Entity
      tags:
      - entities (deprecated)
    get:
      description: Get an entity by ID, resolving the channel to a specific version.
      operationId: get_entity_v1__entity_type___entity_id__get
      parameters:
      - in: path
        name: entity_type
        required: true
        schema:
          title: Entity Type
          type: string
      - in: path
        name: entity_id
        required: true
        schema:
          format: uuid
          title: Entity Id
          type: string
      - in: query
        name: channel
        required: false
        schema:
          default: latest
          title: Channel
          type: string
      - in: header
        name: if-none-match
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: If-None-Match
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get Entity
      tags:
      - entities (deprecated)
    put:
      description: Update an entity by creating a new immutable version.
      operationId: update_entity_v1__entity_type___entity_id__put
      parameters:
      - in: path
        name: entity_type
        required: true
        schema:
          title: Entity Type
          type: string
      - in: path
        name: entity_id
        required: true
        schema:
          format: uuid
          title: Entity Id
          type: string
      - in: header
        name: if-match
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: If-Match
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityUpdateRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Update Entity
      tags:
      - entities (deprecated)
  /v1/{entity_type}/{entity_id}/diff:
    get:
      description: Compute a JSON patch between two versions.
      operationId: diff_versions_v1__entity_type___entity_id__diff_get
      parameters:
      - in: path
        name: entity_type
        required: true
        schema:
          title: Entity Type
          type: string
      - in: path
        name: entity_id
        required: true
        schema:
          format: uuid
          title: Entity Id
          type: string
      - in: query
        name: from
        required: true
        schema:
          format: uuid
          title: From
          type: string
      - in: query
        name: to
        required: true
        schema:
          format: uuid
          title: To
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiffResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Diff Versions
      tags:
      - versions
  /v1/{entity_type}/{entity_id}/pin:
    post:
      description: Pin a channel to a specific version.
      operationId: pin_channel_v1__entity_type___entity_id__pin_post
      parameters:
      - in: path
        name: entity_type
        required: true
        schema:
          title: Entity Type
          type: string
      - in: path
        name: entity_id
        required: true
        schema:
          format: uuid
          title: Entity Id
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PinRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Pin Channel
      tags:
      - versions
  /v1/{entity_type}/{entity_id}/promote:
    post:
      description: "Promote: copy one channel pointer to another (default: latest\
        \ \u2192 stable)."
      operationId: promote_v1__entity_type___entity_id__promote_post
      parameters:
      - in: path
        name: entity_type
        required: true
        schema:
          title: Entity Type
          type: string
      - in: path
        name: entity_id
        required: true
        schema:
          format: uuid
          title: Entity Id
          type: string
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/PromoteRequest'
              - type: 'null'
              title: Body
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Promote
      tags:
      - versions
  /v1/{entity_type}/{entity_id}/revert:
    post:
      description: 'Revert: create a new version with content from an old version.'
      operationId: revert_v1__entity_type___entity_id__revert_post
      parameters:
      - in: path
        name: entity_type
        required: true
        schema:
          title: Entity Type
          type: string
      - in: path
        name: entity_id
        required: true
        schema:
          format: uuid
          title: Entity Id
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RevertRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Revert
      tags:
      - versions
  /v1/{entity_type}/{entity_id}/versions:
    get:
      description: List all versions of an entity with pagination.
      operationId: list_versions_v1__entity_type___entity_id__versions_get
      parameters:
      - in: path
        name: entity_type
        required: true
        schema:
          title: Entity Type
          type: string
      - in: path
        name: entity_id
        required: true
        schema:
          format: uuid
          title: Entity Id
          type: string
      - in: query
        name: limit
        required: false
        schema:
          default: 20
          maximum: 100
          minimum: 1
          title: Limit
          type: integer
      - in: query
        name: offset
        required: false
        schema:
          default: 0
          minimum: 0
          title: Offset
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/VersionInfo'
                title: Response List Versions V1  Entity Type   Entity Id  Versions
                  Get
                type: array
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: List Versions
      tags:
      - versions
  /v1/{entity_type}/{entity_id}/versions/{version_id}:
    get:
      description: Get a specific version with its content.
      operationId: get_version_v1__entity_type___entity_id__versions__version_id__get
      parameters:
      - in: path
        name: entity_type
        required: true
        schema:
          title: Entity Type
          type: string
      - in: path
        name: entity_id
        required: true
        schema:
          format: uuid
          title: Entity Id
          type: string
      - in: path
        name: version_id
        required: true
        schema:
          format: uuid
          title: Version Id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionDetail'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get Version
      tags:
      - versions