Documentación

Referencia de API

Crear ejecución de herramienta

POST/v1/tool-runs

Admite flat constante por llamada, input precalculado por entradas y usage según uso final. pricing.quote_required determina si se exige cotización; requires_usage, si se exige límite de coste y uso final confirmado. Ninguno se deduce de schema_version. Con metered_pricing apagado solo se restringen llamadas nuevas que requieren uso final; reglas constantes/por entrada sin ese requisito siguen disponibles. La clave actual necesita autorización de herramientas; identidad y resultados quedan limitados a la clave original. Con el interruptor general apagado el catálogo está vacío; el catálogo anónimo no autoriza la ejecución. Las llamadas nuevas requieren version/input no vacíos e Idempotency-Key. Si se pierde la respuesta sin run_id, repite con clave de API, Idempotency-Key y cuerpo completo originales para recuperar la ejecución, sin recotizar ni cambiar el límite de coste. Repetir una ejecución aceptada no depende de interruptores actuales ni vigencia de cotización. Con run_id, consulta solo la original; no crees con otra clave ante envío desconocido.

Ejecutar después de cotizar

Obtén version, input_schema y pricing exactos de los detalles de la herramienta. mode=flat es un precio constante por llamada; mode=input se precalcula según entradas; mode=usage usa el consumo final. schema_version solo describe el formato de almacenamiento.

Las nuevas llamadas con quote_required=true deben cotizar primero. Comprueba tool_id/version devueltos y guarda quote_id y la solicitud original. Con requires_usage=true, max_cost_usd debe ser como mínimo maximum_usd. Para las demás ejecuciones, el límite es opcional pero también se comprueba si se aporta. Las de precio constante sin uso final pueden ejecutarse directamente; las reglas por entrada requieren cotización pero pueden liquidarse sin uso final.

La cotización fija el origen original. Aunque cambie el predeterminado, sigue usando el original mientras este y su configuración sean válidos. Ante quote_expired, quote_stale o invalid_quote, una llamada nueva aún no enviada puede recotizar tras verificar sus entradas. Si la ejecución tiene éxito pero billing sigue reserved, continúa consultando el uso final; el éxito de la salida no demuestra liquidación.

Recuperar una respuesta perdida

Antes de enviar, conserva la identidad de la clave de API, Idempotency-Key y cuerpo completo originales. Si se pierde la respuesta y no hay run_id, repite POST /v1/tool-runs con la misma clave de API, clave de solicitud y cuerpo completo original. Conserva quote_id y max_cost_usd; no recotices ni cambies claves. Una ejecución existente devuelve primero su registro original sin llamar de nuevo al servicio; se recupera aunque caduque la cotización o se desactiven nuevas llamadas. Una vez obtenido run_id, usa solo GET sobre la ejecución original.

Los conflictos de idempotencia exigen verificar la solicitud original; no cambies automáticamente la clave para crear otra operación facturable. Consulta Gestión de errores, Facturación y Recuperación asíncrona.

Autenticación y permisos

Usa tu clave actual de GloopAPI. Los modelos, capacidades y permisos dependen de su catálogo y de la documentación del endpoint.

Authorization: Bearer $GLOOP_API_KEY

Esquemas de autenticación: BearerAuth

Solicitud

Encabezados de solicitud

  • Idempotency-KeystringObligatorio

    Conserva la intención original con la misma clave; tras una interrupción, consulta recuperación primero. No reenvíes a ciegas estados desconocidos.

    Longitud mínima
    1
    Longitud máxima
    191

Cuerpo de solicitud · application/json

Tipo
object
Campos obligatorios
tool_idversioninput
Propiedades adicionales
false

