openapi: 3.1.0
info:
  title: Amigo Account Tool Testing API
  version: 0.1.0
servers:
- url: https://api.amigo.ai
- url: https://internal-api.amigo.ai
- url: https://api-eu-central-1.amigo.ai
- url: https://api-ap-southeast-2.amigo.ai
- url: https://api-ca-central-1.amigo.ai
security:
- Bearer-Authorization: []
  Bearer-Authorization-Organization: []
  Basic: []
tags:
- name: Tool Testing
paths:
  /v1/{workspace_id}/tools/execute:
    post:
      tags:
      - Tool Testing
      summary: Execute a tool in test mode
      description: Run an HSM tool outside a live session for testing.
      operationId: execute-tool-test
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolExecuteRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolExecuteResponse'
        '403':
          description: Insufficient permissions.
        '401':
          description: Missing or invalid credentials.
        '503':
          description: Voice agent service unavailable.
        '422':
          description: Invalid request body.
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
  /v1/{workspace_id}/services/{service_id}/tools/resolve:
    get:
      tags:
      - Tool Testing
      summary: Resolve tools for a service
      description: List all tools available for a service's HSM with metadata.
      operationId: resolve-service-tools
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: service_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Service Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolResolveResponse'
        '403':
          description: Insufficient permissions.
        '401':
          description: Missing or invalid credentials.
        '503':
          description: Voice agent service unavailable.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/tools/catalog:
    get:
      tags:
      - Tool Testing
      summary: List built-in tool catalog
      description: List the platform's built-in world + surface tools (workspace-independent).
      operationId: list-tool-catalog
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolCatalogResponse'
        '403':
          description: Insufficient permissions.
        '401':
          description: Missing or invalid credentials.
        '503':
          description: Voice agent service unavailable.
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
components:
  schemas:
    NameString:
      type: string
      maxLength: 256
      minLength: 1
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ToolCatalogResponse:
      properties:
        tools:
          items:
            $ref: '#/components/schemas/ResolvedToolItem'
          type: array
          title: Tools
      type: object
      required:
      - tools
      title: ToolCatalogResponse
    ResolvedToolItem:
      properties:
        tool_name:
          type: string
          title: Tool Name
        tool_type:
          type: string
          title: Tool Type
        description:
          type: string
          title: Description
          default: ''
        input_schema:
          additionalProperties: true
          type: object
          title: Input Schema
        states:
          items:
            type: string
          type: array
          title: States
        tier:
          type: string
          title: Tier
          default: world
        is_write:
          type: boolean
          title: Is Write
          default: false
        additional_instructions:
          additionalProperties:
            type: string
          type: object
          title: Additional Instructions
      type: object
      required:
      - tool_name
      - tool_type
      title: ResolvedToolItem
    SubToolLogItem:
      properties:
        tool_name:
          type: string
          title: Tool Name
          default: ''
        input:
          additionalProperties: true
          type: object
          title: Input
        output:
          type: string
          title: Output
          default: ''
        duration_ms:
          type: number
          title: Duration Ms
          default: 0.0
        succeeded:
          type: boolean
          title: Succeeded
          default: true
      type: object
      title: SubToolLogItem
    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
    ToolExecuteResponse:
      properties:
        result:
          title: Result
        duration_ms:
          type: number
          title: Duration Ms
          default: 0.0
        dry_run:
          type: boolean
          title: Dry Run
          default: false
        source:
          type: string
          title: Source
          default: tool_test
        tool_type:
          type: string
          title: Tool Type
          default: ''
        tier:
          type: string
          title: Tier
          default: world
        is_write:
          type: boolean
          title: Is Write
          default: false
        sub_tool_logs:
          items:
            $ref: '#/components/schemas/SubToolLogItem'
          type: array
          title: Sub Tool Logs
        blocked_side_effects:
          items:
            type: string
          type: array
          title: Blocked Side Effects
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
      type: object
      title: ToolExecuteResponse
    ToolResolveResponse:
      properties:
        tools:
          items:
            $ref: '#/components/schemas/ResolvedToolItem'
          type: array
          title: Tools
        service_id:
          type: string
          format: uuid
          title: Service Id
        workspace_id:
          type: string
          format: uuid
          title: Workspace Id
      type: object
      required:
      - tools
      - service_id
      - workspace_id
      title: ToolResolveResponse
    ToolExecuteRequest:
      properties:
        tool_type:
          type: string
          maxLength: 64
          title: Tool Type
          description: world_tool — other tool families use their dedicated endpoints
        tool_name:
          $ref: '#/components/schemas/NameString'
          description: Fully qualified tool name
        service_id:
          type: string
          format: uuid
          title: Service Id
          description: Service ID that owns the HSM
        input_params:
          additionalProperties: true
          type: object
          title: Input Params
          description: Parameters to pass to the tool handler
        entity_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Entity Id
          description: Optional entity ID for context
        dry_run:
          type: boolean
          title: Dry Run
          description: If true, write tools are simulated without persistence
          default: false
      type: object
      required:
      - tool_type
      - tool_name
      - service_id
      title: ToolExecuteRequest
  securitySchemes:
    Bearer-Authorization:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the [`SignInWithAPIKey`](sign-in-with-api-key) endpoint.
    Bearer-Authorization-Organization:
      type: apiKey
      in: header
      name: X-ORG-ID
      description: An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
    Basic:
      type: http
      scheme: basic
      description: The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.