Seekr Explainability API

openapi: 3.2.0
info:
  title: SeekrFlow Explainability API
  description: SeekrFlow API Documentation
  termsOfService: http://www.seekr.com/support
  contact:
    name: Seekr API Support
    url: http://www.seekr.com/contact
    email: contact@seekr.com
  version: 5.17.1
servers:
- url: https://flow.seekr.com
  description: SeekrBuild server base URL
tags:
- name: Explainability
paths:
  /version:
    get:
      tags:
      - Explainability
      summary: Version
      operationId: version_version_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
                title: Response Version Version Get
      x-excluded: true
  /v1/explainability/:
    get:
      tags:
      - Explainability
      summary: Read Root
      operationId: read_root_v1_explainability__get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      x-excluded: true
  /v1/explainability/status:
    get:
      tags:
      - Explainability
      summary: Check Status
      description: "Check the status of the retriever service.\n\nReturns:\n    JSONResponse: The status response containing the status and version information."
      operationId: check_status_v1_explainability_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
      x-excluded: true
  /v1/explainability/create-index:
    post:
      tags:
      - Explainability
      summary: Create Index
      description: Create index.
      operationId: create_index_v1_explainability_create_index_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateIndexRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateIndexResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-excluded: true
  /v1/explainability/populate-index:
    post:
      tags:
      - Explainability
      summary: Populate Index
      description: Populate the index with qa pairs in the parquet files.
      operationId: populate_index_v1_explainability_populate_index_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PopulateIndexRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PopulateIndexResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-excluded: true
  /v1/explainability/delete-index:
    post:
      tags:
      - Explainability
      summary: Delete Index
      operationId: delete_index_v1_explainability_delete_index_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteIndexRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteIndexResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-excluded: true
  /v1/explainability/influential-finetuning-data:
    get:
      tags:
      - Explainability
      summary: Get Influential Finetuning Data
      description: "Perform hybrid search of the index for the given query.\n\nParameters:\n- team_id (str): team scope for the request.\n- question (str): question from user.\n- model_id (str): model_id of the finetuned model.\n- system_prompt (str | None): optional system prompt used only when answer must be generated.\n- answer (str | None): answer from the finetuned model to the question; if not provided, the service retrieves\n  an answer from the finetuned model specified by model_id.\n- method (str): Specify the types of the hybrid query. Possible values are:\n        match (default): match query for text/keyword search,\n        mlt: more_like_this query for text/keyword search,\n        ns: neural_sparse query for keyword search,\n        bool: boolean query for text/keyword search,\n- k (int): the number of results to be retrieved (5 by default).\n- alpha (float): hybrid query weighting parameter in [0, 1] (default 0.9).\n- index_version (str): index version identifier carried in the request (default \"v0\").\n- threshold (float): score threshold value carried in the request in [0, 1] (default 0.0).\n- api_key: API key passed via HTTP header. Required when answer should be computed\n  using the finetuned model.\n\nReturns:\n    InfluentialFinetuningDataResponse"
      operationId: get_influential_finetuning_data_v1_explainability_influential_finetuning_data_get
      security:
      - HTTPBearer: []
      parameters:
      - name: team_id
        in: query
        required: true
        schema:
          type: string
          title: Team Id
      - name: question
        in: query
        required: true
        schema:
          type: string
          title: Question
      - name: model_id
        in: query
        required: true
        schema:
          type: string
          title: Model Id
      - name: system_prompt
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: System Prompt
      - name: answer
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Answer
      - name: method
        in: query
        required: false
        schema:
          type: string
          default: match
          title: Method
      - name: k
        in: query
        required: false
        schema:
          type: integer
          default: 5
          title: K
      - name: alpha
        in: query
        required: false
        schema:
          type: number
          maximum: 1
          minimum: 0
          default: 0.9
          title: Alpha
      - name: index_version
        in: query
        required: false
        schema:
          type: string
          default: v0
          title: Index Version
      - name: threshold
        in: query
        required: false
        schema:
          type: number
          maximum: 1
          minimum: 0
          default: 0
          title: Threshold
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InfluentialFinetuningDataResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-excluded: true
  /v1/explainability/populate-index-job-status:
    get:
      tags:
      - Explainability
      summary: Populate Index Job Status
      operationId: populate_index_job_status_v1_explainability_populate_index_job_status_get
      parameters:
      - name: team_id
        in: query
        required: true
        schema:
          type: string
          title: Team Id
      - name: job_id
        in: query
        required: true
        schema:
          type: string
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PopulateIndexJobStatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-excluded: true
  /v1/explainability/context-attributor:
    post:
      tags:
      - Explainability
      summary: Get Context Attribution
      description: "Compute context attribution scores for a model response.\n\nDetermines which parts of the provided context contributed to the model's response\nusing the ContextCite algorithm.\n\nRequired fields:\n    - context: The context text that was provided to the model\n    - query: The user's query/question\n    - response: The model's response to attribute\n\nOptional fields:\n    - model: Model name for attribution computation (default: Llama-3.1-8B-Instruct)\n    - highlight: Specific portion of response to attribute. If omitted,\n      returns attributions for all response segments.\n    - granularity: Context partitioning granularity (sentence/chunk)\n    - top_k: Number of top sources to return per segment\n    - num_ablations (32-256): Advanced tuning\n\nReturns:\n    ContextAttributionResult with either:\n    - Single-highlight format (when highlight provided): response_text, highlight, sources\n    - Segment-based format (when highlight omitted): response_text, segments[]"
      operationId: get_context_attribution_v1_explainability_context_attributor_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContextAttributionRequest'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextAttributionResult'
        '422':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /v1/explainability/context-attributor-from-run:
    post:
      tags:
      - Explainability
      summary: Get Context Attribution From Run
      description: "Compute context attribution scores from an agent run.\n\nExtracts context (tool results from message parts, or logfire spans as a SaaS\nfallback), the agent's system prompt (from ``agent.instructions``), the query\n(user input), and the response (assistant output), then runs context\nattribution analysis.\n\nRequired fields:\n    - thread_id: ID of the thread to analyze\n\nOptional fields:\n    - run_id: If not provided, uses the latest completed run\n    - highlight: Specific portion of response to attribute\n    - granularity: Context partitioning granularity (sentence/chunk)\n    - top_k: Number of top sources to return per segment\n\nReturns:\n    ContextAttributionResult with either:\n    - Single-highlight format (when highlight provided): response_text, highlight, sources\n    - Segment-based format (when highlight omitted): response_text, segments[]\n\nRaises:\n    404: If no completed run or spans found\n    422: If no user query or assistant response found"
      operationId: get_context_attribution_from_run_v1_explainability_context_attributor_from_run_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContextAttributionFromRunRequest'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextAttributionResult'
        '422':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