Cuerpo de solicitud obligatorio

  • quote_idstringOpcional

    Las nuevas ejecuciones con pricing.quote_required=true requieren cotización válida; puede omitirse con venta constante sin uso final. Siempre se verifica la vinculación de una cotización aportada.

  • tool_idstringObligatorio

    ID de herramienta del catálogo ejecutable de la clave actual.

  • versionstringObligatorio

    Versión de contrato/capacidad o herramienta; la ejecución usa la versión del catálogo.

    Longitud mínima
    1
    Patrón
    ".*\\S.*"
  • inputunknownObligatorio

    Debe cumplir input_schema de esa version; solo JSON normalizado, sin campos adicionales como route_id de administrador.

  • max_cost_usdstringOpcionalAdmite null

    Las nuevas ejecuciones con pricing.requires_usage=true exigen un presupuesto decimal válido en USD, no null, igual o superior al maximum_usd cotizado. Es opcional en las demás, pero también se comprueba si se aporta. Solo se verifica al crear la ejecución.

Respuestas y errores

HTTP 200

Devuelve 200 con succeeded o failed, tanto en respuesta síncrona inicial como recuperación idempotente. succeeded puede tener billing.status=reserved esperando uso final; HTTP 200 no implica liquidación.

application/json

Tipo
object
Campos obligatorios
idtool_idversionstatusoutputbillingresult_expiredcreated_atupdated_at
  • idstringObligatorio

    Identificador público del objeto, usado en su ruta de detalles.

  • tool_idstringObligatorio

    ID de herramienta del catálogo ejecutable de la clave actual.

  • versionstringObligatorio

    Versión de contrato/capacidad o herramienta; la ejecución usa la versión del catálogo.

  • statusstringObligatorio

    submitting/running/submission_unknown/succeeded/failed; submission_unknown indica resultado de envío desconocido. No reenvíes con otro Idempotency-Key.

  • outputunknownObligatorio

    JSON definido por output_schema de la herramienta; no supongas que sigue existiendo tras caducar.

  • error_codestringOpcional

    Código público de error para decisiones de flujo.

  • billingobjectObligatorio

    Estado de facturación independiente, no sustituible por estado de generación.

    Campos secundarios de billing (7)
    • review_requiredbooleanOpcional

      Las pruebas de facturación requieren revisión manual.

    • reasonstringOpcional

      Motivo público de acción no disponible o revisión de facturación.

    • usageunknownOpcional

      Valor JSON definido por esquema o protocolo de la herramienta; sin campos fijos supuestos.

    • breakdownunknownOpcional

      Valor JSON definido por esquema o protocolo de la herramienta; sin campos fijos supuestos.

    • statusstringObligatorio

      Estado actual del objeto; evalúalo aparte de facturación y guardado.

    • reserved_usdstringObligatorio

      Reserva máxima en USD como cadena.

    • charged_usdstringObligatorio

      Importe en USD confirmado actualmente, como cadena.

    Rama allOf 1

    Tipo: object

    Obligatorio en esta rama: status, reserved_usd, charged_usd

    • review_requiredbooleanOpcional

      Las pruebas de facturación requieren revisión manual.

    • reasonstringOpcional

      Motivo público de acción no disponible o revisión de facturación.

    • usageunknownOpcional

      Valor JSON definido por esquema o protocolo de la herramienta; sin campos fijos supuestos.

    • breakdownunknownOpcional

      Valor JSON definido por esquema o protocolo de la herramienta; sin campos fijos supuestos.

    • statusstringObligatorio

      Estado actual del objeto; evalúalo aparte de facturación y guardado.

    • reserved_usdstringObligatorio

      Reserva máxima en USD como cadena.

    • charged_usdstringObligatorio

      Importe en USD confirmado actualmente, como cadena.

  • result_expiredbooleanObligatorio

    Si el resultado caducó; facturación e idempotencia se conservan.

  • created_atintegerObligatorio

    Fecha de creación en segundos Unix.

  • updated_atintegerObligatorio

    Última actualización en segundos Unix.

HTTP 202

Estado submitting, running o submission_unknown; solicitud aceptada, pero billing debe evaluarse por separado.

application/json

