openapi: 3.0.0
info:
  title: Frontline Public API
  version: 1.0.0
  description: Public API for accessing agents, flows, and analytics.
  license:
    name: Proprietary
    url: https://www.getfrontline.ai/terms-and-conditions
servers:
  - url: https://prod-api.getfrontline.ai
tags:
  - name: Agents
    description: Manage and view AI agent data.
  - name: Flows
    description: Access flows associated with agents.
  - name: Workflows
    description: Track and analyze account-wide workflows.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
  schemas:
    Agent:
      type: object
      properties:
        id:
          type: string
          example: 550e8400-e29b-41d4-a716-446655440000
        name:
          type: string
          example: Support Bot
        description:
          type: string
          nullable: true
          example: Main customer support agent
        status:
          type: string
          enum:
            - NONE
            - ACTIVE
            - INACTIVE
            - TRAINING
            - TRAIN_ERROR
          example: ACTIVE
        createdAt:
          type: string
          example: '2024-01-01T12:00:00Z'
        updatedAt:
          type: string
          example: '2024-01-01T12:00:00Z'
      required:
        - id
        - name
        - description
        - status
        - createdAt
        - updatedAt
    Error:
      type: object
      properties:
        message:
          type: string
          example: Detailed error message
      required:
        - message
    Flow:
      type: object
      properties:
        id:
          type: number
          example: 101
        name:
          type: string
          example: Order Retrieval
        description:
          type: string
          nullable: true
          example: Extracts order info from DB
        status:
          type: string
          enum:
            - ACTIVE
            - SUSPENDED
            - DELETED
            - DRAFT
          example: ACTIVE
        createdAt:
          type: string
          example: '2024-01-01T12:00:00Z'
        updatedAt:
          type: string
          example: '2024-01-01T12:00:00Z'
        runCount:
          type: number
          example: 450
      required:
        - id
        - name
        - description
        - status
        - createdAt
        - updatedAt
        - runCount
    AgentAnalytics:
      type: object
      properties:
        summary:
          type: object
          properties:
            totalCredits:
              type: number
              example: 500.25
            totalConversations:
              type: number
              example: 150
          required:
            - totalCredits
            - totalConversations
        creditsByDate:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
                example: '2024-01-01'
              totalCredits:
                type: number
                example: 25.5
              conversationCount:
                type: number
                example: 10
            required:
              - date
              - totalCredits
              - conversationCount
      required:
        - summary
        - creditsByDate
    Workflow:
      type: object
      properties:
        id:
          type: number
          example: 501
        name:
          type: string
          example: Daily CRM Sync
        description:
          type: string
          nullable: true
          example: Syncs contacts to HubSpot
        status:
          type: string
          enum:
            - ACTIVE
            - DELETED
            - DRAFT
          example: ACTIVE
        triggerType:
          type: string
          nullable: true
          enum:
            - CONVERSATION_ENDED
            - CONTACT_CREATED
            - CONTACT_UPDATED
            - FEEDBACK_CAPTURED
            - INCOMING_WEBHOOK
            - TABLE_ROW_CREATED
            - SCHEDULED_TRIGGER
            - CONVERSATION_IDLE
          example: CONVERSATION_ENDED
        createdAt:
          type: string
          example: '2024-01-01T12:00:00Z'
        updatedAt:
          type: string
          example: '2024-01-01T12:00:00Z'
        runsCount:
          type: number
          example: 1200
        runsFailedCount:
          type: number
          example: 5
        lastRunDate:
          type: string
          nullable: true
          example: '2024-01-01T12:00:00Z'
      required:
        - id
        - name
        - description
        - status
        - triggerType
        - createdAt
        - updatedAt
        - runsCount
        - runsFailedCount
        - lastRunDate
    WorkflowAnalytics:
      type: object
      properties:
        runsByDate:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
                nullable: true
                example: '2024-01-01'
              totalRuns:
                type: number
                example: 100
              completedRuns:
                type: number
                example: 95
              failedRuns:
                type: number
                example: 5
              pendingRuns:
                type: number
                example: 0
              totalCredits:
                type: number
                example: 250.5
            required:
              - date
              - totalRuns
              - completedRuns
              - failedRuns
              - pendingRuns
              - totalCredits
        summary:
          type: object
          properties:
            totalRuns:
              type: number
              example: 1000
            completedRuns:
              type: number
              example: 950
            failedRuns:
              type: number
              example: 50
            pendingRuns:
              type: number
              example: 0
            totalCredits:
              type: number
              example: 2500
            averageCreditsPerRun:
              type: number
              example: 2.5
            nonExecutedRuns:
              type: number
              example: 10
          required:
            - totalRuns
            - completedRuns
            - failedRuns
            - pendingRuns
            - totalCredits
            - averageCreditsPerRun
            - nonExecutedRuns
      required:
        - runsByDate
        - summary
  parameters: {}