components:
  schemas:
    StatusResponse:
      properties:
        status:
          type: string
          title: Status
        version:
          type: string
          title: Version
      type: object
      required:
      - status
      - version
      title: StatusResponse
    CreateIndexRequest:
      properties:
        index_name:
          type: string
          title: Index Name
          description: 'The name of the index to be used for a fine-tuned model in SeekrFlow. '
        use_sparse_vector:
          type: boolean
          title: Use Sparse Vector
          description: True if you want to use sparse_vector for keyword search.
          default: false
      type: object
      required:
      - index_name
      title: CreateIndexRequest
      description: "CreateIndexRequest represents the request model for creating an index.\n\nAttributes:\n     index_name (str): the index name for a fine-tuned model in SeekrFlow.\n     use_sparse_vector (bool): True if the index should have sparse_vector field (required when ns method is used for search)."
    SegmentAttribution:
      properties:
        segment_index:
          type: integer
          title: Segment Index
          description: Index of this segment in the response (0-based).
        segment_text:
          type: string
          title: Segment Text
          description: The text content of this segment.
        char_offset:
          type: integer
          title: Char Offset
          description: Character offset of this segment in the response.
        sources:
          items:
            oneOf:
            - $ref: '#/components/schemas/ToolResponseSource'
            - $ref: '#/components/schemas/RawContextSource'
            - $ref: '#/components/schemas/SystemPromptSource'
            discriminator:
              propertyName: source_type
              mapping:
                raw: '#/components/schemas/RawContextSource'
                system_prompt: '#/components/schemas/SystemPromptSource'
                tool_response: '#/components/schemas/ToolResponseSource'
          type: array
          title: Sources
          description: Context sources attributed to this segment.
      type: object
      required:
      - segment_index
      - segment_text
      - char_offset
      - sources
      title: SegmentAttribution
      description: Attribution results for a single response segment (e.g., a sentence).
    MCPToolContent:
      properties:
        type:
          type: string
          const: mcp_tool
          title: Type
          default: mcp_tool
        tool_name:
          type: string
          title: Tool Name
        tool_input:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Tool Input
          description: The args sent to the tool (e.g. the prompt passed to a subagent). Truncated to ~2k chars when serialized; mirrors the sensitivity classification of the underlying run.
      type: object
      required:
      - tool_name
      title: MCPToolContent
      description: 'Content for generic MCP tool calls.


        This is the canonical type for any tool call that does not have a

        dedicated first-class handler (web_search, file_search,

        code_interpreter). In practice this covers all MCP tools, including

        "agents as tools" (subagents) — at the persistence layer those are

        indistinguishable from any other MCP tool call.'
    RawContextSource:
      properties:
        source_type:
          type: string
          const: raw
          title: Source Type
          default: raw
        id:
          type: integer
          title: Id
          description: Index of this source in the original context partition.
        text:
          type: string
          title: Text
          description: The source text content.
        attribution:
          type: number
          title: Attribution
          description: Attribution score in range (-1, 1). Positive values indicate support.
        offset:
          type: integer
          title: Offset
          description: Character offset of this source in the original context.
      type: object
      required:
      - id
      - text
      - attribution
      - offset
      title: RawContextSource
      description: 'A context source from raw context (not from a tool).


        This model is used for context that was provided directly, not retrieved

        by a tool call.'
    PopulateIndexJobStatusResponse:
      properties:
        job_id:
          type: string
          title: Job Id
          description: populate index job id
        status:
          type: string
          title: Status
          description: The status of the Populate Index Job.
      type: object
      required:
      - job_id
      - status
      title: PopulateIndexJobStatusResponse
    ContextAttributionRequest:
      properties:
        context:
          type: string
          title: Context
          description: The context text provided to the model.
        query:
          type: string
          title: Query
          description: The user's question/query.
        response:
          type: string
          title: Response
          description: The model's response to attribute.
        highlight:
          anyOf:
          - type: string
          - type: 'null'
          title: Highlight
          description: Specific portion of response to attribute. If None, attributes all segments.
        granularity:
          $ref: '#/components/schemas/BaseGranularityType'
          description: 'Granularity for partitioning context: sentence or paragraph.'
          default: sentence
        top_k:
          type: integer
          minimum: 1
          title: Top K
          description: Number of top attributed sources to return per segment.
          default: 5
        num_ablations:
          anyOf:
          - type: integer
          - type: 'null'
          title: Num Ablations
          description: Number of ablation experiments to run. If None, computed dynamically using O(k log d) formula. Must be between 32 and 256 (inclusive) if specified.
        return_diagnostics:
          type: boolean
          title: Return Diagnostics
          description: If True, include diagnostic information in the response.
          default: false
      type: object
      required:
      - context
      - query
      - response
      title: ContextAttributionRequest
      description: 'Request model for context attribution.


        Computes which parts of the context contributed to the model''s response

        using the ContextCite algorithm.'
    CreateIndexResponse:
      properties:
        index_name:
          type: string
          title: Index Name
          description: 'The name of the index created. '
        status:
          type: string
          title: Status
          description: 'Final status. '
          default: ''
      type: object
      required:
      - index_name
      title: CreateIndexResponse
      description: "CreateIndexResponse represents the response model for creating an index.\n\nAttributes:\n     index_name (str): the index name that has been created.\n     status (str): status_code from OpenSearch.indices.create()"
    WebSearchToolContent:
      properties:
        type:
          type: string
          const: web_search
          title: Type
          default: web_search
        url:
          type: string
          title: Url
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        search_query:
          type: string
          title: Search Query
      type: object
      required:
      - url
      - search_query
      title: WebSearchToolContent
      description: Content specific to web search sources.
    ToolResponseSource:
      properties:
        source_type:
          type: string
          const: tool_response
          title: Source Type
          default: tool_response
        id:
          type: integer
          title: Id
          description: Index of this source in the original context partition.
        text:
          type: string
          title: Text
          description: The source text content.
        attribution:
          type: number
          title: Attribution
          description: Attribution score in range (-1, 1). Positive values indicate support.
        offset:
          type: integer
          title: Offset
          description: Character offset of this source in the original context.
        tool_name:
          type: string
          title: Tool Name
          description: Name of the tool that produced this source.
        tool_call_id:
          type: string
          title: Tool Call Id
          description: Unique identifier for the tool call.
        tool:
          oneOf:
          - $ref: '#/components/schemas/WebSearchToolContent'
          - $ref: '#/components/schemas/FileSearchToolContent'
          - $ref: '#/components/schemas/CodeInterpreterToolContent'
          - $ref: '#/components/schemas/MCPToolContent'
          title: Tool
          description: Tool-specific metadata and content.
          discriminator:
            propertyName: type
            mapping:
              code_interpreter: '#/components/schemas/CodeInterpreterToolContent'
              file_search: '#/components/schemas/FileSearchToolContent'
              mcp_tool: '#/components/schemas/MCPToolContent'
              web_search: '#/components/schemas/WebSearchToolContent'
      type: object
      required:
      - id
      - text
      - attribution
      - offset
      - tool_name
      - tool_call_id
      - tool
      title: ToolResponseSource
      description: 'A context source that originated from a tool call.


        This model contains the core attribution fields plus tool-specific metadata

        nested in the `tool` field.'
    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
    InfluentialFinetuningDataResponse:
      properties:
        answer:
          type: string
          title: Answer
          description: The answer from the model or provided by the user
        version:
          type: string
          title: Version
          description: Version of the index used
        results:
          items:
            $ref: '#/components/schemas/QuestionAnswerPair'
          type: array
          title: Results
          description: List of influential QA pairs
      type: object
      required:
      - answer
      - version
      - results
      title: InfluentialFinetuningDataResponse
    DeleteIndexRequest:
      properties:
        team_id:
          type: string
          title: Team Id
          description: Team id (derived from auth context).
        model_id:
          type: string
          title: Model Id
          description: 'The deployment id of the fine-tuned model in SeekrFlow. '
      type: object
      required:
      - team_id
      - model_id
      title: DeleteIndexRequest
      description: "DeleteIndexRequest represents the request model for deleting an index.\n\nAttributes:\n     team_id (str): team id\n     model_id (str): the fine-tuned model id in SeekrFlow."
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    DeleteIndexResponse:
      properties:
        index_name:
          type: string
          title: Index Name
          description: 'The name of the index created. '
        status:
          type: string
          title: Status
          description: 'Final status. '
          default: ''
      type: object
      required:
      - index_name
      title: DeleteIndexResponse
      description: "DeleteIndexResponse represents the response model for deleting an index.\n\nAttributes:\n     index_name (str): the index name that has been deleted.\n     status (str): response from OpenSearch.indices.delete()"
    CodeInterpreterToolContent:
      properties:
        type:
          type: string
          const: code_interpreter
          title: Type
          default: code_interpreter
        code:
          type: string
          title: Code
      type: object
      required:
      - code
      title: CodeInterpreterToolContent
      description: Content specific to code interpreter sources.
    PopulateIndexRequest:
      properties:
        index_name:
          type: string
          title: Index Name
          description: name of the hybrid search index
        user_id:
          anyOf:
          - type: string
          - type: 'null'
          title: User Id
          description: user_id (derived from auth context)
        team_id:
          type: string
          title: Team Id
          description: team_id (derived from auth context)
        file_ids:
          items:
            type: string
          type: array
          title: File Ids
          description: 'The list of ids of the parquet file in SeekrFlow. '
        use_sparse_vector:
          type: boolean
          title: Use Sparse Vector
          description: True if sparse_vector field should be populated.
          default: false
      type: object
      required:
      - index_name
      - team_id
      - file_ids
      title: PopulateIndexRequest
      description: "PopulateIndexRequest represents the request model for populating an index with the data to the given index.\n\nThis model is used to specify the parquet file containing QA pairs used to fine-tune a model. The file is retrieved\nusing SeekrFlow.\n\nAttributes:\n    index_name (str): name of the index\n    user_id (str): user id\n    team_id (str): team id\n    file_ids (list[str]): The parquet file id in SeekrFlow.\n    use_sparse_vector (bool): True if you want to use sparse vector for keyword search."
    FromRunGranularityType:
      type: string
      enum:
      - sentence
      - chunk
      title: FromRunGranularityType
      description: Granularity for /context-attributor-from-run endpoint.
    QuestionAnswerPair:
      properties:
        id:
          type: string
          title: Id
          description: Unique identifier for the QA pair
        file_id:
          type: string
          title: File Id
          description: ID of the source file
        influence_level:
          $ref: '#/components/schemas/InfluenceLevel'
          description: Level of influence this QA pair has (high, medium, low, irrelevant)
        messages:
          type: string
          title: Messages
          description: The question-answer content
      type: object
      required:
      - id
      - file_id
      - influence_level
      - messages
      title: QuestionAnswerPair
    ContextAttributionFromRunRequest:
      properties:
        thread_id:
          type: string
          title: Thread Id
          description: ID of the thread to analyze.
        run_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Run Id
          description: Optional run ID. If not provided, uses the latest completed run.
        highlight:
          anyOf:
          - type: string
          - type: 'null'
          title: Highlight
          description: Specific portion of response to attribute. If None, attributes all segments.
        granularity:
          $ref: '#/components/schemas/FromRunGranularityType'
          description: 'Granularity for partitioning context: sentence or chunk.'
          default: sentence
        top_k:
          type: integer
          minimum: 1
          title: Top K
          description: Number of top attributed sources to return per segment.
          default: 5
        num_ablations:
          anyOf:
          - type: integer
          - type: 'null'
          title: Num Ablations
          description: Number of ablation experiments to run. If None, computed dynamically using O(k log d) formula. Must be between 32 and 256 (inclusive) if specified.
        return_diagnostics:
          type: boolean
          title: Return Diagnostics
          description: If True, include diagnostic information in the response.
          default: false
      type: object
      required:
      - thread_id
      title: ContextAttributionFromRunRequest
      description: Request model for context attribution from an agent run. Extracts the context, query, and response from the run, then computes attribution scores across the retrieved sources.
    SystemPromptSource:
      properties:
        source_type:
          type: string
          const: system_prompt
          title: Source Type
          default: system_prompt
        id:
          type: integer
          title: Id
          description: Index of this source in the system prompt partition.
        text:
          type: string
          title: Text
          description: The source text content (a sentence or chunk of the system prompt).
        attribution:
          type: number
          title: Attribution
          description: Attribution score in range (-1, 1). Positive values indicate support.
        offset:
          type: integer
          title: Offset
          description: Character offset of this source within the system prompt string.
      type: object
      required:
      - id
      - text
      - attribution
      - offset
      title: SystemPromptSource
      description: 'A context source that originated from the agent''s system prompt.


        Indicates that the response segment was influenced by the agent''s

        operator-defined instructions rather than retrieved documents or tool outputs.

        Character offsets are relative to the system prompt string itself.'
    ContextAttributionDiagnostics:
      properties:
        num_sources:
          type: integer
          title: Num Sources
          description: Number of context sources after partitioning.
        num_ablations:
          type: integer
          title: Num Ablations
          description: Number of ablation experiments performed.
        lasso_alpha:
          type: number
          title: Lasso Alpha
          description: LASSO regularization strength used.
        mask_probability:
          type: number
          title: Mask Probability
          description: Probability of including each source in ablations.
        y_vector_stats:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Y Vector Stats
          description: Statistics of the aggregated Y vector (mean, std, min, max, range).
        raw_coef_stats:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Raw Coef Stats
          description: Statistics of raw LASSO coefficients before tanh (min, max, absmax, nonzero, sparsity).
        scaler_stats:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Scaler Stats
          description: StandardScaler statistics (mean, scale arrays).
      type: object
      required:
      - num_sources
      - num_ablations
      - lasso_alpha
      - mask_probability
      title: ContextAttributionDiagnostics
      description: Diagnostic information for context attribution debugging.
    FileSearchToolContent:
      properties:
        type:
          type: string
          const: file_search
          title: Type
          default: file_search
        file_path:
          anyOf:
          - type: string
          - type: 'null'
          title: File Path
        file_id:
          anyOf:
          - type: string
          - type: 'null'
          title: File Id
        query:
          anyOf:
          - type: string
          - 

# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/seekr/refs/heads/main/openapi/seekr-explainability-api-openapi.yml