OpenAPI Specification
openapi: 3.1.0
info:
title: Vijil Console API (Combined) agent-configurations Diamond API
description: Combined OpenAPI specification for all vijil-console microservices.
version: 0.1.0
tags:
- name: Diamond
description: Evaluation management and report retrieval
paths:
/v1/evaluations/:
get:
tags:
- Diamond
summary: List Team Evaluations
description: "List all evaluations for the authenticated user's teams.\n\nThis endpoint lists all evaluations (running and completed) from the job repository.\nFor completed evaluations stored in S3, use GET /evaluations-results/ instead.\n\nArgs:\n claims: JWT claims with user and team info\n diamond_domain: Diamond domain orchestrator\n\nReturns:\n Dict with \"evaluations\" key containing list of evaluation summaries"
operationId: list_team_evaluations_v1_evaluations__get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
additionalProperties:
items:
additionalProperties: true
type: object
type: array
type: object
title: Response List Team Evaluations V1 Evaluations Get
post:
tags:
- Diamond
summary: Create Evaluation
description: "Create a new evaluation job.\n\nCreates a Kubernetes Job to run the evaluation and tracks it in memory.\nFetches agent configuration from Agent Registry using the provided agent_id.\nJWT token is retrieved from request context (set by JWTAuthMiddleware).\n\nArgs:\n request: Evaluation configuration with agent_id and team_id\n claims: JWT claims with user and team info\n diamond_domain: Diamond domain orchestrator\n\nReturns:\n Evaluation ID, status, and status URL"
operationId: create_evaluation_v1_evaluations__post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEvaluationRequest'
required: true
responses:
'202':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEvaluationResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/evaluations/{evaluation_id}/html:
get:
tags:
- Diamond
summary: Get Evaluation Html Report
description: "Get HTML trust report for an evaluation.\n\nReturns the HTML content directly for browser viewing.\nHTML reports are automatically generated when evaluations complete.\n\nArgs:\n evaluation_id: UUID of the evaluation\n team_id: Team ID that owns this evaluation\n claims: JWT claims with user and team info\n report_storage: Report storage adapter\n\nReturns:\n HTML response with the report content\n\nRaises:\n HTTPException: 401 if unauthorized, 403 if no permission, 404 if report not found"
operationId: get_evaluation_html_report_v1_evaluations__evaluation_id__html_get
parameters:
- name: evaluation_id
in: path
required: true
schema:
type: string
format: uuid
title: Evaluation Id
- name: team_id
in: query
required: true
schema:
type: string
format: uuid
description: Team ID that owns this evaluation
title: Team Id
description: Team ID that owns this evaluation
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/evaluations/{evaluation_id}/pdf:
get:
tags:
- Diamond
summary: Get Evaluation Pdf Report
description: "Get PDF trust report for an evaluation.\n\nPDF reports are automatically generated when evaluations complete\n(same flow as HTML reports).\n\nArgs:\n evaluation_id: UUID of the evaluation\n team_id: Team ID that owns this evaluation\n claims: JWT claims with user and team info\n report_storage: Report storage adapter\n\nReturns:\n PDF response with the report content\n\nRaises:\n HTTPException: 401 if unauthorized, 403 if no permission, 404 if report not found"
operationId: get_evaluation_pdf_report_v1_evaluations__evaluation_id__pdf_get
parameters:
- name: evaluation_id
in: path
required: true
schema:
type: string
format: uuid
title: Evaluation Id
- name: team_id
in: query
required: true
schema:
type: string
format: uuid
description: Team ID that owns this evaluation
title: Team Id
description: Team ID that owns this evaluation
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/evaluations/{evaluation_id}/logs:
get:
tags:
- Diamond
summary: Get Evaluation Logs
description: "Get evaluation job logs from Kubernetes.\n\nArgs:\n evaluation_id: UUID of the evaluation\n claims: JWT claims with user and team info\n diamond_domain: Diamond domain orchestrator\n\nReturns:\n Job logs as dict with \"logs\" key\n\nRaises:\n HTTPException: 404 if logs not available"
operationId: get_evaluation_logs_v1_evaluations__evaluation_id__logs_get
parameters:
- name: evaluation_id
in: path
required: true
schema:
type: string
format: uuid
title: Evaluation Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties:
type: string
title: Response Get Evaluation Logs V1 Evaluations Evaluation Id Logs Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/evaluations/{evaluation_id}:
get:
tags:
- Diamond
summary: Get Evaluation
description: "Get evaluation status.\n\nArgs:\n evaluation_id: UUID of the evaluation (can be job_id or evaluation_id)\n claims: JWT claims with user and team info\n diamond_domain: Diamond domain orchestrator\n\nReturns:\n Current evaluation status with timestamps (returns Diamond's evaluation_id as source of truth)\n\nRaises:\n HTTPException: 404 if evaluation not found or user lacks access\n HTTPException: 503 if evaluation status cannot be retrieved"
operationId: get_evaluation_v1_evaluations__evaluation_id__get
parameters:
- name: evaluation_id
in: path
required: true
schema:
type: string
format: uuid
title: Evaluation Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EvaluationStatusResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- Diamond
summary: Delete Evaluation
description: "Delete evaluation (Kubernetes Job + repository entry + S3 storage).\n\nDeletes the evaluation from:\n- Kubernetes Job (via domain)\n- Repository entry (via domain)\n- S3 storage (request, results, report files)\n\nArgs:\n evaluation_id: UUID of the evaluation\n claims: JWT claims with user and team info\n diamond_domain: Diamond domain orchestrator\n storage: Evaluation storage adapter\n\nReturns:\n Status dict with \"deleted\" status\n\nRaises:\n HTTPException: 404 if evaluation not found"
operationId: delete_evaluation_v1_evaluations__evaluation_id__delete
parameters:
- name: evaluation_id
in: path
required: true
schema:
type: string
format: uuid
title: Evaluation Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties:
type: string
title: Response Delete Evaluation V1 Evaluations Evaluation Id Delete
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/evaluations/{evaluation_id}/cancel:
post:
tags:
- Diamond
summary: Cancel Evaluation
description: "Cancel a running evaluation (Kubernetes Job cancellation + workflow status update).\n\nCancels an evaluation that is in progress (CREATED, STARTING, or RUNNING status).\nThis will:\n- Delete the Kubernetes Job (which cancels the running pod)\n- Update workflow status to CANCELLED\n- Optionally clean up partial S3 data (request file is kept for audit)\n\nArgs:\n evaluation_id: UUID of the evaluation to cancel\n claims: JWT claims with user and team info\n diamond_domain: Diamond domain orchestrator\n storage: Evaluation storage adapter\n\nReturns:\n Status dict with \"cancelled\" status\n\nRaises:\n HTTPException: 404 if evaluation not found, 400 if evaluation is already completed/cancelled"
operationId: cancel_evaluation_v1_evaluations__evaluation_id__cancel_post
parameters:
- name: evaluation_id
in: path
required: true
schema:
type: string
format: uuid
title: Evaluation Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties:
type: string
title: Response Cancel Evaluation V1 Evaluations Evaluation Id Cancel Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/evaluations/{evaluation_id}/report:
post:
tags:
- Diamond
summary: Generate Report On Demand
description: 'Generate a trust report on demand (Layer 3).
This endpoint triggers LLM analysis + HTML/PDF report generation
for a completed evaluation. Reports are cached in S3 — subsequent
calls return the cached version unless force_regenerate=True.
Reports are NOT auto-generated on evaluation completion (CON-256).
Users explicitly request reports when they need proof of compliance
or want a printable summary.'
operationId: generate_report_on_demand_v1_evaluations__evaluation_id__report_post
parameters:
- name: evaluation_id
in: path
required: true
schema:
type: string
format: uuid
title: Evaluation Id
- name: team_id
in: query
required: true
schema:
type: string
format: uuid
description: Team that owns this evaluation
title: Team Id
description: Team that owns this evaluation
- name: force_regenerate
in: query
required: false
schema:
type: boolean
description: Force regeneration even if cached
default: false
title: Force Regenerate
description: Force regeneration even if cached
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response Generate Report On Demand V1 Evaluations Evaluation Id Report Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/evaluation-results/:
get:
tags:
- Diamond
summary: List Completed Evaluations
description: "List completed evaluations from S3 storage for a specific team.\n\nThis endpoint lists only completed evaluations that have results stored in S3.\nIt requires the team_id as a query parameter and respects permission checks.\nSupports paging via limit (default 10) and offset.\n\nArgs:\n team_id: Team ID to list evaluations for (required query parameter)\n limit: Max number of results (default 10, max 100)\n offset: Number of results to skip for paging\n claims: JWT claims with user and team info\n diamond_domain: Diamond domain for listing evaluations (newest-first sort + paginate)\n agent_adapter: Agent registry adapter for looking up agent names\n\nReturns:\n List of completed evaluations with evaluation_id, team_id, agent information, and total count\n\nRaises:\n HTTPException: 401 if unauthorized, 403 if no permission"
operationId: list_completed_evaluations_v1_evaluation_results__get
parameters:
- name: team_id
in: query
required: true
schema:
type: string
format: uuid
title: Team Id
- name: limit
in: query
required: false
schema:
type: integer
maximum: 100
minimum: 1
description: Maximum number of results to return
default: 10
title: Limit
description: Maximum number of results to return
- 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
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EvaluationListResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/evaluation-results/{evaluation_id}/results:
get:
tags:
- Diamond
summary: Get Evaluation Results
description: "Get evaluation results from S3 storage.\n\nThe results are saved to S3 after the evaluation job completes.\nThis endpoint searches S3 directly (no repository dependency).\n\nArgs:\n evaluation_id: UUID of the evaluation\n team_id: Team ID that owns this evaluation (required query parameter)\n claims: JWT claims with user and team info\n diamond_domain: Diamond domain orchestrator (not used, kept for API consistency)\n storage: Evaluation storage adapter\n\nReturns:\n Evaluation results as JSON\n\nRaises:\n HTTPException: 404 if not found, 403 if no permission"
operationId: get_evaluation_results_v1_evaluation_results__evaluation_id__results_get
parameters:
- name: evaluation_id
in: path
required: true
schema:
type: string
format: uuid
title: Evaluation Id
- name: team_id
in: query
required: true
schema:
type: string
format: uuid
description: Team ID that owns this evaluation
title: Team Id
description: Team ID that owns this evaluation
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response Get Evaluation Results V1 Evaluation Results Evaluation Id Results Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/evaluation-results/{evaluation_id}/report:
get:
tags:
- Diamond
summary: Get Evaluation Report
description: "Download evaluation report PDF from S3 storage.\n\nThe report is saved to S3 after the evaluation job completes.\nThis endpoint searches S3 directly (no repository dependency).\n\nArgs:\n evaluation_id: UUID of the evaluation\n team_id: Team ID that owns this evaluation (required query parameter)\n claims: JWT claims with user and team info\n diamond_domain: Diamond domain orchestrator (not used, kept for API consistency)\n storage: Evaluation storage adapter\n\nReturns:\n PDF file response\n\nRaises:\n HTTPException: 404 if report not found in storage, 403 if no permission"
operationId: get_evaluation_report_v1_evaluation_results__evaluation_id__report_get
parameters:
- name: evaluation_id
in: path
required: true
schema:
type: string
format: uuid
title: Evaluation Id
- name: team_id
in: query
required: true
schema:
type: string
format: uuid
description: Team ID that owns this evaluation
title: Team Id
description: Team ID that owns this evaluation
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/evaluation-results/{evaluation_id}/report.html:
get:
tags:
- Diamond
summary: Get Evaluation Report Html
description: "Download evaluation report HTML from S3 storage.\n\nThe HTML report is saved to S3 after the evaluation job completes.\nThis is the preferred report format - can be viewed in browser or printed to PDF.\n\nArgs:\n evaluation_id: UUID of the evaluation\n team_id: Team ID that owns this evaluation (required query parameter)\n claims: JWT claims with user and team info\n diamond_domain: Diamond domain orchestrator (not used, kept for API consistency)\n storage: Evaluation storage adapter\n\nReturns:\n HTML file response\n\nRaises:\n HTTPException: 404 if report not found in storage, 403 if no permission"
operationId: get_evaluation_report_html_v1_evaluation_results__evaluation_id__report_html_get
parameters:
- name: evaluation_id
in: path
required: true
schema:
type: string
format: uuid
title: Evaluation Id
- name: team_id
in: query
required: true
schema:
type: string
format: uuid
description: Team ID that owns this evaluation
title: Team Id
description: Team ID that owns this evaluation
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/evaluation-summaries/:
get:
tags:
- Diamond
summary: List Evaluation Summaries
description: "List evaluation summaries for a team with optional filters and pagination.\n\nArgs:\n team_id: Team ID to list summaries for (required)\n agent_id: Optional filter by agent ID\n status: Optional filter by status (running, completed, failed, cancelled)\n harness_type: Optional filter by harness type\n tested_by: Optional filter by evaluation tool\n limit: Max number of results (default 10, max 100)\n offset: Number of results to skip for paging\n claims: JWT claims with user and team info\n summary_repo: Evaluation summary repository\n\nReturns:\n Paginated list of evaluation summaries with total count\n\nRaises:\n HTTPException: 401 if unauthorized, 403 if no permission"
operationId: list_evaluation_summaries_v1_evaluation_summaries__get
parameters:
- name: team_id
in: query
required: true
schema:
type: string
format: uuid
description: Team ID to list summaries for
title: Team Id
description: Team ID to list summaries for
- 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
- name: status
in: query
required: false
schema:
anyOf:
- $ref: '#/components/schemas/EvaluationStatus'
- type: 'null'
description: Filter by status (running, completed, failed, cancelled)
title: Status
description: Filter by status (running, completed, failed, cancelled)
- name: harness_type
in: query
required: false
schema:
anyOf:
- enum:
- standard
- custom
type: string
- type: 'null'
description: Filter by harness type (standard or custom)
title: Harness Type
description: Filter by harness type (standard or custom)
- name: tested_by
in: query
required: false
schema:
anyOf:
- $ref: '#/components/schemas/EvaluationTool'
- type: 'null'
description: Filter by tool that ran the evaluation
title: Tested By
description: Filter by tool that ran the evaluation
- name: limit
in: query
required: false
schema:
type: integer
maximum: 100
minimum: 1
description: Maximum number of results to return
default: 10
title: Limit
description: Maximum number of results to return
- 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
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EvaluationSummaryListResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/evaluation-summaries/latest-by-agent:
get:
tags:
- Diamond
summary: List Latest Evaluation Summaries By Agent
description: 'Return the latest completed evaluation summary per agent for the team.
Uses server-side grouping (one row per agent_id with max completed_at).
No pagination; returns at most one summary per agent that has a completed evaluation.'
operationId: list_latest_evaluation_summaries_by_agent_v1_evaluation_summaries_latest_by_agent_get
parameters:
- name: team_id
in: query
required: true
schema:
type: string
format: uuid
description: Team ID to list latest summary per agent for
title: Team Id
description: Team ID to list latest summary per agent for
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EvaluationSummaryListResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/evaluation-summaries/{evaluation_id}:
get:
tags:
- Diamond
summary: Get Evaluation Summary
description: "Get a single evaluation summary by evaluation ID.\n\nArgs:\n evaluation_id: UUID of the evaluation (same as summary ID)\n team_id: Team ID that owns this evaluation\n claims: JWT claims with user and team info\n summary_repo: Evaluation summary repository\n\nReturns:\n Evaluation summary with scores and metadata\n\nRaises:\n HTTPException: 401 if unauthorized, 403 if no permission, 404 if not found"
operationId: get_evaluation_summary_v1_evaluation_summaries__evaluation_id__get
parameters:
- name: evaluation_id
in: path
required: true
schema:
type: string
format: uuid
title: Evaluation Id
- name: team_id
in: query
required: true
schema:
type: string
format: uuid
description: Team ID that owns this evaluation
title: Team Id
description: Team ID that owns this evaluation
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EvaluationSummaryResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- Diamond
summary: Delete Evaluation Summary
description: "Delete an evaluation summary row.\n\nThis endpoint only removes the summary cache row — it does not delete\nthe underlying evaluation job or S3 artifacts. To fully delete an\nevaluation, use DELETE /evaluations/{evaluation_id}.\n\nArgs:\n evaluation_id: UUID of the evaluation summary to delete\n team_id: Team ID that owns this evaluation\n claims: JWT claims with user and team info\n summary_repo: Evaluation summary repository\n\nRaises:\n HTTPException: 401 if unauthorized, 403 if no permission, 404 if not found"
operationId: delete_evaluation_summary_v1_evaluation_summaries__evaluation_id__delete
parameters:
- name: evaluation_id
in: path
required: true
schema:
type: string
format: uuid
title: Evaluation Id
- name: team_id
in: query
required: true
schema:
type: string
format: uuid
description: Team ID that owns this evaluation
title: Team Id
description: Team ID that owns this evaluation
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/harnesses/:
get:
tags:
- Diamond
summary: List Harnesses
description: "List all standard harnesses (global resources).\n\nStandard harnesses are global and not scoped to a team.\nThey are read-only and managed externally.\n\nArgs:\n team_id: Team ID (required for permission checks)\n claims: JWT claims with user and team info\n harness_service: Harness service instance\n \nReturns:\n List of harness items, ordered by updated_at descending\n \nRaises:\n HTTPException: 422 if team_id is missing, 403 if user lacks permission, 500 on server errors"
operationId: list_harnesses_v1_harnesses__get
parameters:
- name: team_id
in: query
required: true
schema:
type: string
format: uuid
description: Team ID (required)
title: Team Id
description: Team ID (required)
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/HarnessListItem'
title: Response List Harnesses V1 Harnesses Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/custom-harnesses/:
get:
tags:
- Diamond
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:
- Diamond
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':
des
# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vijil/refs/heads/main/openapi/vijil-diamond-api-openapi.yml