Documentation

API reference

Create a tool run

POST/v1/tool-runs

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. New calls require nonempty version/input and Idempotency-Key. If the creation response is lost and no run_id is available, replay this operation with the original API key, original Idempotency-Key, and original complete request body to recover the existing run, without requoting or changing the cost cap. Replaying an accepted run does not depend on current switches or quote expiration. With a known run_id, only query the original run; never create a new run with a different key for an unknown submission.

Execute after quoting

Retrieve the exact version, input_schema, and pricing from tool details. mode=flat is a constant per-call price, mode=input is precomputed from inputs, and mode=usage is based on final usage. A rule's schema_version only describes its storage format.

New calls with quote_required=true must obtain a quote first. Check the tool_id/version echoed in the response, and retain the quote_id and original request. With requires_usage=true, you must also provide max_cost_usd no lower than maximum_usd. Cost caps are optional for other runs but are still checked when supplied. Constant-price runs requiring no final usage may execute directly; input-priced rules require quotes but may settle without final usage.

Quotes freeze the original source. If the default source later changes, the original quote still uses its original source as long as that source and configuration remain valid. New calls that have not been submitted may be requoted after checking inputs when quote_expired, quote_stale, or invalid_quote occurs. If execution succeeds while billing remains reserved, continue querying final usage; successful output alone does not prove settlement.

Recovering a lost response

Before sending, retain the original API key identity, Idempotency-Key, and complete request body. If the creation response is lost and there is no run_id, replay POST /v1/tool-runs with the same API key, same request key, and original complete request. Retain the original quote_id and max_cost_usd; do not requote or change keys. Existing runs return their original records first without executing the task again. Recovery remains possible even if the quote later expires or the switch for new calls is disabled. Once you have a run_id, only GET the original run.

For idempotency conflicts, reconcile the original request. Do not automatically change keys to create another billable operation. See Error handling, Billing, and Asynchronous recovery.

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 headers

  • Idempotency-KeystringRequired

    Retain the original request intent with the same key. After a network interruption, query recovery first; never blindly resend unknown states.

    Minimum length
    1
    Maximum length
    191

Request body · application/json

Type
object
Required fields
tool_idversioninput
Additional properties
false

Request body required

  • quote_idstringOptional

    New runs with pricing.quote_required=true require a valid quote; it may be omitted for constant selling prices requiring no final usage. Any supplied quote is always checked for binding.

  • tool_idstringRequired

    Tool ID from the current key's executable catalog.

  • versionstringRequired

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

    Minimum length
    1
    Pattern
    ".*\\S.*"
  • inputunknownRequired

    Must pass the input_schema for this tool version. Only canonical JSON is accepted; additional fields such as the administrator route_id are prohibited.

  • max_cost_usdstringOptionalAllows null

    New runs with pricing.requires_usage=true must provide a valid, non-null decimal USD budget at least equal to the quote's maximum_usd. Optional otherwise, but still checked when supplied. The budget is checked only when creating a run.

Responses and errors

HTTP 200

Returns 200 when run status is succeeded or failed, for both the initial synchronous response and idempotent recovery of the original request. succeeded may still have billing.status=reserved while awaiting final usage settlement; HTTP 200 does not mean billing is settled.

application/json

Type
object
Required fields
idtool_idversionstatusoutputbillingresult_expiredcreated_atupdated_at
  • idstringRequired

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

  • tool_idstringRequired

    Tool ID from the current key's executable catalog.

  • versionstringRequired

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

  • statusstringRequired

    submitting/running/submission_unknown/succeeded/failed; submission_unknown means the submission outcome is unknown. Do not resend with a different Idempotency-Key.

  • outputunknownRequired

    JSON defined by the tool's output_schema; do not assume results remain after expiration.

  • error_codestringOptional

    Public error code usable for branching logic.

  • billingobjectRequired

    Independent billing status; do not substitute generation status.

    billing child fields (7)
    • review_requiredbooleanOptional

      Billing evidence requires manual review.

    • reasonstringOptional

      Public reason for an unavailable action or billing review.

    • usageunknownOptional

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

    • breakdownunknownOptional

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

    • statusstringRequired

      Current object status; evaluate separately from billing and the saving stage.

    • reserved_usdstringRequired

      Maximum USD reservation amount as a string.

    • charged_usdstringRequired

      Currently confirmed USD charge amount as a string.

    allOf branch 1

    Type: object

    Required in this branch: status, reserved_usd, charged_usd

    • review_requiredbooleanOptional

      Billing evidence requires manual review.

    • reasonstringOptional

      Public reason for an unavailable action or billing review.

    • usageunknownOptional

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

    • breakdownunknownOptional

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

    • statusstringRequired

      Current object status; evaluate separately from billing and the saving stage.

    • reserved_usdstringRequired

      Maximum USD reservation amount as a string.

    • charged_usdstringRequired

      Currently confirmed USD charge amount as a string.

  • result_expiredbooleanRequired

    Whether the result has expired; billing/idempotency records remain.

  • created_atintegerRequired

    Creation time in Unix seconds.

  • updated_atintegerRequired

    Last update time in Unix seconds.

HTTP 202

Run status is submitting, running, or submission_unknown. The request was accepted; billing must still be evaluated independently using billing.

application/json

Type
object
Required fields
idtool_idversionstatusoutputbillingresult_expiredcreated_atupdated_at
  • idstringRequired

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

  • tool_idstringRequired

    Tool ID from the current key's executable catalog.

  • versionstringRequired

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

  • statusstringRequired

    submitting/running/submission_unknown/succeeded/failed; submission_unknown means the submission outcome is unknown. Do not resend with a different Idempotency-Key.

  • outputunknownRequired

    JSON defined by the tool's output_schema; do not assume results remain after expiration.

  • error_codestringOptional

    Public error code usable for branching logic.

  • billingobjectRequired

    Independent billing status; do not substitute generation status.

    billing child fields (7)
    • review_requiredbooleanOptional

      Billing evidence requires manual review.

    • reasonstringOptional

      Public reason for an unavailable action or billing review.

    • usageunknownOptional

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

    • breakdownunknownOptional

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

    • statusstringRequired

      Current object status; evaluate separately from billing and the saving stage.

    • reserved_usdstringRequired

      Maximum USD reservation amount as a string.

    • charged_usdstringRequired

      Currently confirmed USD charge amount as a string.

    allOf branch 1

    Type: object

    Required in this branch: status, reserved_usd, charged_usd

    • review_requiredbooleanOptional

      Billing evidence requires manual review.

    • reasonstringOptional

      Public reason for an unavailable action or billing review.

    • usageunknownOptional

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

    • breakdownunknownOptional

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

    • statusstringRequired

      Current object status; evaluate separately from billing and the saving stage.

    • reserved_usdstringRequired

      Maximum USD reservation amount as a string.

    • charged_usdstringRequired

      Currently confirmed USD charge amount as a string.

  • result_expiredbooleanRequired

    Whether the result has expired; billing/idempotency records remain.

  • created_atintegerRequired

    Creation time in Unix seconds.

  • updated_atintegerRequired

    Last update time in Unix seconds.

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

Endpoint notes

This example is for tools with requires_usage=true: replace quote_id and max_cost_usd. The budget must be a valid decimal USD string at least equal to this quote's maximum_usd; 0.01 is only illustrative. For input-priced rules requiring a quote but no final usage, the budget is optional. For constant-price runs requiring no final usage, both quote and budget are optional. Before sending, retain the original key identity, request key, and complete request body; reuse them for recovery if the response is lost.