vee3-io Meta Tools API

openapi: 3.2.0
info:
  title: Vee3 Io Meta Tools API
  version: 0.1.0
  description: 'Operations tagged meta-tools across 2 of this provider''s published API definitions: vee3-io.json, vee3-io-openapi.json. Each path carries the servers of the definition it was published in.'
tags:
- name: meta-tools
paths:
  /v1/meta-tools/tools:
    get:
      tags:
      - meta-tools
      summary: List all tools
      description: Return every live Vee3 capability and MCP tool name available to agents.
      operationId: list_all_tools_v1_meta_tools_tools_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAllToolsResult'
      security:
      - HTTPBearer: []
  /v1/meta-tools/tool:
    get:
      tags:
      - meta-tools
      summary: Describe tool
      description: Return the full schema, examples, and token cost for one capability.
      operationId: describe_tool_v1_meta_tools_tool_get
      security:
      - HTTPBearer: []
      parameters:
      - name: tool_name
        in: query
        required: true
        schema:
          type: string
          maxLength: 128
          title: Tool Name
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DescribeToolResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/meta-tools/token-balance:
    get:
      tags:
      - meta-tools
      summary: Get token balance
      description: Return this key's token limit, usage, remaining balance, and reset time.
      operationId: get_token_balance_v1_meta_tools_token_balance_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenBalanceResult'
      security:
      - HTTPBearer: []
  /v1/meta-tools/groups:
    get:
      tags:
      - meta-tools
      summary: List groups
      description: Return every capability group with summaries and live tool counts.
      operationId: list_groups_v1_meta_tools_groups_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListGroupsResult'
      security:
      - HTTPBearer: []
  /v1/meta-tools/group-tools:
    get:
      tags:
      - meta-tools
      summary: List group tools
      description: Return every live tool in one capability group.
      operationId: list_group_tools_v1_meta_tools_group_tools_get
      security:
      - HTTPBearer: []
      parameters:
      - name: group_id
        in: query
        required: true
        schema:
          type: string
          maxLength: 128
          title: Group Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListGroupToolsResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/meta-tools/search:
    get:
      tags:
      - meta-tools
      summary: Search tools
      description: Search live Vee3 capabilities by keyword or task description.
      operationId: search_tools_v1_meta_tools_search_get
      security:
      - HTTPBearer: []
      parameters:
      - name: query
        in: query
        required: true
        schema:
          type: string
          maxLength: 256
          title: Query
      - name: group_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Group Id
      - name: limit
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            maximum: 20
            minimum: 1
          - type: 'null'
          default: 8
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchToolsResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/meta-tools/report-bug:
    post:
      tags:
      - meta-tools
      summary: Report bug
      description: Report a bug, error, or unexpected behavior encountered while using Vee3.
      operationId: report_bug_v1_meta_tools_report_bug_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportBugRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportBugResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /v1/meta-tools/request-feature:
    post:
      tags:
      - meta-tools
      summary: Request feature
      description: Request a new capability or feature that Vee3 does not offer yet.
      operationId: request_feature_v1_meta_tools_request_feature_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestFeatureRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestFeatureResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
