Documentation

API reference

Get a tool contract

GET/v1/tools/{id}

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

Path parameters

  • idstringRequired

    Catalog tool ID or original tool run ID, depending on the current operation's object.

Query parameters

  • versionstringOptional

    Omission uses the current version; creating a run requires specifying the catalog version.

Responses and errors

HTTP 200

Tool contract retrieved successfully

application/json

Type
object
Required fields
category_idcollection_idtagsidnamedescriptionversionpricinginput_schemaoutput_schemaread_only
  • 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.

  • input_schemaunknownRequired

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

  • output_schemaunknownRequired

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

  • read_onlybooleanRequired

    Read-only property declared by the tool's public contract; not a guarantee of free or authorization-free access.

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