RunRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/looot/main/json-schema/looot-run-request-schema.json",
  "title": "RunRequest",
  "x-generated": "2026-10-05",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/looot-openapi.json#/components/schemas/RunRequest",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "endpointId",
    "input"
  ],
  "properties": {
    "endpointId": {
      "type": "string",
      "minLength": 1,
      "description": "The catalog endpoint id to run"
    },
    "input": {
      "type": "object",
      "description": "Arbitrary key/value input, validated against the endpoint's own input schema"
    },
    "idempotencyKey": {
      "type": "string",
      "minLength": 1,
      "description": "Required, unless supplied instead as the Idempotency-Key request header (either satisfies the requirement; supplying both requires them to match, or the request is a 400). A replay with the same key and the same body returns the original run (replayed:true); the same key with a different body is a 409. Never auto-generated by the gateway -- see the report's decision options for why."
    },
    "output": {
      "type": "object",
      "description": "Optional output selection/mapping pin; same shape as an inspected endpoint's outputMappingPin"
    },
    "wait": {
      "oneOf": [
        {
          "type": "boolean"
        },
        {
          "type": "number",
          "minimum": 0,
          "maximum": 60
        }
      ],
      "description": "Optional alternative to the ?wait= query parameter (the query parameter wins if both are given)"
    },
    "fallback": {
      "description": "Optional. Let the run move to the next provider of the same job when one misses or fails, within ONE hold; only attempts that ran are charged. true takes every default. The run then carries `route` {servedBy, outcome, chargedUsd, capped, attempts[], skipped[], summary}.",
      "oneOf": [
        {
          "type": "boolean"
        },
        {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "enabled": {
              "type": "boolean",
              "description": "false turns it off (the same as omitting fallback)"
            },
            "maxAttempts": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10,
              "description": "Dispatched attempts, default 3"
            },
            "maxCostUsd": {
              "type": "number",
              "exclusiveMinimum": 0,
              "maximum": 100,
              "description": "The route's cap; default the sum of the first maxAttempts prices; can only lower it"
            },
            "prefer": {
              "enum": [
                "cheapest",
                "reliable",
                "fastest",
                "balanced"
              ],
              "description": "Order of the job's other providers, default balanced"
            },
            "exclude": {
              "type": "array",
              "maxItems": 50,
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200
              },
              "description": "Endpoint or provider ids never tried"
            },
            "stopAtFirstMiss": {
              "type": "boolean",
              "description": "Stop at the first empty answer, default false"
            }
          }
        }
      ]
    }
  }
}