> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helve.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Call tool

> Invoke any tool from Helve's catalog by `tool_id` with its native `arguments` using your single `sk_live_` key. Upstream costs plus Helve's 15% fee are debited from your balance; failed upstream calls cost $0.



## OpenAPI

````yaml openapi.json POST /v1/tools/call
openapi: 3.1.0
info:
  title: Helve API
  version: 2.0.0
  description: >-
    Metered pay-per-call tool gateway for AI agents: search available tools via
    `/v1/tools/search`, call any tool immediately via `/v1/tools/call` with one
    Helve API key and zero third-party signups, plus unified `/v1/search`,
    `/v1/extract`, and `/v1/transcriptions` endpoints.
servers:
  - url: https://helve.dev
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Catalog
    description: >-
      Discover 223 metered third-party and public utility tools, invoke any tool
      with one key, or request missing tools.
  - name: Search
    description: >-
      Web search with one schema across Exa, Parallel, Tavily, Brave, Serper,
      Firecrawl, Linkup, Valyu, Jina, Octen, Perplexity, and the `fusion` panel.
  - name: Extract
    description: Fetch and clean pages by URL.
  - name: Transcription
    description: >-
      Durable speech-to-text jobs across AssemblyAI, Deepgram, and ElevenLabs.
      Submit a recording, poll the job.
paths:
  /v1/tools/call:
    post:
      tags:
        - Catalog
      summary: Call any catalog tool
      description: >-
        Invoke any tool from Helve's catalog by `tool_id` with its native
        `arguments` using your single `sk_live_` key. Upstream costs plus
        Helve's 15% fee are debited from your balance; failed upstream calls
        cost $0.
      operationId: callTool
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tool_id:
                  type: string
                  minLength: 1
                  example: frankfurter.fx_rates
                arguments:
                  type: object
                  additionalProperties:
                    nullable: true
                  default: {}
                  example:
                    base: USD
                    symbols: EUR,GBP
              required:
                - tool_id
      responses:
        '200':
          description: Tool execution result and metered cost
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  tool_id:
                    type: string
                  provider:
                    type: string
                  category:
                    type: string
                  data:
                    nullable: true
                  warnings:
                    type: array
                    items:
                      type: string
                  usage:
                    type: object
                    properties:
                      provider_cost_usd:
                        type: number
                      platform_fee_usd:
                        type: number
                      cost_usd:
                        type: number
                      credits:
                        type: integer
                    required:
                      - provider_cost_usd
                      - platform_fee_usd
                      - cost_usd
                      - credits
                  latency_ms:
                    type: integer
                required:
                  - id
                  - tool_id
                  - provider
                  - category
                  - warnings
                  - usage
                  - latency_ms
        '400':
          description: Invalid tool arguments
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - unauthorized
                          - invalid_request
                          - provider_not_available
                          - provider_not_configured
                          - provider_error
                          - not_found
                          - insufficient_credits
                          - spend_limit_exceeded
                          - internal_error
                        description: >-
                          Stable machine-readable category. `invalid_request`
                          carries validation issues in `detail`;
                          `provider_error` carries the provider's own error
                          body.
                      message:
                        type: string
                        description: Human-readable explanation.
                      detail:
                        nullable: true
                        description: >-
                          Validation issues for `invalid_request`; the
                          provider's error body for `provider_error`.
                    required:
                      - type
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - unauthorized
                          - invalid_request
                          - provider_not_available
                          - provider_not_configured
                          - provider_error
                          - not_found
                          - insufficient_credits
                          - spend_limit_exceeded
                          - internal_error
                        description: >-
                          Stable machine-readable category. `invalid_request`
                          carries validation issues in `detail`;
                          `provider_error` carries the provider's own error
                          body.
                      message:
                        type: string
                        description: Human-readable explanation.
                      detail:
                        nullable: true
                        description: >-
                          Validation issues for `invalid_request`; the
                          provider's error body for `provider_error`.
                    required:
                      - type
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '402':
          description: Insufficient credits
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - unauthorized
                          - invalid_request
                          - provider_not_available
                          - provider_not_configured
                          - provider_error
                          - not_found
                          - insufficient_credits
                          - spend_limit_exceeded
                          - internal_error
                        description: >-
                          Stable machine-readable category. `invalid_request`
                          carries validation issues in `detail`;
                          `provider_error` carries the provider's own error
                          body.
                      message:
                        type: string
                        description: Human-readable explanation.
                      detail:
                        nullable: true
                        description: >-
                          Validation issues for `invalid_request`; the
                          provider's error body for `provider_error`.
                    required:
                      - type
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '404':
          description: Unknown tool_id
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - unauthorized
                          - invalid_request
                          - provider_not_available
                          - provider_not_configured
                          - provider_error
                          - not_found
                          - insufficient_credits
                          - spend_limit_exceeded
                          - internal_error
                        description: >-
                          Stable machine-readable category. `invalid_request`
                          carries validation issues in `detail`;
                          `provider_error` carries the provider's own error
                          body.
                      message:
                        type: string
                        description: Human-readable explanation.
                      detail:
                        nullable: true
                        description: >-
                          Validation issues for `invalid_request`; the
                          provider's error body for `provider_error`.
                    required:
                      - type
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '502':
          description: Upstream provider error ($0 debited)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - unauthorized
                          - invalid_request
                          - provider_not_available
                          - provider_not_configured
                          - provider_error
                          - not_found
                          - insufficient_credits
                          - spend_limit_exceeded
                          - internal_error
                        description: >-
                          Stable machine-readable category. `invalid_request`
                          carries validation issues in `detail`;
                          `provider_error` carries the provider's own error
                          body.
                      message:
                        type: string
                        description: Human-readable explanation.
                      detail:
                        nullable: true
                        description: >-
                          Validation issues for `invalid_request`; the
                          provider's error body for `provider_error`.
                    required:
                      - type
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '503':
          description: Tool not configured
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - unauthorized
                          - invalid_request
                          - provider_not_available
                          - provider_not_configured
                          - provider_error
                          - not_found
                          - insufficient_credits
                          - spend_limit_exceeded
                          - internal_error
                        description: >-
                          Stable machine-readable category. `invalid_request`
                          carries validation issues in `detail`;
                          `provider_error` carries the provider's own error
                          body.
                      message:
                        type: string
                        description: Human-readable explanation.
                      detail:
                        nullable: true
                        description: >-
                          Validation issues for `invalid_request`; the
                          provider's error body for `provider_error`.
                    required:
                      - type
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        An API key from the dashboard, `sk_live_…`, sent as `Authorization:
        Bearer sk_live_…`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.