openapi: 3.1.0
info:
  title: Hyfn Public API
  description: >
    Public REST API for managing your AI workforce programmatically. 

    Create and manage AI agents, knowledge sources, scheduled jobs, track
    billable work tasks, and access invoices.


    **⚠️ SECURITY WARNING**: This API is currently in development and uses a
    system-wide API key. 

    Do not use in production without implementing per-organization API keys. See
    documentation for details.
  version: 1.0.0
  contact:
    email: support@hyfn.ai
    url: https://hyfn.ai/support
  license:
    name: MIT
    url: https://opensource.org/license/mit/
servers:
  - url: https://your-domain.replit.app/api/public
    description: Production server
  - url: http://localhost:5000/api/public
    description: Local development server
security:
  - ApiKeyAuth: []
    OrgIdAuth: []
tags:
  - name: Agents
    description: Manage AI agents
  - name: Knowledge
    description: Manage knowledge sources and documents
  - name: Jobs
    description: Manage scheduled AI jobs
  - name: Work Items
    description: Track billable AI work tasks
  - name: Invoices
    description: Access invoices and billing information (read-only)
  - name: Skills
    description: Browse and execute integration actions from connected tools
paths:
  /agents:
    get:
      summary: List all agents
      description: Returns a list of all AI agents for your organization.
      operationId: listAgents
      tags:
        - Agents
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  agents:
                    type: array
                    items:
                      $ref: '#/components/schemas/Agent'
              examples:
                success:
                  $ref: '#/components/examples/ListAgentsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      summary: Create agent
      description: Creates a new AI agent.
      operationId: createAgent
      tags:
        - Agents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgent'
            examples:
              default:
                $ref: '#/components/examples/CreateAgentRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  agent:
                    $ref: '#/components/schemas/Agent'
              examples:
                success:
                  $ref: '#/components/examples/CreateAgentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /agents/{agentId}:
    get:
      summary: Get agent by ID
      description: Returns details of a specific AI agent.
      operationId: getAgent
      tags:
        - Agents
      parameters:
        - $ref: '#/components/parameters/AgentId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  agent:
                    $ref: '#/components/schemas/Agent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      summary: Update agent
      description: Updates an existing AI agent.
      operationId: updateAgent
      tags:
        - Agents
      parameters:
        - $ref: '#/components/parameters/AgentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAgent'
            examples:
              default:
                $ref: '#/components/examples/UpdateAgentRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  agent:
                    $ref: '#/components/schemas/Agent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      summary: Delete agent
      description: Deletes an AI agent.
      operationId: deleteAgent
      tags:
        - Agents
      parameters:
        - $ref: '#/components/parameters/AgentId'
      responses:
        '204':
          description: Success - no content
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /knowledge:
    get:
      summary: List knowledge sources
      description: Returns a list of all knowledge sources for your organization.
      operationId: listKnowledgeSources
      tags:
        - Knowledge
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  knowledgeSources:
                    type: array
                    items:
                      $ref: '#/components/schemas/KnowledgeSource'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      summary: Create knowledge source
      description: Creates a new knowledge source.
      operationId: createKnowledgeSource
      tags:
        - Knowledge
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateKnowledgeSource'
            examples:
              website:
                $ref: '#/components/examples/CreateKnowledgeSourceWebsite'
              document:
                $ref: '#/components/examples/CreateKnowledgeSourceDocument'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  knowledgeSource:
                    $ref: '#/components/schemas/KnowledgeSource'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /knowledge/{knowledgeId}:
    get:
      summary: Get knowledge source
      description: Returns details of a specific knowledge source.
      operationId: getKnowledgeSource
      tags:
        - Knowledge
      parameters:
        - $ref: '#/components/parameters/KnowledgeId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  knowledgeSource:
                    $ref: '#/components/schemas/KnowledgeSource'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      summary: Update knowledge source
      description: Updates an existing knowledge source.
      operationId: updateKnowledgeSource
      tags:
        - Knowledge
      parameters:
        - $ref: '#/components/parameters/KnowledgeId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateKnowledgeSource'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  knowledgeSource:
                    $ref: '#/components/schemas/KnowledgeSource'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      summary: Delete knowledge source
      description: Deletes a knowledge source.
      operationId: deleteKnowledgeSource
      tags:
        - Knowledge
      parameters:
        - $ref: '#/components/parameters/KnowledgeId'
      responses:
        '204':
          description: Success - no content
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /jobs:
    get:
      summary: List jobs
      description: Returns a list of all scheduled jobs for your organization.
      operationId: listJobs
      tags:
        - Jobs
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobs:
                    type: array
                    items:
                      $ref: '#/components/schemas/Job'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      summary: Create job
      description: Creates a new scheduled job.
      operationId: createJob
      tags:
        - Jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateJob'
            examples:
              default:
                $ref: '#/components/examples/CreateJobRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  job:
                    $ref: '#/components/schemas/Job'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /jobs/{jobId}:
    get:
      summary: Get job
      description: Returns details of a specific job.
      operationId: getJob
      tags:
        - Jobs
      parameters:
        - $ref: '#/components/parameters/JobId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  job:
                    $ref: '#/components/schemas/Job'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      summary: Update job
      description: Updates an existing job.
      operationId: updateJob
      tags:
        - Jobs
      parameters:
        - $ref: '#/components/parameters/JobId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateJob'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  job:
                    $ref: '#/components/schemas/Job'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      summary: Delete job
      description: Deletes a scheduled job.
      operationId: deleteJob
      tags:
        - Jobs
      parameters:
        - $ref: '#/components/parameters/JobId'
      responses:
        '204':
          description: Success - no content
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /work_items:
    get:
      summary: List work items
      description: Returns a list of all billable work items for your organization.
      operationId: listWorkItems
      tags:
        - Work Items
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  workItems:
                    type: array
                    items:
                      $ref: '#/components/schemas/WorkItem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      summary: Create work item
      description: Creates a new billable work item.
      operationId: createWorkItem
      tags:
        - Work Items
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWorkItem'
            examples:
              default:
                $ref: '#/components/examples/CreateWorkItemRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  workItem:
                    $ref: '#/components/schemas/WorkItem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /work_items/{workItemId}:
    get:
      summary: Get work item
      description: Returns details of a specific work item.
      operationId: getWorkItem
      tags:
        - Work Items
      parameters:
        - $ref: '#/components/parameters/WorkItemId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  workItem:
                    $ref: '#/components/schemas/WorkItem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      summary: Update work item
      description: >-
        Updates an existing work item. Note work items are immutable by design
        for audit purposes.
      operationId: updateWorkItem
      tags:
        - Work Items
      parameters:
        - $ref: '#/components/parameters/WorkItemId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWorkItem'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  workItem:
                    $ref: '#/components/schemas/WorkItem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      summary: Delete work item
      description: Soft-deletes a work item (maintains audit trail).
      operationId: deleteWorkItem
      tags:
        - Work Items
      parameters:
        - $ref: '#/components/parameters/WorkItemId'
      responses:
        '204':
          description: Success - no content
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /invoices:
    get:
      summary: List invoices
      description: Returns a list of all invoices for your organization (read-only).
      operationId: listInvoices
      tags:
        - Invoices
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoices:
                    type: array
                    items:
                      $ref: '#/components/schemas/Invoice'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /invoices/{invoiceId}:
    get:
      summary: Get invoice with line items
      description: Returns details of a specific invoice including all line items.
      operationId: getInvoice
      tags:
        - Invoices
      parameters:
        - $ref: '#/components/parameters/InvoiceId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoice:
                    $ref: '#/components/schemas/Invoice'
                  lineItems:
                    type: array
                    items:
                      $ref: '#/components/schemas/InvoiceLineItem'
              examples:
                success:
                  $ref: '#/components/examples/GetInvoiceResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /skills:
    get:
      summary: List connected integrations
      description: >-
        Returns a list of all integrations (skills) connected to your
        organization. These are third-party tools like Notion, Slack,
        Salesforce, etc. that your AI agents can interact with.
      operationId: listSkills
      tags:
        - Skills
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  skills:
                    type: array
                    items:
                      $ref: '#/components/schemas/Skill'
              examples:
                success:
                  $ref: '#/components/examples/ListSkillsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /skills/{integration}/actions:
    get:
      summary: List integration actions
      description: >-
        Returns all available actions for a specific integration. Actions are
        capabilities like "Create Page" in Notion or "Send Message" in Slack.
      operationId: listIntegrationActions
      tags:
        - Skills
      parameters:
        - $ref: '#/components/parameters/IntegrationName'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  actions:
                    type: array
                    items:
                      $ref: '#/components/schemas/IntegrationAction'
              examples:
                success:
                  $ref: '#/components/examples/ListIntegrationActionsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /skills/{integration}/actions/{action}/execute:
    post:
      summary: Execute integration action
      description: >-
        Executes a specific action for an integration with the provided
        parameters. For example, create a Notion page or send a Slack message.
      operationId: executeIntegrationAction
      tags:
        - Skills
      parameters:
        - $ref: '#/components/parameters/IntegrationName'
        - $ref: '#/components/parameters/ActionName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecuteAction'
            examples:
              notionCreatePage:
                $ref: '#/components/examples/ExecuteNotionActionRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: object
                    description: The result returned by the integration action
              examples:
                success:
                  $ref: '#/components/examples/ExecuteActionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '502':
          description: Integration provider error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  details:
                    type: string
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Your API key for authentication
    OrgIdAuth:
      type: apiKey
      in: header
      name: x-org-id
      description: Your organization ID
  parameters:
    AgentId:
      name: agentId
      in: path
      required: true
      description: Unique identifier for the AI agent
      schema:
        type: string
        format: uuid
      example: 6310db44-39c9-4e4d-8b67-83c45700e545
    KnowledgeId:
      name: knowledgeId
      in: path
      required: true
      description: Unique identifier for the knowledge source
      schema:
        type: string
        format: uuid
      example: 8e3bd21d-dc1b-4565-82a5-274efc6ab411
    JobId:
      name: jobId
      in: path
      required: true
      description: Unique identifier for the job
      schema:
        type: string
        format: uuid
      example: deaf5733-cb4c-40ec-9b59-5de3fab80a80
    WorkItemId:
      name: workItemId
      in: path
      required: true
      description: Unique identifier for the work item
      schema:
        type: string
        format: uuid
      example: 5f6bce01-643e-4f68-a976-02f9a9cdba9f
    InvoiceId:
      name: invoiceId
      in: path
      required: true
      description: Unique identifier for the invoice
      schema:
        type: string
        format: uuid
      example: d4c124bb-f2fd-4117-b1ec-e3021e4fa6c8
    IntegrationName:
      name: integration
      in: path
      required: true
      description: Integration identifier (e.g., notion, slack, salesforce)
      schema:
        type: string
      example: notion
    ActionName:
      name: action
      in: path
      required: true
      description: Action identifier for the integration
      schema:
        type: string
      example: NOTION_CREATE_PAGE
  schemas:
    Agent:
      type: object
      required:
        - id
        - orgId
        - name
        - modelProvider
        - modelName
        - status
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the agent
          example: 6310db44-39c9-4e4d-8b67-83c45700e545
        orgId:
          type: string
          description: Organization ID this agent belongs to
          example: demo-org-123
        name:
          type: string
          description: Name of the AI agent
          example: Marketing Bot
        modelProvider:
          type: string
          enum:
            - openai
            - watson_llama
            - watson_granite
            - snowflake_cortex
          description: AI model provider
          example: openai
        modelName:
          type: string
          description: Name of the AI model
          example: gpt-4
        systemPrompt:
          type: string
          description: System prompt for the agent
          example: You are a helpful marketing assistant
        providerConfig:
          type: object
          description: Provider-specific configuration
          example: {}
        status:
          type: string
          enum:
            - active
            - inactive
          description: Agent status
          example: active
        tasksCompleted:
          type: integer
          description: Number of tasks completed by this agent
          example: 0
        deletedAt:
          type: string
          format: date-time
          nullable: true
          description: Soft delete timestamp
        createdAt:
          type: string
          format: date-time
          description: Agent creation timestamp
        updatedAt:
          type: string
          format: date-time
          description: Agent last update timestamp
    CreateAgent:
      type: object
      required:
        - name
        - modelProvider
        - modelName
      properties:
        name:
          type: string
          description: Name of the AI agent
          example: Sales Assistant
        modelProvider:
          type: string
          enum:
            - openai
            - watson_llama
            - watson_granite
            - snowflake_cortex
          description: AI model provider
          example: openai
        modelName:
          type: string
          description: Name of the AI model
          example: gpt-4
        systemPrompt:
          type: string
          description: System prompt for the agent
          example: You are a helpful sales assistant
        providerConfig:
          type: object
          description: Provider-specific configuration
          example: {}
    UpdateAgent:
      type: object
      properties:
        name:
          type: string
          description: Name of the AI agent
        modelProvider:
          type: string
          enum:
            - openai
            - watson_llama
            - watson_granite
          description: AI model provider
        modelName:
          type: string
          description: Name of the AI model
        systemPrompt:
          type: string
          description: System prompt for the agent
        providerConfig:
          type: object
          description: Provider-specific configuration
        status:
          type: string
          enum:
            - active
            - inactive
          description: Agent status
    KnowledgeSource:
      type: object
      required:
        - id
        - orgId
        - type
        - source
        - status
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the knowledge source
        orgId:
          type: string
          description: Organization ID
        agentId:
          type: string
          format: uuid
          nullable: true
          description: Optional agent ID if knowledge is agent-specific
        type:
          type: string
          enum:
            - website
            - document
          description: Type of knowledge source
          example: website
        source:
          type: string
          description: URL for websites or filename for documents
          example: https://docs.example.com
        status:
          type: string
          enum:
            - pending
            - processing
            - completed
            - failed
          description: Processing status
          example: pending
        lastSyncedAt:
          type: string
          format: date-time
          nullable: true
          description: Last sync timestamp
        metadata:
          type: object
          nullable: true
          description: Additional metadata
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    CreateKnowledgeSource:
      type: object
      required:
        - type
        - source
      properties:
        type:
          type: string
          enum:
            - website
            - document
          description: Type of knowledge source
          example: website
        source:
          type: string
          description: URL for websites or filename for documents
          example: https://docs.example.com
        agentId:
          type: string
          format: uuid
          description: Optional agent ID
        metadata:
          type: object
          description: Additional metadata
    UpdateKnowledgeSource:
      type: object
      properties:
        type:
          type: string
          enum:
            - website
            - document
        source:
          type: string
        agentId:
          type: string
          format: uuid
          nullable: true
        status:
          type: string
          enum:
            - pending
            - processing
            - completed
            - failed
        metadata:
          type: object
    Job:
      type: object
      required:
        - id
        - orgId
        - agentId
        - name
        - schedule
        - status
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the job
        orgId:
          type: string
          description: Organization ID
        agentId:
          type: string
          format: uuid
          description: Agent assigned to this job
        name:
          type: string
          description: Job name
          example: Daily Sales Report
        description:
          type: string
          description: Job description
          example: Generate daily sales summary report
        schedule:
          type: string
          enum:
            - hourly
            - daily
            - weekly
            - monthly
          description: Job schedule frequency
          example: daily
        status:
          type: string
          enum:
            - queued
            - running
            - completed
            - failed
          description: Job status
          example: queued
        lastRunAt:
          type: string
          format: date-time
          nullable: true
          description: Last execution timestamp
        runsCount:
          type: integer
          description: Number of times executed
          example: 0
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        agentName:
          type: string
          description: Name of the assigned agent
    CreateJob:
      type: object
      required:
        - agentId
        - name
        - schedule
      properties:
        agentId:
          type: string
          format: uuid
          description: Agent to assign to this job
        name:
          type: string
          description: Job name
          example: Daily Sales Report
        description:
          type: string
          description: Job description
          example: Generate daily sales summary
        schedule:
          type: string
          enum:
            - hourly
            - daily
            - weekly
            - monthly
          description: Job schedule frequency
          example: daily
    UpdateJob:
      type: object
      properties:
        agentId:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        schedule:
          type: string
          enum:
            - hourly
            - daily
            - weekly
            - monthly
        status:
          type: string
          enum:
            - queued
            - running
            - completed
            - failed
    WorkItem:
      type: object
      required:
        - id
        - orgId
        - type
        - timeSpent
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the work item
        orgId:
          type: string
          description: Organization ID
        agentId:
          type: string
          format: uuid
          nullable: true
          description: Agent that performed the work
        jobId:
          type: string
          format: uuid
          nullable: true
          description: Associated job if applicable
        type:
          type: string
          enum:
            - model_call
            - knowledge_call
            - skill_call
            - job_task
          description: Type of work performed
          example: model_call
        description:
          type: string
          description: Work description
          example: Customer support chat
        timeSpent:
          type: string
          description: Time spent in hours (decimal)
          example: '0.5'
        humanInLoop:
          type: boolean
          description: Whether human intervention was required
          example: false
        metadata:
          type: object
          nullable: true
          description: Additional metadata
          example:
            modelName: gpt-4
            tokensUsed: 1500
        createdAt:
          type: string
          format: date-time
    CreateWorkItem:
      type: object
      required:
        - type
        - timeSpent
      properties:
        agentId:
          type: string
          format: uuid
          description: Agent that performed the work
        jobId:
          type: string
          format: uuid
          description: Associated job if applicable
        type:
          type: string
          enum:
            - model_call
            - knowledge_call
            - skill_call
            - job_task
          description: Type of work performed
          example: model_call
        description:
          type: string
          description: Work description
        timeSpent:
          type: string
          description: Time spent in hours (decimal)
          example: '0.25'
        humanInLoop:
          type: boolean
          description: Whether human intervention was required
          default: false
        metadata:
          type: object
          description: Additional metadata
    UpdateWorkItem:
      type: object
      properties:
        description:
          type: string
        metadata:
          type: object
    Invoice:
      type: object
      required:
        - id
        - orgId
        - amount
        - currency
        - status
        - periodStart
        - periodEnd
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the invoice
        orgId:
          type: string
          description: Organization ID
        amount:
          type: string
          description: Total invoice amount
          example: '19.99'
        currency:
          type: string
          description: Currency code
          example: usd
        status:
          type: string
          enum:
            - pending
            - paid
            - failed
            - cancelled
          description: Invoice status
          example: pending
        stripeInvoiceId:
          type: string
          nullable: true
          description: Stripe invoice ID
          example: inv_...
        stripeInvoiceUrl:
          type: string
          nullable: true
          description: Stripe invoice URL
          example: https://invoice.stripe.com/...
        periodStart:
          type: string
          format: date-time
          description: Billing period start
        periodEnd:
          type: string
          format: date-time
          description: Billing period end
        paidAt:
          type: string
          format: date-time
          nullable: true
          description: Payment timestamp
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    InvoiceLineItem:
      type: object
      required:
        - id
        - invoiceId
        - description
        - quantity
        - unitPrice
        - amount
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the line item
        invoiceId:
          type: string
          format: uuid
          description: Associated invoice ID
        workTaskId:
          type: string
          format: uuid
          nullable: true
          description: Associated work task ID
        description:
          type: string
          description: Line item description
          example: Model API calls - 2.5 hours
        quantity:
          type: string
          description: Quantity (decimal)
          example: '2.5000'
        unitPrice:
          type: string
          description: Price per unit
          example: '10.00'
        amount:
          type: string
          description: Total line item amount
          example: '25.00'
        createdAt:
          type: string
          format: date-time
    Skill:
      type: object
      required:
        - id
        - name
        - displayName
        - isConnected
      properties:
        id:
          type: string
          description: Unique identifier for the integration
          example: tool-notion
        name:
          type: string
          description: Integration identifier
          example: notion
        displayName:
          type: string
          description: Human-readable integration name
          example: Notion
        description:
          type: string
          nullable: true
          description: Integration description
          example: Note-taking and collaboration workspace
        iconUrl:
          type: string
          nullable: true
          description: Integration icon URL
          example: https://example.com/notion-icon.png
        category:
          type: string
          nullable: true
          description: Integration category
          example: Productivity
        isConnected:
          type: boolean
          description: Whether the integration is connected
          example: true
        connectedAt:
          type: string
          format: date-time
          nullable: true
          description: Connection timestamp
    IntegrationAction:
      type: object
      required:
        - action
        - name
        - description
      properties:
        action:
          type: string
          description: Action identifier
          example: NOTION_CREATE_PAGE
        name:
          type: string
          description: Human-readable action name
          example: Create a Page
        description:
          type: string
          description: Action description
          example: Create a new page in a Notion database
        parameters:
          type: object
          description: JSON schema describing action parameters
          example:
            type: object
            properties:
              parent:
                type: object
                description: Parent database or page
              properties:
                type: object
                description: Page properties
    ExecuteAction:
      type: object
      properties:
        parameters:
          type: object
          description: Parameters to pass to the action
          example:
            parent:
              database_id: abc123
            properties:
              Name:
                title:
                  - text:
                      content: My New Page
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
          example: Missing required headers
        details:
          type: string
          description: Additional error details
          example: x-api-key and x-org-id headers are required
  responses:
    BadRequest:
      description: Bad Request - Invalid input or missing required headers
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missing_headers:
              value:
                error: Missing required headers
                details: x-api-key and x-org-id headers are required
            validation_error:
              value:
                error: Validation error
                details:
                  - expected: '''openai'' | ''watson_llama'' | ''watson_granite'''
                    received: undefined
                    code: invalid_type
                    path:
                      - modelProvider
                    message: Required
    Unauthorized:
      description: Unauthorized - Invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            invalid_key:
              value:
                error: Invalid API key
    Forbidden:
      description: Forbidden - Access denied (cross-tenant access attempt)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            access_denied:
              value:
                error: Access denied
    NotFound:
      description: Not Found - Resource does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            not_found:
              value:
                error: Agent not found
  examples:
    ListAgentsResponse:
      value:
        agents:
          - id: 6310db44-39c9-4e4d-8b67-83c45700e545
            orgId: demo-org-123
            name: Marketing Bot
            modelProvider: openai
            modelName: gpt-4
            systemPrompt: You are a marketing expert
            providerConfig: {}
            status: active
            tasksCompleted: 0
            deletedAt: null
            createdAt: '2025-10-18T07:49:27.749Z'
            updatedAt: '2025-10-18T07:49:27.749Z'
    CreateAgentRequest:
      value:
        name: Sales Assistant
        modelProvider: openai
        modelName: gpt-4
        systemPrompt: You are a helpful sales assistant
    CreateAgentResponse:
      value:
        agent:
          id: d0312fcf-0bd5-40fe-a5da-1fe1af8e5d13
          orgId: demo-org-123
          name: Sales Assistant
          modelProvider: openai
          modelName: gpt-4
          systemPrompt: You are a helpful sales assistant
          providerConfig: {}
          status: active
          tasksCompleted: 0
          deletedAt: null
          createdAt: '2025-10-19T19:13:40.453Z'
          updatedAt: '2025-10-19T19:13:40.453Z'
    UpdateAgentRequest:
      value:
        name: Updated Sales Assistant
        systemPrompt: You are an expert sales assistant
    CreateKnowledgeSourceWebsite:
      value:
        type: website
        source: https://docs.example.com
    CreateKnowledgeSourceDocument:
      value:
        type: document
        source: company-handbook.pdf
    CreateJobRequest:
      value:
        agentId: 6310db44-39c9-4e4d-8b67-83c45700e545
        name: Daily Sales Report
        description: Generate daily sales summary
        schedule: daily
    CreateWorkItemRequest:
      value:
        agentId: 6310db44-39c9-4e4d-8b67-83c45700e545
        jobId: deaf5733-cb4c-40ec-9b59-5de3fab80a80
        type: model_call
        description: Customer support chat
        timeSpent: '0.5'
        metadata:
          modelName: gpt-4
          tokensUsed: 1500
    GetInvoiceResponse:
      value:
        invoice:
          id: d4c124bb-f2fd-4117-b1ec-e3021e4fa6c8
          orgId: demo-org-123
          amount: '25.00'
          currency: usd
          status: pending
          stripeInvoiceId: inv_abc123
          stripeInvoiceUrl: https://invoice.stripe.com/i/acct_abc/test_xyz
          periodStart: '2025-01-01T00:00:00Z'
          periodEnd: '2025-01-31T23:59:59Z'
          paidAt: null
          createdAt: '2025-02-01T00:00:00Z'
          updatedAt: '2025-02-01T00:00:00Z'
        lineItems:
          - id: line_item_1
            invoiceId: d4c124bb-f2fd-4117-b1ec-e3021e4fa6c8
            workTaskId: 5f6bce01-643e-4f68-a976-02f9a9cdba9f
            description: Model API calls - 2.5 hours
            quantity: '2.5000'
            unitPrice: '10.00'
            amount: '25.00'
            createdAt: '2025-02-01T00:00:00Z'
    ListSkillsResponse:
      value:
        skills:
          - id: tool-notion
            name: notion
            displayName: Notion
            description: Note-taking and collaboration workspace
            iconUrl: https://logo.clearbit.com/notion.so
            category: Productivity
            isConnected: true
            connectedAt: '2025-01-15T10:30:00Z'
          - id: tool-slack
            name: slack
            displayName: Slack
            description: Team communication platform
            iconUrl: https://logo.clearbit.com/slack.com
            category: Communication
            isConnected: true
            connectedAt: '2025-01-16T14:20:00Z'
    ListIntegrationActionsResponse:
      value:
        actions:
          - action: NOTION_CREATE_PAGE
            name: Create a Page
            description: Create a new page in a Notion database
            parameters:
              type: object
              properties:
                parent:
                  type: object
                  description: Parent database or page ID
                properties:
                  type: object
                  description: Page properties
          - action: NOTION_UPDATE_PAGE
            name: Update a Page
            description: Update an existing Notion page
            parameters:
              type: object
              properties:
                page_id:
                  type: string
                  description: ID of the page to update
                properties:
                  type: object
                  description: Properties to update
          - action: NOTION_SEARCH_PAGES
            name: Search Pages
            description: Search for pages in your Notion workspace
            parameters:
              type: object
              properties:
                query:
                  type: string
                  description: Search query
    ExecuteNotionActionRequest:
      value:
        parameters:
          parent:
            database_id: abc123def456
          properties:
            Name:
              title:
                - text:
                    content: New Project
            Status:
              select:
                name: In Progress
            Priority:
              select:
                name: High
    ExecuteActionResponse:
      value:
        result:
          object: page
          id: page_abc123
          created_time: '2025-01-20T15:30:00.000Z'
          last_edited_time: '2025-01-20T15:30:00.000Z'
          properties:
            Name:
              title:
                - text:
                    content: New Project
            Status:
              select:
                name: In Progress
            Priority:
              select:
                name: High
