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

# Invoke

> Invokes a pre-configured evaluation by its ID. The evaluation configuration (which checks to run, modes, assertions, etc.) is defined in the Qualifire dashboard.



## OpenAPI

````yaml POST /v1/evaluation/invoke
openapi: 3.0.3
info:
  title: Qualifire AI API
  description: API for Qualifire AI services, including evaluation and prompt management.
  version: 1.0.0
servers:
  - url: https://api.qualifire.ai/api
security:
  - ApiKeyAuth: []
paths:
  /v1/evaluation/invoke:
    post:
      tags:
        - Evaluation
      summary: Invoke a pre-configured evaluation
      description: >-
        Invokes a pre-configured evaluation by its ID. The evaluation
        configuration (which checks to run, modes, assertions, etc.) is defined
        in the Qualifire dashboard.
      requestBody:
        description: Evaluation invoke request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/models.EvaluationInvokeRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.EvaluationResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.Error'
        '404':
          description: Evaluation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.Error'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.Error'
components:
  schemas:
    models.EvaluationInvokeRequest:
      type: object
      description: At least one of `input`, `output`, or `messages` must be provided.
      required:
        - evaluation_id
      properties:
        evaluation_id:
          type: string
          description: The ID of the pre-configured evaluation to invoke
        input:
          type: string
          description: The input text (e.g., user prompt)
        output:
          type: string
          description: The output text (e.g., LLM response)
        messages:
          type: array
          description: Conversation messages for multi-turn evaluation
          items:
            $ref: '#/components/schemas/models.LlmMessage'
        available_tools:
          type: array
          description: List of tools available to the LLM
          items:
            $ref: '#/components/schemas/models.LlmToolDefinition'
        metadata:
          type: object
          additionalProperties:
            type: string
          description: >-
            Optional key-value pairs (string values only) to attach to the
            evaluation invocation
    models.EvaluationResponse:
      type: object
      required:
        - status
        - score
        - evaluationResults
      properties:
        status:
          type: string
          description: Overall evaluation status
          enum:
            - success
            - warning
            - failed
        score:
          type: number
          nullable: true
          description: Overall evaluation score (0-100)
        evaluationResults:
          type: array
          items:
            $ref: '#/components/schemas/models.EvaluationResult'
    models.Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: A human-readable error message
          example: Invalid API key
    models.LlmMessage:
      type: object
      required:
        - role
      properties:
        role:
          type: string
          description: The role of the message sender
          enum:
            - system
            - user
            - assistant
            - tool
            - developer
        content:
          type: string
          nullable: true
          description: The text content of the message
        tool_calls:
          type: array
          description: Tool calls made by the assistant
          items:
            $ref: '#/components/schemas/models.LlmToolCall'
    models.LlmToolDefinition:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Name of the tool
        description:
          type: string
          description: Description of what the tool does
        parameters:
          type: object
          additionalProperties: true
          description: JSON Schema describing the tool's parameters
    models.EvaluationResult:
      type: object
      required:
        - type
        - results
      properties:
        type:
          type: string
          description: >-
            The evaluation type (e.g., hallucinations, grounding, policy, pii,
            prompt_injections, safety, tuq, topic_scoping)
        results:
          type: array
          items:
            $ref: '#/components/schemas/models.DetectionResult'
    models.LlmToolCall:
      type: object
      required:
        - function
      properties:
        id:
          type: string
          description: Unique identifier for the tool call
        type:
          type: string
          description: The type of tool call (e.g., "function")
        function:
          type: object
          required:
            - name
            - arguments
          properties:
            name:
              type: string
              description: Name of the tool being called
            arguments:
              type: object
              additionalProperties: true
              description: Arguments passed to the tool (key-value pairs)
    models.DetectionResult:
      type: object
      required:
        - name
        - score
        - label
        - confidence_score
        - reason
        - flagged
      properties:
        name:
          type: string
        score:
          type: number
        label:
          type: string
        confidence_score:
          type: number
        reason:
          type: string
        quote:
          type: string
        flagged:
          type: boolean
          description: Whether this result was flagged as a violation
        data:
          type: string
          description: Additional context data (e.g., the assertion text for policy checks)
          nullable: true
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Qualifire-API-Key

````