Vijil Agent Environment API

openapi: 3.2.0
info:
  title: Vijil Console API (Combined) Agent Environment API
  description: Combined OpenAPI specification for all vijil-console microservices.
  version: 0.1.0
tags:
- name: Agent Environment
  description: Agent, persona, policy, and harness management
paths:
  /v1/agent-configurations/:
    post:
      tags:
      - Agent Environment
      summary: Create Agent Configuration
      description: 'Create a new agent configuration.


        This endpoint accepts AgentConfigRequest format from the frontend and transforms it

        to the internal AgentCreate format. The agent_url field is preserved.


        Requires agent:write permission.'
      operationId: create_agent_configuration_v1_agent_configurations__post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentConfigRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Agent Environment
      summary: Get Agent Configurations
      description: 'List agent configurations with filtering and pagination.


        Requires agent:read permission (all team members) or

        agent:read_all permission (super admin).'
      operationId: get_agent_configurations_v1_agent_configurations__get
      parameters:
      - name: statuses
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: Filter by status(es). If not provided, defaults to non-archived statuses.
          title: Statuses
        description: Filter by status(es). If not provided, defaults to non-archived statuses.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Maximum number of results
          default: 100
          title: Limit
        description: Maximum number of results
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Number of results to skip
          default: 0
          title: Offset
        description: Number of results to skip
      - name: include_scores
        in: query
        required: false
        schema:
          type: boolean
          description: When true, sideloads the latest completed evaluation scores onto each agent.
          default: false
          title: Include Scores
        description: When true, sideloads the latest completed evaluation scores onto each agent.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentConfigListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/agent-configurations/{id}:
    get:
      tags:
      - Agent Environment
      summary: Get Agent Configuration By Id
      description: 'Get a single agent configuration by ID.


        Requires agent:read permission (all team members) or

        agent:read_all permission (super admin).'
      operationId: get_agent_configuration_by_id_v1_agent_configurations__id__get
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      - name: include_scores
        in: query
        required: false
        schema:
          type: boolean
          description: When true, sideloads the latest completed evaluation scores onto the agent.
          default: false
          title: Include Scores
        description: When true, sideloads the latest completed evaluation scores onto the agent.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - Agent Environment
      summary: Update Agent Configuration
      description: "Update an existing agent configuration.\n\nSupports partial updates - you can update just the api_key field, or any other field(s).\nAll fields in the request body are optional.\n\nRequires agent:write permission + billing feature 'write_custom_agent'.\n\nExample:\n    # Update only the API key\n    PUT /agent-configurations/{id}\n    {\n      \"api_key\": \"sk-new-key-value\"\n    }\n    \n    # Update multiple fields\n    PUT /agent-configurations/{id}\n    {\n      \"agent_name\": \"New Name\",\n      \"api_key\": \"sk-new-key-value\",\n      \"mcp_config\": {\"proxy_url\": \"https://proxy.example.com\", \"access_level\": \"read\"}\n    }\n    \n    # Enable/disable dome auto-apply (when true, saving dome config auto-applies it)\n    PUT /agent-configurations/{id}\n    {\n      \"dome_manually_configured\": true\n    }"
      operationId: update_agent_configuration_v1_agent_configurations__id__put
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/agent-configurations/{id}/archive:
    put:
      tags:
      - Agent Environment
      summary: Archive Agent Configuration
      description: 'Archive agent configuration.


        Sets the agent status to ARCHIVED.

        Requires agent:write permission (all team members) or

        agent:write_all permission (super admin).'
      operationId: archive_agent_configuration_v1_agent_configurations__id__archive_put
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/agent-configurations/{id}/lifecycle:
    put:
      tags:
      - Agent Environment
      summary: Update Agent Lifecycle
      description: 'Update agent trust lifecycle stage.


        Requires agent:write permission (all team members) or

        agent:write_all permission (super admin).


        Setting trust_stage to ''hardened'' captures trusted_at and computes ttt_days.'
      operationId: update_agent_lifecycle_v1_agent_configurations__id__lifecycle_put
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentLifecycleUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/agent-configurations/{agent_id}/dome-configs:
    get:
      tags:
      - Agent Environment
      summary: Get Agent Dome Config
      description: Return the dome configuration this agent is using (row-bound and/or ``dome_config_id``).
      operationId: get_agent_dome_config_v1_agent_configurations__agent_id__dome_configs_get
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Agent Id
      - 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:
                $ref: '#/components/schemas/AgentDomeConfigResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/agent-configurations/{id}/evaluation-config:
    get:
      tags:
      - Agent Environment
      summary: Get Evaluation Config
      description: 'Get agent configuration for Diamond evaluation.


        Returns agent_url, agent_api_key, and agent_model_name needed for evaluation.

        Requires agent:read permission (all team members) or

        agent:read_all permission (super admin).'
      operationId: get_evaluation_config_v1_agent_configurations__id__evaluation_config_get
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentEvaluationConfig'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/agents/{agent_id}/constraints:
    get:
      tags:
      - Agent Environment
      summary: Fetch agent trust constraints
      description: Returns the agent's trust constraints (Dome guard config, tool permissions, organization rules, enforcement mode) in the format consumed by the vijil-sdk Trust Runtime at boot.
      operationId: get_agent_constraints_v1_agents__agent_id__constraints_get
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Agent Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentConstraints'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/agent-configurations/import/validate:
    post:
      tags:
      - Agent Environment
      summary: Validate Agent Import
      description: 'Validate an agent import request without saving.


        Supports three input methods with deterministic access levels:

        - agent_url:   Remote black_box - Just an endpoint URL to call

        - agent_card:  Local grey_box - Upload agent configuration/card JSON

        - source_code: Local white_box - Upload agent source code files


        Returns validation status, access level, and parsed agent card for preview.'
      operationId: validate_agent_import_v1_agent_configurations_import_validate_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnifiedImportRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnifiedValidationResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/agent-configurations/import:
    post:
      tags:
      - Agent Environment
      summary: Import Agent Unified
      description: 'Import an agent using the unified import endpoint.


        Supports three input methods with deterministic access levels:

        - agent_url:   Remote black_box - Just an endpoint URL to call

        - agent_card:  Local grey_box - Upload agent configuration/card JSON

        - source_code: Local white_box - Upload agent source code files


        Access level is determined by input method (not content).'
      operationId: import_agent_unified_v1_agent_configurations_import_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnifiedImportRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnifiedImportResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/personas/{id}:
    get:
      tags:
      - Agent Environment
      summary: Get Persona
      description: 'Get a single persona by ID.


        Requires persona:read permission and team_id query parameter. The user''s JWT must be scoped to that team.'
      operationId: get_persona_v1_personas__id__get
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      - name: team_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Team scope (required); must match a team the user has access to
          title: Team Id
        description: Team scope (required); must match a team the user has access to
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Persona'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - Agent Environment
      summary: Update Persona
      description: 'Update an existing persona.


        Supports partial updates - only provided fields will be updated.

        Requires persona:write permission.'
      operationId: update_persona_v1_personas__id__put
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonaUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Persona'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Agent Environment
      summary: Delete Persona
      description: 'Delete a persona.


        Requires persona:write permission.'
      operationId: delete_persona_v1_personas__id__delete
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/personas/:
    get:
      tags:
      - Agent Environment
      summary: List Personas
      description: 'List personas with filtering and pagination.


        Requires persona:read permission and team_id query parameter. The user''s JWT must be scoped to that team.'
      operationId: list_personas_v1_personas__get
      parameters:
      - name: team_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Team scope (required); must match a team the user has access to
          title: Team Id
        description: Team scope (required); must match a team the user has access to
      - name: intents
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: 'Filter by intent(s): benign, curious, adversarial, malicious'
          title: Intents
        description: 'Filter by intent(s): benign, curious, adversarial, malicious'
      - name: is_preset
        in: query
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          description: Filter by preset status
          title: Is Preset
        description: Filter by preset status
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Search in name, description, and role
          title: Search
        description: Search in name, description, and role
      - 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
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonaListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Agent Environment
      summary: Create Persona
      description: 'Create a new persona.


        Requires persona:write permission for the team_id in the request body.'
      operationId: create_persona_v1_personas__post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonaCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Persona'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/personas/presets/:
    get:
      tags:
      - Agent Environment
      summary: List Presets
      description: 'List system preset personas.


        Requires persona:read permission and team_id query parameter. The user''s JWT must be scoped to that team.'
      operationId: list_presets_v1_personas_presets__get
      parameters:
      - name: team_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Team scope (required); must match a team the user has access to
          title: Team Id
        description: Team scope (required); must match a team the user has access to
      - name: preset_category
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Filter by preset category: professional, adversarial, support'
          title: Preset Category
        description: 'Filter by preset category: professional, adversarial, support'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 250
          minimum: 1
          description: Maximum number of results
          default: 100
          title: Limit
        description: Maximum number of results
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Number of results to skip
          default: 0
          title: Offset
        description: Number of results to skip
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonaListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/personas/from-preset/{preset_id}:
    post:
      tags:
      - Agent Environment
      summary: Create From Preset
      description: 'Create a new persona from a system preset.


        Requires persona:write permission.'
      operationId: create_from_preset_v1_personas_from_preset__preset_id__post
      parameters:
      - name: preset_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Preset Id
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/CreateFromPresetRequest'
              - type: 'null'
              title: Request
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Persona'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/demographics/:
    get:
      tags:
      - Agent Environment
      summary: List Dimensions
      description: 'List demographic dimensions.


        Requires agent:read permission (dimensions are global reference data).'
      operationId: list_dimensions_v1_demographics__get
      parameters:
      - name: protected_class_only
        in: query
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          description: Filter to only protected class dimensions
          title: Protected Class Only
        description: Filter to only protected class dimensions
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 250
          minimum: 1
          description: Maximum number of results
          default: 100
          title: Limit
        description: Maximum number of results
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Number of results to skip
          default: 0
          title: Offset
        description: Number of results to skip
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/src__service_agent_environment__api__dimensions__DimensionListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Agent Environment
      summary: Create Dimension
      description: 'Create a new demographic dimension.


        Requires super admin permission (dimensions are global).'
      operationId: create_dimension_v1_demographics__post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DemographicDimensionCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DemographicDimension'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/demographics/{dimension_id}:
    get:
      tags:
      - Agent Environment
      summary: Get Dimension
      description: Get a dimension by ID, including its values.
      operationId: get_dimension_v1_demographics__dimension_id__get
      parameters:
      - name: dimension_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Dimension Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DemographicDimension'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - Agent Environment
      summary: Update Dimension
      description: 'Update a demographic dimension.


        Requires super admin permission.'
      operationId: update_dimension_v1_demographics__dimension_id__put
      parameters:
      - name: dimension_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Dimension Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DemographicDimensionUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DemographicDimension'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Agent Environment
      summary: Delete Dimension
      description: 'Delete a demographic dimension and all its values.


        Requires super admin permission.'
      operationId: delete_dimension_v1_demographics__dimension_id__delete
      parameters:
      - name: dimension_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Dimension Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/demographics/by-name/{name}:
    get:
      tags:
      - Agent Environment
      summary: Get Dimension By Name
      description: Get a dimension by name, including its values.
      operationId: get_dimension_by_name_v1_demographics_by_name__name__get
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
          title: Name
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DemographicDimension'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/demographics/{dimension_id}/values:
    get:
      tags:
      - Agent Environment
      summary: List Values
      description: List values for a dimension.
      operationId: list_values_v1_demographics__dimension_id__values_get
      parameters:
      - name: dimension_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Dimension Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 500
          minimum: 1
          description: Maximum number of results
          default: 250
          title: Limit
        description: Maximum number of results
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Number of results to skip
          default: 0
          title: Offset
        description: Number of results to skip
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/src__service_agent_environment__api__dimensions__ValueListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Agent Environment
      summary: Add Value
      description: 'Add a value to a dimension.


        Requires super admin permission.'
      operationId: add_value_v1_demographics__dimension_id__values_post
      parameters:
      - name: dimension_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Dimension Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DemographicValueCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DemographicValue'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/demographics/{dimension_id}/values/bulk:
    post:
      tags:
      - Agent Environment
      summary: Bulk Add Values
      description: 'Bulk add values to a dimension.


        Requires super admin permission.'
      operationId: bulk_add_values_v1_demographics__dimension_id__values_bulk_post
      parameters:
      - name: dimension_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Dimension Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/src__service_agent_environment__api__dimensions__BulkValuesRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                type: a

# --- truncated at 32 KB (165 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vijil/refs/heads/main/openapi/vijil-agent-environment-api-openapi.yml