paths:
  /public/v1/agents:
    get:
      summary: List all agents
      operationId: listAgents
      description: Returns a list of agents associated with the account.
      security:
        - bearerAuth: []
      tags:
        - Agents
      parameters:
        - schema:
            type: string
            enum:
              - NONE
              - ACTIVE
              - INACTIVE
              - TRAINING
              - TRAIN_ERROR
            example: ACTIVE
          required: false
          name: status
          in: query
      responses:
        '200':
          description: A list of agents
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Agent'
                required:
                  - results
                description: Standard list response
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /public/v1/agents/{agentId}/flows:
    get:
      summary: List flows for an agent
      operationId: listAgentFlows
      description: >-
        Returns a list of flows associated with a specific agent. Nodes and
        logic are excluded.
      security:
        - bearerAuth: []
      tags:
        - Flows
      parameters:
        - schema:
            type: string
            example: uuid-xxxx-xxxx
          required: true
          name: agentId
          in: path
        - schema:
            type: string
            enum:
              - ACTIVE
              - SUSPENDED
              - DELETED
              - DRAFT
            example: ACTIVE
          required: false
          name: status
          in: query
      responses:
        '200':
          description: A list of flows
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Flow'
                required:
                  - results
                description: Standard list response
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /public/v1/agents/{agentId}/analytics:
    get:
      summary: Get agent analytics
      operationId: getAgentAnalytics
      description: Returns credit usage and conversation counts for a specific agent.
      security:
        - bearerAuth: []
      tags:
        - Agents
      parameters:
        - schema:
            type: string
            example: uuid-xxxx-xxxx
          required: true
          name: agentId
          in: path
        - schema:
            type: string
            nullable: true
            example: '2024-01-01'
          required: false
          name: startDate
          in: query
        - schema:
            type: string
            nullable: true
            example: '2024-01-01'
          required: false
          name: endDate
          in: query
      responses:
        '200':
          description: Agent analytics data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentAnalytics'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /public/v1/workflows:
    get:
      summary: List all workflows
      operationId: listWorkflows
      description: >-
        Returns a list of workflows associated with the account. Nodes and logic
        are excluded.
      security:
        - bearerAuth: []
      tags:
        - Workflows
      parameters:
        - schema:
            type: string
            enum:
              - ACTIVE
              - DELETED
              - DRAFT
            example: ACTIVE
          required: false
          name: status
          in: query
      responses:
        '200':
          description: A list of workflows
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workflow'
                required:
                  - results
                description: Standard list response
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /public/v1/workflows/{workflowId}/analytics:
    get:
      summary: Get workflow analytics
      operationId: getWorkflowAnalytics
      description: >-
        Returns analytics for a specific workflow, including runs by date and
        summary.
      security:
        - bearerAuth: []
      tags:
        - Workflows
      parameters:
        - schema:
            type: number
            nullable: true
            example: 42
          required: false
          name: workflowId
          in: path
        - schema:
            type: string
            nullable: true
            example: '2024-01-01'
          required: false
          name: startDate
          in: query
        - schema:
            type: string
            nullable: true
            example: '2024-01-01'
          required: false
          name: endDate
          in: query
      responses:
        '200':
          description: Workflow analytics data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowAnalytics'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
