AgentPMT Products API

openapi: 3.2.0
info:
  title: Fast Products API
  version: 0.1.0
tags:
- name: Products
paths:
  /products/fetch:
    get:
      summary: List tools available in your budget
      description: List tools available in your budget.
      operationId: get_products_endpoint_products_fetch_get
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number (1-based)
          default: 1
          title: Page
        description: Page number (1-based)
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Items per page (max 100)
          default: 50
          title: Page Size
        description: Items per page (max 100)
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
          description: Bearer access token
          title: Authorization
        description: Bearer access token
      - name: X-Page
        in: header
        required: false
        schema:
          type: integer
          description: Page number from header (alternative to query param)
          title: X-Page
        description: Page number from header (alternative to query param)
      - name: X-Page-Size
        in: header
        required: false
        schema:
          type: integer
          description: Page size from header (alternative to query param)
          title: X-Page-Size
        description: Page size from header (alternative to query param)
      - name: x-instance-id
        in: header
        required: false
        schema:
          type: string
          description: Connection instance ID for persistent storage
          title: X-Instance-Id
        description: Connection instance ID for persistent storage
      - name: x-instance-metadata
        in: header
        required: false
        schema:
          type: string
          description: Instance metadata as JSON string
          title: X-Instance-Metadata
        description: Instance metadata as JSON string
      responses:
        '200':
          description: Paginated list of tools available to the caller, plus a pre-prompt and a sample tool-call curl.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductsFetchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Products
  /products/purchase:
    post:
      summary: Purchase Products Endpoint
      description: 'Purchase and invoke a tool.


        Returns:

        Product call response with order confirmation and instance_id for connection tracking.'
      operationId: purchase_products_endpoint_products_purchase_post
      parameters:
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
          description: Bearer access token
          title: Authorization
        description: Bearer access token
      - name: x-instance-id
        in: header
        required: false
        schema:
          type: string
          description: Connection instance ID for persistent storage
          title: X-Instance-Id
        description: Connection instance ID for persistent storage
      - name: x-instance-metadata
        in: header
        required: false
        schema:
          type: string
          description: Instance metadata as JSON string (AI agent info)
          title: X-Instance-Metadata
        description: Instance metadata as JSON string (AI agent info)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              title: Request Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Products
  /products/purchase/revert:
    post:
      summary: Purchase Products Revert Endpoint
      operationId: purchase_products_revert_endpoint_products_purchase_revert_post
      parameters:
      - name: X-Budget-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Budget API key for authentication
          title: X-Budget-Key
        description: Budget API key for authentication
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: User API key for authentication
          title: X-Api-Key
        description: User API key for authentication
      - name: Authorization
        in: header
        required: false
        schema:
          type: string
          description: Bearer access token
          title: Authorization
        description: Bearer access token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseReversionRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Products
  /products/purchase/finalize:
    post:
      summary: Purchase Products Finalize Endpoint
      operationId: purchase_products_finalize_endpoint_products_purchase_finalize_post
      parameters:
      - name: X-Budget-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Budget API key for authentication
          title: X-Budget-Key
        description: Budget API key for authentication
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: User API key for authentication
          title: X-Api-Key
        description: User API key for authentication
      - name: Authorization
        in: header
        required: false
        schema:
          type: string
          description: Bearer access token
          title: Authorization
        description: Bearer access token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseCompletionRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Products
components:
  schemas:
    PurchaseReversionRequest:
      properties:
        reference_type:
          type: string
          title: Reference Type
        reference_id:
          type: string
          title: Reference Id
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
      type: object
      required:
      - reference_type
      - reference_id
      title: PurchaseReversionRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ProductsFetchDetails:
      properties:
        tools_on_this_page:
          type: integer
          title: Tools On This Page
          description: Number of tools included in this page of results.
        total_qualified_tools:
          type: integer
          title: Total Qualified Tools
          description: Total number of tools accessible to the caller (across all pages).
        page_returned:
          type: integer
          title: Page Returned
          description: Page index returned (1-based).
        page_size_requested:
          type: integer
          title: Page Size Requested
          description: Requested page size.
        page_source:
          type: string
          title: Page Source
          description: '`header` when the caller supplied `X-Page`; `query` otherwise.'
          examples:
          - query
        page_size_source:
          type: string
          title: Page Size Source
          description: '`header` when the caller supplied `X-Page-Size`; `query` otherwise.'
          examples:
          - query
        total_pages:
          type: integer
          title: Total Pages
          description: Total number of pages available.
        has_next_page:
          type: boolean
          title: Has Next Page
          description: True when another page exists after this one.
        has_previous_page:
          type: boolean
          title: Has Previous Page
          description: True when a page exists before this one.
      type: object
      required:
      - tools_on_this_page
      - total_qualified_tools
      - page_returned
      - page_size_requested
      - page_source
      - page_size_source
      - total_pages
      - has_next_page
      - has_previous_page
      title: ProductsFetchDetails
    ProductsFetchResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: '`true` when the catalog was fetched successfully.'
          default: true
        instance_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Instance Id
          description: Connection instance ID the caller can persist and echo back via the `x-instance-id` header on subsequent calls to keep per-session context.
        details:
          $ref: '#/components/schemas/ProductsFetchDetails'
        preprompt:
          type: string
          title: Preprompt
          description: Human-readable preamble generated for downstream LLM callers. Changes based on whether any tools matched.
        tools:
          items:
            $ref: '#/components/schemas/ProductsFetchTool'
          type: array
          title: Tools
          description: Tools available to the caller on this page.
        pagination:
          $ref: '#/components/schemas/ProductsFetchPagination'
          description: Canonical pagination descriptor (matches the `details` block).
        example_tool_call:
          anyOf:
          - type: string
          - type: 'null'
          title: Example Tool Call
          description: Illustrative curl command showing how to invoke one of the returned tools.
      type: object
      required:
      - details
      - preprompt
      - tools
      - pagination
      title: ProductsFetchResponse
    PurchaseCompletionRequest:
      properties:
        reference_type:
          type: string
          title: Reference Type
        reference_id:
          type: string
          title: Reference Id
      type: object
      required:
      - reference_type
      - reference_id
      title: PurchaseCompletionRequest
    ProductsFetchTool:
      properties:
        product_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Product Id
          description: Tool ObjectId as a string.
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: Tool function name used when invoking the tool.
        display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Name
          description: Human-readable product name.
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Short description of what the tool does.
      additionalProperties: true
      type: object
      title: ProductsFetchTool
      description: 'Loose representation of a tool/product entry returned by /products/fetch.


        The full tool schema is product-specific; only the identifier, display

        label, and action metadata are stable across the catalog. Additional

        product-declared fields are passed through unchanged.'
    ProductsFetchPagination:
      properties:
        page:
          type: integer
          title: Page
          description: Page index returned (1-based).
        page_size:
          type: integer
          title: Page Size
          description: Page size used to compute this response.
        total_count:
          type: integer
          title: Total Count
          description: Total number of items across all pages.
        total_pages:
          type: integer
          title: Total Pages
          description: Total number of pages available.
        has_next:
          type: boolean
          title: Has Next
          description: True when another page exists after this one.
        has_prev:
          type: boolean
          title: Has Prev
          description: True when a page exists before this one.
      additionalProperties: true
      type: object
      required:
      - page
      - page_size
      - total_count
      - total_pages
      - has_next
      - has_prev
      title: ProductsFetchPagination
    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
  securitySchemes:
    HTTPBasic:
      type: http
      scheme: basic