openapi: 3.0.3
info:
  title: Alfred AI API
  version: 1.0.0
  description: |
    The Alfred AI API provides programmatic access to Alfred's AI agent platform —
    chat with AI, execute 13,000+ tools, deploy autonomous agent fleets, manage voice
    conferences, and browse the marketplace.

    ## Authentication
    All endpoints (except discovery) require a Bearer token:
    ```
    Authorization: Bearer ak_live_xxxxxxxx...
    ```
    Generate API keys at https://gositeme.com/developer-portal

    ## Rate Limits
    | Tier | Per Minute | Per Hour | Per Day |
    |------|-----------|---------|---------|
    | Free | 10 | 200 | 1,000 |
    | Starter | 30 | 600 | 5,000 |
    | Pro | 60 | 2,000 | 20,000 |
    | Enterprise | 200 | 10,000 | 100,000 |

    Rate limit headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
  contact:
    name: GoSiteMe Developer Support
    email: support@gositeme.com
    url: https://gositeme.com/help
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  termsOfService: https://gositeme.com/terms-of-service

servers:
  - url: https://gositeme.com/api/v1
    description: Production
  - url: https://staging.gositeme.com/api/v1
    description: Staging

tags:
  - name: Discovery
    description: API info and health
  - name: Chat
    description: Conversational AI with Alfred
  - name: Tools
    description: Browse and execute 13,000+ AI tools
  - name: Agents
    description: Create and manage autonomous AI agents
  - name: Fleets
    description: Orchestrate multi-agent fleets
  - name: Voice
    description: Voice calls and conference rooms
  - name: Marketplace
    description: Browse tools, templates, and integrations
  - name: Usage
    description: Usage analytics and billing

security:
  - BearerAuth: []