Tipo
object
Campos obligatorios
idtool_idversionstatusoutputbillingresult_expiredcreated_atupdated_at
  • idstringObligatorio

    Identificador público del objeto, usado en su ruta de detalles.

  • tool_idstringObligatorio

    ID de herramienta del catálogo ejecutable de la clave actual.

  • versionstringObligatorio

    Versión de contrato/capacidad o herramienta; la ejecución usa la versión del catálogo.

  • statusstringObligatorio

    submitting/running/submission_unknown/succeeded/failed; submission_unknown indica resultado de envío desconocido. No reenvíes con otro Idempotency-Key.

  • outputunknownObligatorio

    JSON definido por output_schema de la herramienta; no supongas que sigue existiendo tras caducar.

  • error_codestringOpcional

    Código público de error para decisiones de flujo.

  • billingobjectObligatorio

    Estado de facturación independiente, no sustituible por estado de generación.

    Campos secundarios de billing (7)
    • review_requiredbooleanOpcional

      Las pruebas de facturación requieren revisión manual.

    • reasonstringOpcional

      Motivo público de acción no disponible o revisión de facturación.

    • usageunknownOpcional

      Valor JSON definido por esquema o protocolo de la herramienta; sin campos fijos supuestos.

    • breakdownunknownOpcional

      Valor JSON definido por esquema o protocolo de la herramienta; sin campos fijos supuestos.

    • statusstringObligatorio

      Estado actual del objeto; evalúalo aparte de facturación y guardado.

    • reserved_usdstringObligatorio

      Reserva máxima en USD como cadena.

    • charged_usdstringObligatorio

      Importe en USD confirmado actualmente, como cadena.

    Rama allOf 1

    Tipo: object

    Obligatorio en esta rama: status, reserved_usd, charged_usd

    • review_requiredbooleanOpcional

      Las pruebas de facturación requieren revisión manual.

    • reasonstringOpcional

      Motivo público de acción no disponible o revisión de facturación.

    • usageunknownOpcional

      Valor JSON definido por esquema o protocolo de la herramienta; sin campos fijos supuestos.

    • breakdownunknownOpcional

      Valor JSON definido por esquema o protocolo de la herramienta; sin campos fijos supuestos.

    • statusstringObligatorio

      Estado actual del objeto; evalúalo aparte de facturación y guardado.

    • reserved_usdstringObligatorio

      Reserva máxima en USD como cadena.

    • charged_usdstringObligatorio

      Importe en USD confirmado actualmente, como cadena.

  • result_expiredbooleanObligatorio

    Si el resultado caducó; facturación e idempotencia se conservan.

  • created_atintegerObligatorio

    Fecha de creación en segundos Unix.

  • updated_atintegerObligatorio

    Última actualización en segundos Unix.

HTTP 400

Campos o parámetros de solicitud inválidos.

application/json

Tipo
object
Campos obligatorios
error

HTTP 401

La clave falta, no es válida, caducó o fue revocada.

application/json

Tipo
object
Campos obligatorios
error

HTTP 403

Permisos insuficientes de IP, cuenta, modelo o herramienta.

application/json

Tipo
object
Campos obligatorios
error

HTTP 404

Objeto/capacidad no disponible o función desactivada.

application/json

Tipo
object
Campos obligatorios
error

HTTP 409

Conflicto de idempotencia/cotización, objeto no preparado o aún referenciado.

application/json

Tipo
object
Campos obligatorios
error

HTTP 429

Límite de solicitudes/cola.

application/json

Tipo
object
Campos obligatorios
error

HTTP 500

Fallo interno de autenticación o almacenamiento de datos.

application/json

Tipo
object
Campos obligatorios
error

HTTP 503

Servicio, precios o almacenamiento no disponibles.

application/json

Tipo
object
Campos obligatorios
error

Notas del endpoint

Ejemplo para herramientas con requires_usage=true: sustituye quote_id y max_cost_usd. El presupuesto debe ser una cadena decimal USD válida no inferior a maximum_usd de la cotización; 0.01 es ilustrativo. En reglas por entrada que requieren cotización pero no uso final, el presupuesto es opcional; en precio constante sin uso final, ambos son opcionales. Guarda identidad de clave, clave de solicitud y cuerpo completo originales antes de enviar; reutilízalos si se pierde la respuesta.