components:
  schemas:
    GroupEntry:
      properties:
        group_id:
          type: string
          title: Group Id
        display_name:
          type: string
          title: Display Name
        summary:
          type: string
          title: Summary
        live_tool_count:
          type: integer
          title: Live Tool Count
      type: object
      required:
      - group_id
      - display_name
      - summary
      - live_tool_count
      title: GroupEntry
    CapabilityExampleDetail:
      properties:
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
        request_body:
          additionalProperties: true
          type: object
          title: Request Body
        surfaces:
          items:
            $ref: '#/components/schemas/SurfaceDetail'
          type: array
          title: Surfaces
      type: object
      required:
      - name
      - description
      - request_body
      - surfaces
      title: CapabilityExampleDetail
    SuccessBodyCodeDetail:
      properties:
        body_code:
          type: string
          title: Body Code
      type: object
      required:
      - body_code
      title: SuccessBodyCodeDetail
    EnumValueDetail:
      properties:
        value:
          type: string
          title: Value
      type: object
      required:
      - value
      title: EnumValueDetail
    RequestFeatureResult:
      properties:
        request_id:
          type: string
          title: Request Id
        status:
          type: string
          title: Status
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - request_id
      - status
      - created_at
      title: RequestFeatureResult
    RequestFeatureRequest:
      properties:
        summary:
          type: string
          maxLength: 200
          title: Summary
          description: Short title describing the requested capability or feature.
        description:
          type: string
          maxLength: 8000
          title: Description
          description: Detailed explanation of what is needed, why it cannot be done with existing tools, and how it would help.
        related_capability_id:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Related Capability Id
          description: Capability id this request extends or relates to, if applicable.
        use_case:
          anyOf:
          - type: string
            maxLength: 8000
          - type: 'null'
          title: Use Case
          description: Example workflow or scenario where this feature would be used.
      type: object
      required:
      - summary
      - description
      title: RequestFeatureRequest
    SurfaceDetail:
      properties:
        surface:
          type: string
          title: Surface
      type: object
      required:
      - surface
      title: SurfaceDetail
    DescribeToolResult:
      properties:
        capability_id:
          type: string
          title: Capability Id
        tool:
          $ref: '#/components/schemas/ToolDetail'
      type: object
      required:
      - capability_id
      - tool
      title: DescribeToolResult
    ListGroupsResult:
      properties:
        message:
          type: string
          title: Message
        groups:
          items:
            $ref: '#/components/schemas/GroupEntry'
          type: array
          title: Groups
      type: object
      required:
      - message
      title: ListGroupsResult
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ReportBugRequest:
      properties:
        summary:
          type: string
          maxLength: 200
          title: Summary
          description: Short title describing the issue.
        description:
          type: string
          maxLength: 8000
          title: Description
          description: Detailed explanation of what went wrong, what was expected, and steps to reproduce if known.
        related_capability_id:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Related Capability Id
          description: MCP tool name or capability id involved in the issue, if applicable.
        error_details:
          anyOf:
          - type: string
            maxLength: 8000
          - type: 'null'
          title: Error Details
          description: Raw error message, stack trace, or API response that shows the failure.
      type: object
      required:
      - summary
      - description
      title: ReportBugRequest
    ToolDetail:
      properties:
        capability_id:
          type: string
          title: Capability Id
        group_id:
          type: string
          title: Group Id
        group_display_name:
          type: string
          title: Group Display Name
        display_name:
          type: string
          title: Display Name
        summary:
          type: string
          title: Summary
        agent_description:
          type: string
          title: Agent Description
        usage_unit_label:
          type: string
          title: Usage Unit Label
        status:
          type: string
          title: Status
        rest_method:
          type: string
          title: Rest Method
        rest_path:
          type: string
          title: Rest Path
        mcp_tool_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Mcp Tool Name
        token_cost:
          anyOf:
          - type: integer
          - type: string
          title: Token Cost
        request_fields:
          items:
            $ref: '#/components/schemas/RequestFieldDetail'
          type: array
          title: Request Fields
        response_fields:
          items:
            $ref: '#/components/schemas/ResponseFieldDetail'
          type: array
          title: Response Fields
        error_codes:
          items:
            $ref: '#/components/schemas/ErrorCodeDetail'
          type: array
          title: Error Codes
        success_body_codes:
          items:
            $ref: '#/components/schemas/SuccessBodyCodeDetail'
          type: array
          title: Success Body Codes
        examples:
          items:
            $ref: '#/components/schemas/CapabilityExampleDetail'
          type: array
          title: Examples
        response_examples:
          items:
            $ref: '#/components/schemas/CapabilityResponseExampleDetail'
          type: array
          title: Response Examples
      type: object
      required:
      - capability_id
      - group_id
      - group_display_name
      - display_name
      - summary
      - agent_description
      - usage_unit_label
      - status
      - rest_method
      - rest_path
      - token_cost
      - request_fields
      - response_fields
      - error_codes
      - success_body_codes
      - examples
      - response_examples
      title: ToolDetail
    ToolEntry:
      properties:
        mcp_tool_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Mcp Tool Name
        group_id:
          type: string
          title: Group Id
        summary:
          type: string
          title: Summary
      type: object
      required:
      - group_id
      - summary
      title: ToolEntry
    GroupToolEntry:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        summary:
          type: string
          title: Summary
      type: object
      required:
      - summary
      title: GroupToolEntry
    ListAllToolsResult:
      properties:
        tools:
          items:
            $ref: '#/components/schemas/ToolEntry'
          type: array
          title: Tools
      type: object
      title: ListAllToolsResult
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    ErrorCodeDetail:
      properties:
        error_code:
          type: string
          title: Error Code
      type: object
      required:
      - error_code
      title: ErrorCodeDetail
    ListGroupToolsResult:
      properties:
        group_id:
          type: string
          title: Group Id
        tools:
          items:
            $ref: '#/components/schemas/GroupToolEntry'
          type: array
          title: Tools
      type: object
      required:
      - group_id
      title: ListGroupToolsResult
    SearchToolsResultEntry:
      properties:
        tool_name:
          type: string
          title: Tool Name
        summary:
          type: string
          title: Summary
        cost:
          type: integer
          title: Cost
      type: object
      required:
      - tool_name
      - summary
      - cost
      title: SearchToolsResultEntry
    TokenBalanceResult:
      properties:
        billing_plan:
          type: string
          title: Billing Plan
        monthly_token_allowance:
          type: integer
          title: Monthly Token Allowance
        tokens_used:
          type: integer
          title: Tokens Used
        tokens_remaining:
          type: integer
          title: Tokens Remaining
        billing_period_start:
          type: string
          format: date-time
          title: Billing Period Start
        billing_period_end:
          type: string
          format: date-time
          title: Billing Period End
        billing_period_resets_at:
          type: string
          format: date-time
          title: Billing Period Resets At
      type: object
      required:
      - billing_plan
      - monthly_token_allowance
      - tokens_used
      - tokens_remaining
      - billing_period_start
      - billing_period_end
      - billing_period_resets_at
      title: TokenBalanceResult
    ResponseFieldDetail:
      properties:
        name:
          type: string
          title: Name
        type_name:
          type: string
          title: Type Name
        description:
          type: string
          title: Description
        children:
          items:
            $ref: '#/components/schemas/ResponseFieldDetail'
          type: array
          title: Children
      type: object
      required:
      - name
      - type_name
      - description
      title: ResponseFieldDetail
    ReportBugResult:
      properties:
        report_id:
          type: string
          title: Report Id
        status:
          type: string
          title: Status
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - report_id
      - status
      - created_at
      title: ReportBugResult
    RequestFieldDetail:
      properties:
        name:
          type: string
          title: Name
        type_name:
          type: string
          title: Type Name
        description:
          type: string
          title: Description
        required:
          type: boolean
          title: Required
        default:
          anyOf:
          - type: string
          - type: integer
          - type: boolean
          - type: 'null'
          title: Default
        surfaces:
          items:
            $ref: '#/components/schemas/SurfaceDetail'
          type: array
          title: Surfaces
        enum_values:
          anyOf:
          - items:
              $ref: '#/components/schemas/EnumValueDetail'
            type: array
          - type: 'null'
          title: Enum Values
        constraints:
          anyOf:
          - additionalProperties:
              anyOf:
              - type: integer
              - type: 'null'
            type: object
          - type: 'null'
          title: Constraints
      type: object
      required:
      - name
      - type_name
      - description
      - required
      - default
      - surfaces
      title: RequestFieldDetail
    SearchToolsResult:
      properties:
        query:
          type: string
          title: Query
        results:
          items:
            $ref: '#/components/schemas/SearchToolsResultEntry'
          type: array
          title: Results
      type: object
      required:
      - query
      title: SearchToolsResult
    CapabilityResponseExampleDetail:
      properties:
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
        status_code:
          type: integer
          title: Status Code
        response_body:
          additionalProperties: true
          type: object
          title: Response Body
      type: object
      required:
      - name
      - description
      - status_code
      - response_body
      title: CapabilityResponseExampleDetail
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
x-refined-from:
- vee3-io.json
- vee3-io-openapi.json