Documentation

API reference

Search executable tools

POST/v1/tools/discover

Unified support for flat constant per-call pricing, input pricing precomputed from inputs, and usage pricing based on final usage. pricing.quote_required determines whether a quote is mandatory; requires_usage determines whether a cost cap and authoritative final usage are required. Neither is inferred from schema_version. When metered_pricing is off, only new calls requiring final usage are restricted; constant/input rules remain available if they need no final usage. The current key must have tool authorization; run identity and results are scoped to the original key. The catalog is empty when the master tool switch is off; the anonymous catalog is not executable authorization.

Authentication and permissions

Use your current GloopAPI key. Available models, capabilities and permissions depend on its catalog and the endpoint documentation.

Authorization: Bearer $GLOOP_API_KEY

Authentication schemes: BearerAuth

Request

Request body · application/json

Type
object
Required fields
query
Additional properties
false

Request body required

  • querystringRequired

    Nonempty, at most 1000 UTF-8 bytes; matches ID/name/description.

  • limitintegerOptional

    Omitted or <=0 values use 5.

    Default value
    5
    Maximum
    20

Responses and errors

HTTP 200

Executable tools searched successfully

application/json

Type
object
Required fields
resultscount
  • resultsarrayRequired
    results child fields (1)
    • []objectOptional
      [] child fields (8)
      • category_idstringRequired

        Tool category identifier.

      • collection_idstringRequired

        Tool collection identifier.

      • tagsarrayRequired

        Public search tags.

        tags child fields (1)
        • []stringOptional
      • idstringRequired

        Public identifier of this object, used for its corresponding detail path.

      • namestringRequired

        Human-readable name.

      • descriptionstringRequired

        Public purpose description.

      • versionstringRequired

        Contract/capability or tool version; runs use the tool version returned by the catalog.

      • pricingobjectRequired

        Public price; current quotes and billing rules apply.

        pricing child fields (9)
        • schema_versionintegerOptional

          Tool pricing rule version.

        • ruleunknownOptional

          JSON value defined by the selected tool's schema or protocol; do not assume fixed fields.

        • quote_requiredbooleanRequired

          Whether new runs must confirm a quote first.

        • currencystringRequired

          Quote/billing currency.

        • unitstringRequired

          call is per-call or precomputed from inputs; usage is based on final usage. See mode for exact semantics.

        • amountstringOptional

          For mode=flat, this is the complete constant USD amount, including zero. input/usage do not expose a potentially misleading constant amount.

        • price_versionintegerRequired

          Selling price revision.

        • modestringRequired

          Selling price semantics: flat constant per-call, input precomputed from inputs, usage based on final usage. Independent of the schema_version data format.

          Enum
          ["flat","input","usage"]
        • requires_usagebooleanRequired

          Whether final settlement requires authoritative usage, including platform settlement constraints. Do not infer solely from the selling price mode.

        allOf branch 1

        Type: object

        Required in this branch: currency, unit, price_version, mode, quote_required, requires_usage

        • schema_versionintegerOptional

          Tool pricing rule version.

        • ruleunknownOptional

          JSON value defined by the selected tool's schema or protocol; do not assume fixed fields.

        • quote_requiredbooleanRequired

          Whether new runs must confirm a quote first.

        • currencystringRequired

          Quote/billing currency.

        • unitstringRequired

          call is per-call or precomputed from inputs; usage is based on final usage. See mode for exact semantics.

        • amountstringOptional

          For mode=flat, this is the complete constant USD amount, including zero. input/usage do not expose a potentially misleading constant amount.

        • price_versionintegerRequired

          Selling price revision.

        • modestringRequired

          Selling price semantics: flat constant per-call, input precomputed from inputs, usage based on final usage. Independent of the schema_version data format.

          Enum
          ["flat","input","usage"]
        • requires_usagebooleanRequired

          Whether final settlement requires authoritative usage, including platform settlement constraints. Do not infer solely from the selling price mode.

  • countintegerRequired

HTTP 400

Invalid request fields or parameters.

application/json

Type
object
Required fields
error

HTTP 401

The key is missing, invalid, expired, or revoked.

application/json

Type
object
Required fields
error

HTTP 403

Insufficient IP, account, model, or tool permissions.

application/json

Type
object
Required fields
error

HTTP 404

Object/capability unavailable, or feature switch disabled.

application/json

Type
object
Required fields
error

HTTP 409

Idempotency/quote conflict, object not ready, or still referenced.

application/json

Type
object
Required fields
error

HTTP 429

Request/queue rate limit.

application/json

Type
object
Required fields
error

HTTP 500

Internal authentication or data storage failure.

application/json

Type
object
Required fields
error

HTTP 503

Service, pricing, or storage unavailable.

application/json

Type
object
Required fields
error