Vijil custom-harnesses API

openapi: 3.1.0
info:
  title: Vijil Console API (Combined) agent-configurations custom-harnesses API
  description: Combined OpenAPI specification for all vijil-console microservices.
  version: 0.1.0
tags:
- name: custom-harnesses
paths:
  /v1/custom-harnesses/:
    get:
      tags:
      - custom-harnesses
      summary: List Custom Harnesses
      description: 'List custom harnesses for the specified team with pagination and filtering.


        Returns paginated list of harnesses owned by the specified team.

        Supports filtering by status.


        Requires agent:read permission.'
      operationId: list_custom_harnesses_v1_custom_harnesses__get
      parameters:
      - name: team_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Team ID (required)
          title: Team Id
        description: Team ID (required)
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Maximum number of results (default 10)
          default: 10
          title: Limit
        description: Maximum number of results (default 10)
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Number of results to skip for paging
          default: 0
          title: Offset
        description: Number of results to skip for paging
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/CustomHarnessStatus'
          - type: 'null'
          description: Filter by status
          title: Status
        description: Filter by status
      - name: agent_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Filter by agent ID
          title: Agent Id
        description: Filter by agent ID
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomHarnessListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - custom-harnesses
      summary: Create Custom Harness
      description: 'Create a new custom harness.


        Creates a harness in ''draft'' status. The harness can be configured with

        an agent, personas, and policies before being activated.


        Note: Harnesses are immutable once created - they cannot be updated.


        Requires agent:write permission.'
      operationId: create_custom_harness_v1_custom_harnesses__post
      parameters:
      - name: team_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Team ID (required)
          title: Team Id
        description: Team ID (required)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomHarnessCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomHarness'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/custom-harnesses/{harness_id}:
    get:
      tags:
      - custom-harnesses
      summary: Get Custom Harness
      description: 'Get a single custom harness by ID with optional workflow status.


        Returns the harness (business status: DRAFT/ACTIVE/ARCHIVED) enriched with

        workflow status (execution state: RUNNING/SUCCEEDED/FAILED) if a workflow exists.


        Client interpretation:

        - harness.status=DRAFT + no workflow = Not started yet

        - harness.status=DRAFT + workflow.status=RUNNING = Generation in progress

        - harness.status=DRAFT + workflow.status=FAILED = Generation failed, can retry

        - harness.status=ACTIVE = Generation completed successfully


        Requires agent:read permission.'
      operationId: get_custom_harness_v1_custom_harnesses__harness_id__get
      parameters:
      - name: harness_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Harness Id
      - name: team_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Team ID (required)
          title: Team Id
        description: Team ID (required)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomHarnessResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - custom-harnesses
      summary: Delete Custom Harness
      description: 'Delete a custom harness.


        Permanently deletes the harness and any associated data.


        Requires agent:write permission.'
      operationId: delete_custom_harness_v1_custom_harnesses__harness_id__delete
      parameters:
      - name: harness_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Harness Id
      - name: team_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Team ID (required)
          title: Team Id
        description: Team ID (required)
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/custom-harnesses/{harness_id}/cancel:
    post:
      tags:
      - custom-harnesses
      summary: Cancel Custom Harness
      description: 'Cancel a running custom harness creation workflow.


        Uses harness_id to load the harness from S3, then the harness''s workflow_id to load the

        workflow. If workflow_specific_fields (task_id, session_id) are present, sends cancel to the

        agent; otherwise marks the workflow as cancelled so the worker will not overwrite with

        success/failure. Requires agent:write permission.'
      operationId: cancel_custom_harness_v1_custom_harnesses__harness_id__cancel_post
      parameters:
      - name: harness_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Harness Id
      - name: team_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Team ID (required)
          title: Team Id
        description: Team ID (required)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
                title: Response Cancel Custom Harness V1 Custom Harnesses  Harness Id  Cancel Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/custom-harnesses/{harness_id}/prompts:
    get:
      tags:
      - custom-harnesses
      summary: Get Custom Harness Prompts
      description: 'Return taxonomy prompts from ``harness_prompts.jsonl`` for a custom harness.


        Served by service-diamond; loads JSONL from the team custom-harness S3 path.

        Does not read Trust Score ``prompt.jsonl``.


        Returns an empty list if the file is missing or empty (e.g. harness still in DRAFT).


        Requires agent:read permission.'
      operationId: get_custom_harness_prompts_v1_custom_harnesses__harness_id__prompts_get
      parameters:
      - name: harness_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Harness Id
      - name: team_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Team ID (required)
          title: Team Id
        description: Team ID (required)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HarnessPromptsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    CustomHarnessResponse:
      properties:
        harness:
          $ref: '#/components/schemas/CustomHarness'
        workflow:
          anyOf:
          - $ref: '#/components/schemas/WorkflowStatusInfo'
          - type: 'null'
      type: object
      required:
      - harness
      title: CustomHarnessResponse
      description: Response model for custom harness with optional workflow status.
    CustomHarness:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        team_id:
          type: string
          format: uuid
          title: Team Id
        name:
          type: string
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        agent_id:
          type: string
          format: uuid
          title: Agent Id
        persona_ids:
          items:
            type: string
            format: uuid
          type: array
          title: Persona Ids
        policy_ids:
          items:
            type: string
            format: uuid
          type: array
          title: Policy Ids
        status:
          $ref: '#/components/schemas/CustomHarnessStatus'
          default: draft
        workflow_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Workflow Id
          description: Reference to the latest workflow that generated this harness. Enables lookup of workflow status by harness_id. Supports future 'regenerate harness' scenarios.
        s3_key:
          anyOf:
          - type: string
          - type: 'null'
          title: S3 Key
        generated_at:
          anyOf:
          - type: integer
          - type: 'null'
          title: Generated At
        prompt_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Prompt Count
        created_at:
          type: integer
          title: Created At
        updated_at:
          type: integer
          title: Updated At
        created_by:
          type: string
          format: uuid
          title: Created By
        creation_error:
          anyOf:
          - type: string
          - type: 'null'
          title: Creation Error
      type: object
      required:
      - id
      - team_id
      - name
      - agent_id
      - created_at
      - updated_at
      - created_by
      title: CustomHarness
      description: 'Domain model for a custom harness (test configuration).


        A custom harness is a test configuration that combines an agent,

        personas, and policies. The backend generates evaluation prompts

        based on this configuration.


        Stored as metadata.json in S3.'
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    CustomHarnessListResponse:
      properties:
        results:
          items:
            $ref: '#/components/schemas/CustomHarnessListItem'
          type: array
          title: Results
        total:
          type: integer
          title: Total
      type: object
      required:
      - results
      - total
      title: CustomHarnessListResponse
      description: Response model for paginated list of custom harnesses.
    WorkflowStatus:
      type: string
      enum:
      - created
      - starting
      - running
      - succeeded
      - failed
      - cancelled
      title: WorkflowStatus
      description: 'Core lifecycle states for workflows.


        These are universal statuses that apply to all workflow types.

        Workflow-specific phases can be tracked using the optional `phase` field.'
    CustomHarnessPrompt:
      properties:
        dimension_name:
          type: string
          title: Dimension Name
        prompt_text:
          type: string
          title: Prompt Text
        pass_criteria:
          type: string
          title: Pass Criteria
        lineage:
          $ref: '#/components/schemas/CustomHarnessLineage'
      type: object
      required:
      - dimension_name
      - prompt_text
      - pass_criteria
      - lineage
      title: CustomHarnessPrompt
      description: A row from ``harness_prompts.jsonl`` (taxonomy / rich prompts for custom harnesses).
    HarnessPromptsResponse:
      properties:
        prompts:
          items:
            $ref: '#/components/schemas/CustomHarnessPrompt'
          type: array
          title: Prompts
        count:
          type: integer
          title: Count
      type: object
      required:
      - count
      title: HarnessPromptsResponse
      description: Response model for taxonomy prompts from ``harness_prompts.jsonl`` (not ``prompt.jsonl``).
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CustomHarnessStatus:
      type: string
      enum:
      - draft
      - active
      - archived
      - failed
      title: CustomHarnessStatus
      description: Status values for custom harnesses.
    CustomHarnessLineage:
      properties:
        principle:
          type: string
          title: Principle
          default: ''
        theme:
          type: string
          title: Theme
          default: ''
        policy_section:
          type: string
          title: Policy Section
          default: ''
        persona:
          type: string
          title: Persona
          default: ''
        diagnostic_hooks:
          items:
            type: string
          type: array
          title: Diagnostic Hooks
      type: object
      title: CustomHarnessLineage
      description: Structured lineage for a custom-harness taxonomy prompt (``harness_prompts.jsonl``).
    WorkflowStatusInfo:
      properties:
        status:
          $ref: '#/components/schemas/WorkflowStatus'
        phase:
          anyOf:
          - type: string
          - type: 'null'
          title: Phase
        error_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Message
        task_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Task Id
        session_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Id
      type: object
      required:
      - status
      title: WorkflowStatusInfo
      description: 'Workflow status information for enrichment.


        For custom harness workflows, task_id and session_id (when present) are

        persisted in the workflow S3 file under workflow_specific_fields and

        exposed here for cancel/debugging.'
    CustomHarnessCreate:
      properties:
        id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Id
        name:
          type: string
          maxLength: 255
          minLength: 1
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        agent_id:
          type: string
          format: uuid
          title: Agent Id
        persona_ids:
          items:
            type: string
            format: uuid
          type: array
          title: Persona Ids
        policy_ids:
          items:
            type: string
            format: uuid
          type: array
          title: Policy Ids
        system_prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: System Prompt
          description: AUT description or system prompt for harness generation. If not provided, agent description will be used.
      type: object
      required:
      - name
      - agent_id
      title: CustomHarnessCreate
      description: Request model for creating a custom harness.
    CustomHarnessListItem:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        status:
          $ref: '#/components/schemas/CustomHarnessStatus'
        created_at:
          type: integer
          title: Created At
        updated_at:
          type: integer
          title: Updated At
        agent_id:
          type: string
          format: uuid
          title: Agent Id
        agent_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Name
        policy_ids:
          items:
            type: string
            format: uuid
          type: array
          title: Policy Ids
        persona_ids:
          items:
            type: string
            format: uuid
          type: array
          title: Persona Ids
      type: object
      required:
      - id
      - name
      - status
      - created_at
      - updated_at
      - agent_id
      title: CustomHarnessListItem
      description: 'List-item model for a custom harness (id, name, status, timestamps, agent, policies, personas).


        Returned by the list endpoint; full details are available via get by id.'