Biolevate Agent API

openapi: 3.1.0
info:
  title: Biolevate Agent API
  version: 1.0.0
  description: Conversational agent jobs
servers:
- url: /
  description: Biolevate Server
security:
- TOKEN: []
tags:
- name: Agent
  description: Conversational agent jobs
paths:
  /api/core/agent/jobs:
    get:
      tags:
      - Agent
      summary: List agent jobs
      description: Returns a paginated list of agent jobs for the current user, ordered by creation time (most recent first). When `conversationId` is provided, the results are restricted to jobs attached to that conversation, which lets a client replay the sequence of questions asked in a single conversation.
      operationId: listAgentJobs
      parameters:
      - name: pageSize
        in: query
        description: Page size
        required: true
        schema:
          type: integer
          format: int32
      - name: page
        in: query
        description: Page number (0-based)
        required: true
        schema:
          type: integer
          format: int32
      - name: conversationId
        in: query
        description: Restrict the results to jobs attached to this conversation
        required: false
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Successfully retrieved jobs
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/PageDataJob'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/PageDataJob'
    post:
      tags:
      - Agent
      summary: Create agent job
      description: Schedules an asynchronous agent run and returns the initial Job (status PENDING).
      operationId: createAgentJob
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentRequest'
        required: true
      responses:
        '403':
          description: Access denied
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Job'
        '200':
          description: Job created successfully
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Job'
        '400':
          description: Invalid request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Job'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Job'
  /api/core/agent/jobs/{jobId}:
    get:
      tags:
      - Agent
      summary: Get agent job
      description: Returns a single agent job by its ID
      operationId: getAgentJob
      parameters:
      - name: jobId
        in: path
        description: The job Id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved job
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Job'
        '403':
          description: Access denied - not the job owner
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Job'
        '404':
          description: Job not found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Job'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Job'
  /api/core/agent/jobs/{jobId}/results:
    get:
      tags:
      - Agent
      summary: Get agent job outputs
      description: Returns the agent's answer (text or structured), explanation, and cited annotation ids
      operationId: getAgentJobOutputs
      parameters:
      - name: jobId
        in: path
        description: The job Id
        required: true
        schema:
          type: string
      responses:
        '403':
          description: Access denied - not the job owner
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/AgentJobOutputs'
        '200':
          description: Successfully retrieved outputs
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/AgentJobOutputs'
        '404':
          description: Job not found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/AgentJobOutputs'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/AgentJobOutputs'
  /api/core/agent/jobs/{jobId}/inputs:
    get:
      tags:
      - Agent
      summary: Get agent job inputs
      description: Returns the messages, files and configuration submitted for the agent job
      operationId: getAgentJobInputs
      parameters:
      - name: jobId
        in: path
        description: The job Id
        required: true
        schema:
          type: string
      responses:
        '403':
          description: Access denied - not the job owner
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/AgentJobInputs'
        '200':
          description: Successfully retrieved inputs
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/AgentJobInputs'
        '404':
          description: Job not found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/AgentJobInputs'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/AgentJobInputs'
  /api/core/agent/jobs/{jobId}/annotations:
    get:
      tags:
      - Agent
      summary: Get agent job annotations
      description: Returns the document annotations the agent cited in its answer
      operationId: getAgentJobAnnotations
      parameters:
      - name: jobId
        in: path
        description: The job Id
        required: true
        schema:
          type: string
      responses:
        '403':
          description: Access denied - not the job owner
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EliseAnnotation'
        '200':
          description: Successfully retrieved annotations
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EliseAnnotation'
        '404':
          description: Job not found
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EliseAnnotation'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EliseAnnotation'
components:
  schemas:
    EntityId:
      type: object
      properties:
        id:
          type: string
          format: uuid
        entityType:
          type: string
          enum:
          - POLICY
          - PROJECT
          - COLLECTION
          - PROVIDER
          - FILE
          - PROCESSOR
          - JOB
          - PRESET
          - EDITABLE_DOCUMENT
          - REVIEW
          - COLLECTION_DERIVATION
          - REVIEW_REQUEST
          - MILESTONE
          - INSIGHT
          - CONCEPT_NOTE
          - ANNOTATION
          - BIBLIO_SEARCH
          - SEARCH_DOWNLOAD
          - INSIGHT_CELL_FILTER
          - INSIGHT_CELL_SORTING
          - INSIGHT_CELL_FORMAT
          - INSIGHT_GROUP
          - INSIGHTS_TABLE_CONFIG
          - INSIGHTS_TABLE_TEMPLATE
          - SEARCH_REMOVAL
          - COMMENT_THREAD
          - COMMENT
          - SMART_REVIEW
          - RIS_IMPORT_JOB
          - FORGE_WORKFLOW
          - COLLECTION_VIEW
          - SUB_COLLECTION_JOB
          - PROJECT_LABEL
          - PROJECT_GROUP
    AgentJobOutputs:
      type: object
      properties:
        answer:
          $ref: '#/components/schemas/JsonNode'
        explanation:
          type: string
        referenceIds:
          type: array
          items:
            type: string
            format: uuid
    Job:
      type: object
      properties:
        jobId:
          type: string
        status:
          type: string
          enum:
          - SUCCESS
          - FAILED
          - ABORTED
          - RUNNING
          - PENDING
        taskType:
          type: string
        createdTime:
          type: integer
          format: int64
        executionTime:
          type: number
          format: double
        errorMessage:
          type: string
        name:
          type: string
        archived:
          type: boolean
    JobLaunchConfig:
      type: object
      description: Optional job launch behaviour for input files
      properties:
        skip_unindexed_files:
          type: boolean
          description: 'When false or omitted, the request is rejected if any input file is not indexed. When true, unindexed files are excluded and the job runs on indexed files only.

            '
          example: false
    EliseAnnotation:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/AnnotationId'
        createdTime:
          type: integer
          format: int64
        owner:
          $ref: '#/components/schemas/UserId'
        space:
          $ref: '#/components/schemas/EntityId'
        data:
          $ref: '#/components/schemas/EliseAnnotationConfig'
        type:
          type: string
          enum:
          - DOCUMENT_STATEMENT
          - WEB_STATEMENT
          - ENTIRE_DOCUMENT_STATEMENT
          - EXTERNAL_DOCUMENT_STATEMENT
          - KNOWLEDGE_STATEMENT
          - REVIEW_STATEMENT
        modifiedTime:
          type: integer
          format: int64
        lastModifier:
          $ref: '#/components/schemas/UserId'
        status:
          type: string
          enum:
          - VALID
          - NOTVALID
    FilesInput:
      type: object
      properties:
        fileIds:
          type: array
          items:
            type: string
        collectionIds:
          type: array
          items:
            type: string
    UserId:
      type: object
      properties:
        id:
          type: string
    JsonNode:
      type: object
    EliseAnnotationConfig:
      type: object
      discriminator:
        propertyName: type
        mapping:
          DOCUMENT_STATEMENT: '#/components/schemas/EliseDocumentStatement'
          EXTERNAL_DOCUMENT_STATEMENT: '#/components/schemas/EliseExternalDocumentStatement'
          WEB_STATEMENT: '#/components/schemas/EliseWebStatement'
          KNOWLEDGE_STATEMENT: '#/components/schemas/EliseKnowledgeStatement'
          ENTIRE_DOCUMENT_STATEMENT: '#/components/schemas/EliseFullDocumentStatement'
          REVIEW_STATEMENT: '#/components/schemas/EliseReviewComment'
      properties:
        type:
          type: string
          enum:
          - DOCUMENT_STATEMENT
          - WEB_STATEMENT
          - ENTIRE_DOCUMENT_STATEMENT
          - EXTERNAL_DOCUMENT_STATEMENT
          - KNOWLEDGE_STATEMENT
          - REVIEW_STATEMENT
    AgentInput:
      type: object
      description: A single input item submitted to the agent (role + text content)
      properties:
        role:
          type: string
          description: Author of the item
          enum:
          - system
          - user
          - assistant
          - SYSTEM
          - USER
          - ASSISTANT
          example: USER
        content:
          type: string
          description: Plain text content of the item
          example: Summarize the attached report.
      required:
      - content
      - role
    AgentJobInputs:
      type: object
      properties:
        message:
          type: string
        messages:
          type: array
          items:
            $ref: '#/components/schemas/AgentInput'
        files:
          $ref: '#/components/schemas/FilesInput'
        outputModelSchema:
          $ref: '#/components/schemas/JsonNode'
        completionConfig:
          $ref: '#/components/schemas/AgentCompletionConfig'
        maxIterations:
          type: integer
          format: int32
        conversationId:
          type: string
          format: uuid
    AnnotationId:
      type: object
      properties:
        id:
          type: string
          format: uuid
        entityType:
          type: string
          enum:
          - POLICY
          - PROJECT
          - COLLECTION
          - PROVIDER
          - FILE
          - PROCESSOR
          - JOB
          - PRESET
          - EDITABLE_DOCUMENT
          - REVIEW
          - COLLECTION_DERIVATION
          - REVIEW_REQUEST
          - MILESTONE
          - INSIGHT
          - CONCEPT_NOTE
          - ANNOTATION
          - BIBLIO_SEARCH
          - SEARCH_DOWNLOAD
          - INSIGHT_CELL_FILTER
          - INSIGHT_CELL_SORTING
          - INSIGHT_CELL_FORMAT
          - INSIGHT_GROUP
          - INSIGHTS_TABLE_CONFIG
          - INSIGHTS_TABLE_TEMPLATE
          - SEARCH_REMOVAL
          - COMMENT_THREAD
          - COMMENT
          - SMART_REVIEW
          - RIS_IMPORT_JOB
          - FORGE_WORKFLOW
          - COLLECTION_VIEW
          - SUB_COLLECTION_JOB
          - PROJECT_LABEL
          - PROJECT_GROUP
    CreateAgentRequest:
      type: object
      description: Request to schedule a new agent run
      properties:
        message:
          type: string
          description: 'Stateful mode: the new user message for this turn. Prior turns are loaded server-side from `conversationId`. Mutually exclusive with `messages`.

            '
          example: Summarize the attached report and list the main risks.
        messages:
          type: array
          items:
            $ref: '#/components/schemas/AgentInput'
        files:
          $ref: '#/components/schemas/FilesInput'
          description: Files the agent can read from
        config:
          $ref: '#/components/schemas/JobLaunchConfig'
          description: Optional job launch behaviour for input files
        historyInputValid:
          type: boolean
        conversationIdValid:
          type: boolean
        output_model_schema:
          $ref: '#/components/schemas/JsonNode'
          description: 'Optional JSON Schema constraining the agent''s final answer to a structured object. Free-form: any valid JSON Schema is accepted'
          example:
            type: object
            properties:
              verdict:
                type: string
            required:
            - verdict
        completion_config:
          $ref: '#/components/schemas/AgentCompletionConfig'
          description: Per-completion LLM knobs (model preset, temperature, max tokens)
        max_iterations:
          type: integer
          format: int32
          description: Hard cap on the number of agent-loop iterations
          example: 10
        conversation_id:
          type: string
          format: uuid
          description: 'Stateful only: continue an existing server session. Omit to start a new conversation. Must not be set for stateless runs.'
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
    AgentCompletionConfig:
      type: object
      description: Per-completion LLM knobs for an agent run
      properties:
        model:
          type: string
          description: Semantic model preset (defaults to BALANCED when omitted)
          enum:
          - FAST
          - BALANCED
          example: BALANCED
        temperature:
          type: number
          format: double
          description: Sampling temperature
          example: 0.7
          maximum: 2.0
          minimum: 0.0
        max_completion_tokens:
          type: integer
          format: int32
          description: Hard cap on response tokens
          example: 2048
          maximum: 32768
          minimum: 1
    PageDataJob:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Job'
        totalPages:
          type: integer
          format: int32
        totalElements:
          type: integer
          format: int64
        hasNext:
          type: boolean
  securitySchemes:
    TOKEN:
      type: http
      scheme: bearer
      bearerFormat: JWT