paths:
  /:
    get:
      tags: [Discovery]
      summary: API discovery
      description: Returns API version, status, and available endpoints.
      security: []
      operationId: getApiInfo
      responses:
        '200':
          description: API info
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                    example: Alfred API
                  version:
                    type: string
                    example: 1.0.0
                  status:
                    type: string
                    example: operational
                  docs:
                    type: string
                    format: uri
                  endpoints:
                    type: object
                    additionalProperties:
                      type: string

  /chat:
    get:
      tags: [Chat]
      summary: Chat endpoint info
      operationId: getChatInfo
      responses:
        '200':
          description: Chat endpoint documentation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
    post:
      tags: [Chat]
      summary: Send a message to Alfred
      operationId: sendChat
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatRequest'
      responses:
        '200':
          description: Chat response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ChatResponse'
                  meta:
                    type: object
                    properties:
                      execution_time_ms:
                        type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'

  /tools:
    get:
      tags: [Tools]
      summary: List tools
      description: Browse and search the tool catalog with filters and pagination.
      operationId: listTools
      parameters:
        - name: search
          in: query
          schema:
            type: string
            maxLength: 200
          description: Text search (also accepts `q`)
        - name: category
          in: query
          schema:
            type: string
            maxLength: 80
        - name: tier
          in: query
          schema:
            type: string
            maxLength: 30
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: Paginated tool list
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginatedResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/ToolSummary'

  /tools/categories:
    get:
      tags: [Tools]
      summary: List tool categories
      operationId: listToolCategories
      responses:
        '200':
          description: Tool categories with counts
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        label:
                          type: string
                        count:
                          type: integer
                        tools:
                          type: array
                          items:
                            type: string
                  meta:
                    type: object
                    properties:
                      total_categories:
                        type: integer
                      total_tools:
                        type: integer

  /tools/{name}:
    get:
      tags: [Tools]
      summary: Get tool details
      operationId: getTool
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Tool details with input schema
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ToolDetail'
        '404':
          $ref: '#/components/responses/NotFound'

  /tools/{name}/execute:
    post:
      tags: [Tools]
      summary: Execute a tool
      operationId: executeTool
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                input:
                  type: string
                  description: Primary input for the tool
                params:
                  type: object
                  description: Additional tool-specific parameters
                  additionalProperties: true
      responses:
        '200':
          description: Tool execution result
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ToolExecuteResult'
        '502':
          description: Tool execution failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /agents:
    get:
      tags: [Agents]
      summary: List agents
      operationId: listAgents
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [queued, running, completed, failed, cancelled]
        - name: fleet_id
          in: query
          schema:
            type: integer
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: Paginated agent list
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginatedResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Agent'
    post:
      tags: [Agents]
      summary: Create an agent
      operationId: createAgent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentRequest'
      responses:
        '201':
          description: Agent created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Agent'

  /agents/{id}:
    get:
      tags: [Agents]
      summary: Get agent details
      operationId: getAgent
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: Agent details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Agent'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags: [Agents]
      summary: Update an agent
      operationId: updateAgent
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAgentRequest'
      responses:
        '200':
          description: Agent updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Agent'
    delete:
      tags: [Agents]
      summary: Delete an agent
      operationId: deleteAgent
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: Agent deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      deleted:
                        type: boolean
                      agent_id:
                        type: integer

  /agents/{id}/execute:
    post:
      tags: [Agents]
      summary: Execute a task on an agent
      operationId: executeAgent
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                task:
                  type: string
                  description: Task description to execute
                input:
                  type: string
                  description: Alternative to task
      responses:
        '200':
          description: Execution result
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AgentExecuteResult'

  /fleets:
    get:
      tags: [Fleets]
      summary: List fleets
      operationId: listFleets
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [idle, running, paused, completed, failed]
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: Paginated fleet list
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginatedResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Fleet'
    post:
      tags: [Fleets]
      summary: Create a fleet
      operationId: createFleet
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFleetRequest'
      responses:
        '201':
          description: Fleet created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Fleet'

  /fleets/{id}:
    get:
      tags: [Fleets]
      summary: Get fleet details
      operationId: getFleet
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: Fleet with agents
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    allOf:
                      - $ref: '#/components/schemas/Fleet'
                      - type: object
                        properties:
                          agents:
                            type: array
                            items:
                              $ref: '#/components/schemas/Agent'
    delete:
      tags: [Fleets]
      summary: Delete a fleet
      operationId: deleteFleet
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: Fleet deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      deleted:
                        type: boolean
                      fleet_id:
                        type: integer

  /fleets/{id}/status:
    get:
      tags: [Fleets]
      summary: Get fleet status
      operationId: getFleetStatus
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: Fleet status with agent breakdown
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      fleet:
                        $ref: '#/components/schemas/Fleet'
                      agent_status_breakdown:
                        type: object
                        properties:
                          queued:
                            type: integer
                          running:
                            type: integer
                          completed:
                            type: integer
                          failed:
                            type: integer
                      total_agents:
                        type: integer

  /fleets/{id}/deploy:
    post:
      tags: [Fleets]
      summary: Deploy a fleet
      description: Start all queued agents. Fleet must be idle or paused with at least 1 agent.
      operationId: deployFleet
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: Fleet deployed
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      fleet_id:
                        type: integer
                      status:
                        type: string
                        example: running
                      agents_deployed:
                        type: integer
                      message:
                        type: string

  /fleets/{id}/pause:
    post:
      tags: [Fleets]
      summary: Pause a fleet
      operationId: pauseFleet
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: Fleet paused
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      fleet_id:
                        type: integer
                      status:
                        type: string
                        example: paused
                      message:
                        type: string

  /voice:
    get:
      tags: [Voice]
      summary: Voice endpoint summary
      operationId: getVoiceInfo
      responses:
        '200':
          description: Voice endpoints list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /voice/calls:
    get:
      tags: [Voice]
      summary: List calls
      operationId: listCalls
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [waiting, active, ended]
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: Paginated call list
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginatedResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/VoiceCall'

  /voice/calls/{id}:
    get:
      tags: [Voice]
      summary: Get call details
      operationId: getCall
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: Call details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/VoiceCall'

  /voice/rooms:
    get:
      tags: [Voice]
      summary: List conference rooms
      operationId: listRooms
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [waiting, active, ended]
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: Paginated room list
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginatedResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/VoiceRoom'
    post:
      tags: [Voice]
      summary: Create a conference room
      operationId: createRoom
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRoomRequest'
      responses:
        '201':
          description: Room created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/VoiceRoom'

  /voice/rooms/{id}:
    get:
      tags: [Voice]
      summary: Get room details
      operationId: getRoom
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: Room details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/VoiceRoom'

  /marketplace:
    get:
      tags: [Marketplace]
      summary: Browse marketplace
      operationId: listMarketplace
      parameters:
        - name: search
          in: query
          schema:
            type: string
            maxLength: 200
        - name: category
          in: query
          schema:
            type: string
        - name: type
          in: query
          schema:
            type: string
            enum: [tool, template, workflow, integration]
        - name: sort
          in: query
          schema:
            type: string
            enum: [created_at, rating, downloads, price, title]
        - name: order
          in: query
          schema:
            type: string
            enum: [ASC, DESC]
            default: DESC
        - name: free
          in: query
          schema:
            type: boolean
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: Paginated marketplace listings
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginatedResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/MarketplaceItem'

  /marketplace/{id}:
    get:
      tags: [Marketplace]
      summary: Get marketplace item
      operationId: getMarketplaceItem
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: Item details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/MarketplaceItem'

  /usage:
    get:
      tags: [Usage]
      summary: Usage overview
      operationId: getUsage
      responses:
        '200':
          description: Aggregated usage stats
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/UsageOverview'

  /usage/tools:
    get:
      tags: [Usage]
      summary: Tool usage breakdown
      operationId: getToolUsage
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: Per-tool usage stats
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginatedResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/ToolUsageStat'

  /usage/daily:
    get:
      tags: [Usage]
      summary: Daily usage
      operationId: getDailyUsage
      parameters:
        - name: days
          in: query
          schema:
            type: integer
            minimum: 7
            maximum: 90
            default: 30
      responses:
        '200':
          description: Daily usage data
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      period_days:
                        type: integer
                      daily:
                        type: array
                        items:
                          type: object
                          properties:
                            date:
                              type: string
                              format: date
                            count:
                              type: integer
                            successes:
                              type: integer
                      total:
                        type: integer

  /billing:
    get:
      tags: [Usage]
      summary: Billing info
      operationId: getBilling
      responses:
        '200':
          description: Plan and rate limit info
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/BillingInfo'

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: "ak_live_*"
      description: API key from https://gositeme.com/developer-portal

  parameters:
    ResourceId:
      name: id
      in: path
      required: true
      schema:
        type: integer
    Page:
      name: page
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1
    PerPage:
      name: per_page
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20

  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      headers:
        X-RateLimit-Limit:
          schema:
            type: integer
        X-RateLimit-Remaining:
          schema:
            type: integer
        X-RateLimit-Reset:
          schema:
            type: integer
        Retry-After:
          schema:
            type: integer

  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            status:
              type: integer

    SuccessResponse:
      type: object
      properties:
        data:
          type: object

    PaginatedResponse:
      type: object
      properties:
        meta:
          type: object
          properties:
            total:
              type: integer
            page:
              type: integer
            per_page:
              type: integer
            total_pages:
              type: integer

    ChatRequest:
      type: object
      required: [message]
      properties:
        message:
          type: string
          maxLength: 10000
          description: Message to Alfred
        conversation_id:
          type: string
          description: Continue an existing conversation
        model:
          type: string
          maxLength: 50
          default: alfred-default
        temperature:
          type: number
          minimum: 0
          maximum: 1
          default: 0.7
        tools:
          type: array
          items:
            type: string
          description: Tool names to make available
        stream:
          type: boolean
          default: false

    ChatResponse:
      type: object
      properties:
        reply:
          type: string
        conversation_id:
          type: string
        model:
          type: string
        tokens_used:
          type: object
          nullable: true
        tools_called:
          type: array
          items:
            type: string

    ToolSummary:
      type: object
      properties:
        name:
          type: string
        category:
          type: string
        description:
          type: string
        icon:
          type: string
        tier:
          type: string

    ToolDetail:
      allOf:
        - $ref: '#/components/schemas/ToolSummary'
        - type: object
          properties:
            input_schema:
              type: object
            execute_url:
              type: string
              format: uri

    ToolExecuteResult:
      type: object
      properties:
        tool:
          type: string
        category:
          type: string
        status:
          type: string
          enum: [completed, failed]
        result:
          type: object
        execution_time_ms:
          type: integer

    Agent:
      type: object
      properties:
        id:
          type: integer
        fleet_id:
          type: integer
        agent_name:
          type: string
        agent_role:
          type: string
          enum: [leader, specialist, generalist, reviewer]
        task:
          type: string
          nullable: true
        skills:
          type: array
          items:
            type: string
        result:
          type: object
          nullable: true
        status:
          type: string
          enum: [queued, running, completed, failed, cancelled]
        fleet_name:
          type: string
        strategy:
          type: string
        started_at:
          type: string
          format: date-time
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true

    CreateAgentRequest:
      type: object
      required: [agent_name, agent_role, fleet_id]
      properties:
        agent_name:
          type: string
          maxLength: 100
        agent_role:
          type: string
          enum: [leader, specialist, generalist, reviewer]
        fleet_id:
          type: integer
        task:
          type: string
          maxLength: 2000
        skills:
          type: array
          items:
            type: string

    UpdateAgentRequest:
      type: object
      properties:
        agent_name:
          type: string
          maxLength: 100
        agent_role:
          type: string
          enum: [leader, specialist, generalist, reviewer]
        task:
          type: string
          maxLength: 2000
        skills:
          type: array
          items:
            type: string

    AgentExecuteResult:
      type: object
      properties:
        agent_id:
          type: integer
        agent_name:
          type: string
        agent_role:
          type: string
        task:
          type: string
        status:
          type: string
          enum: [completed, failed]
        result:
          type: object
        execution_time_ms:
          type: integer

    Fleet:
      type: object
      properties:
        id:
          type: integer
        fleet_name:
          type: string
        objective:
          type: string
        strategy:
          type: string
          enum: [parallel, pipeline, consensus, competition]
        status:
          type: string
          enum: [idle, running, paused, completed, failed]
        agent_count:
          type: integer
        progress_percent:
          type: integer
        results:
          type: object
          nullable: true
        kpis:
          type: array
          items:
            type: object
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true

    CreateFleetRequest:
      type: object
      required: [name, objective]
      properties:
        name:
          type: string
          maxLength: 100
        objective:
          type: string
          maxLength: 2000
        strategy:
          type: string
          enum: [parallel, pipeline, consensus, competition]
          default: parallel
        kpis:
          type: array
          items:
            type: object

    VoiceCall:
      type: object
      properties:
        id:
          type: integer
        host_user_id:
          type: integer
        topic:
          type: string
        room_code:
          type: string
        status:
          type: string
          enum: [waiting, active, ended]
        max_participants:
          type: integer
        current_participants:
          type: integer
        agenda:
          type: object
          nullable: true
        created_at:
          type: string
          format: date-time
        ended_at:
          type: string
          format: date-time
          nullable: true

    VoiceRoom:
      type: object
      properties:
        id:
          type: integer
        host_user_id:
          type: integer
        topic:
          type: string
        room_code:
          type: string
          example: ALF-A1B2-C3D4
        max_participants:
          type: integer
          minimum: 2
          maximum: 100
        current_participants:
          type: integer
        status:
          type: string
          enum: [waiting, active, ended]
        agenda:
          type: object
          nullable: true
        join_url:
          type: string
          format: uri
        created_at:
          type: string
          format: date-time
        ended_at:
          type: string
          format: date-time
          nullable: true

    CreateRoomRequest:
      type: object
      required: [topic]
      properties:
        topic:
          type: string
          maxLength: 255
        max_participants:
          type: integer
          minimum: 2
          maximum: 100
          default: 10
        agenda:
          type: object

    MarketplaceItem:
      type: object
      properties:
        id:
          type: integer
        seller_user_id:
          type: integer
        seller_name:
          type: string
          nullable: true
        item_type:
          type: string
          enum: [tool, template, workflow, integration]
        title:
          type: string
        description:
          type: string
        price:
          type: number
        currency:
          type: string
        category:
          type: string
        tags:
          type: array
          items:
            type: string
          nullable: true
        downloads:
          type: integer
        rating:
          type: number
          nullable: true
        review_count:
          type: integer
        created_at:
          type: string
          format: date-time

    UsageOverview:
      type: object
      properties:
        tool_executions:
          type: integer
        successful_executions:
          type: integer
        success_rate:
          type: number
        unique_tools_used:
          type: integer
        fleets:
          type: integer
        agents:
          type: integer
        conferences:
          type: integer
        api_requests_30d:
          type: integer
        xp:
          type: object
          properties:
            total:
              type: integer
            level:
              type: integer
            streak_days:
              type: integer
        tier:
          type: string

    ToolUsageStat:
      type: object
      properties:
        tool_name:
          type: string
        category:
          type: string
        usage_count:
          type: integer
        success_count:
          type: integer
        avg_time_ms:
          type: integer
        last_used:
          type: string
          format: date-time

    BillingInfo:
      type: object
      properties:
        plan:
          type: string
        api_tier:
          type: string
        rate_limits:
          type: object
          properties:
            per_minute:
              type: integer
            per_hour:
              type: integer
            per_day:
              type: integer
        fleet_limit:
          type: integer
        fleets_used:
          type: integer
        fleets_remaining:
          type: integer
