{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/apiosk-com/json-schema/apiosk-com-buyer-run-schema.json",
  "title": "BuyerRun",
  "x-generated": "2026-11-02",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/apiosk-com-openapi.json#/components/schemas/BuyerRun",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "status": {
      "type": "string",
      "enum": [
        "requires_approval",
        "running",
        "completed",
        "partial",
        "needs_input",
        "needs_selection",
        "unsupported",
        "cancelled",
        "failed"
      ]
    },
    "question": {
      "type": "string"
    },
    "capability": {
      "type": "string",
      "description": "European capability slug for a structured capability plan or run."
    },
    "normalized_records": {
      "type": "array",
      "description": "Contract-extracted provider facts grouped by subject. Equal facts for one subject are combined with all their source references; absent fields are never invented.",
      "items": {
        "type": "object",
        "properties": {
          "entity_ref": {
            "type": "string",
            "format": "uuid"
          },
          "entity_refs": {
            "type": "array",
            "description": "Original subject references joined by a matching stable identifier.",
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "facts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string"
                },
                "value": {},
                "observed_at": {
                  "type": "string",
                  "format": "date-time"
                },
                "expires_at": {
                  "type": "string",
                  "format": "date-time"
                },
                "sources": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "source_id": {
                        "type": "string"
                      },
                      "result_ref": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "source_url": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "retrieved_at": {
                        "type": "string",
                        "format": "date-time"
                      },
                      "source_pointer": {
                        "type": [
                          "string",
                          "null"
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "plan": {
      "type": "object",
      "properties": {
        "quote_ref": {
          "type": "string",
          "format": "uuid"
        },
        "expires_at": {
          "type": "string",
          "format": "date-time"
        },
        "steps": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "source_id": {
                "type": "string"
              },
              "operation": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "conditional": {
                "type": "boolean"
              },
              "estimated_cost": {
                "type": "object",
                "properties": {
                  "amount": {
                    "type": "number"
                  },
                  "amount_micro_usd": {
                    "type": "string"
                  },
                  "currency": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "estimated_total": {
          "type": "object",
          "properties": {
            "amount": {
              "type": "number"
            },
            "amount_micro_usd": {
              "type": "string"
            },
            "currency": {
              "type": "string"
            }
          }
        }
      }
    },
    "answer": {
      "type": [
        "object",
        "null"
      ],
      "description": "Apiosk's reading of the results, with evidence pointers. Null for a direct call."
    },
    "data": {
      "type": "object",
      "description": "The source document, when the run produced exactly one."
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "result_ref": {
            "type": "string",
            "format": "uuid"
          },
          "source": {
            "type": "object",
            "properties": {
              "provider": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            }
          },
          "data": {
            "type": "object"
          }
        }
      }
    },
    "usage": {
      "type": "object",
      "properties": {
        "sources": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "source_id": {
                "type": "string"
              },
              "operation": {
                "type": "string"
              },
              "calls": {
                "type": "integer"
              },
              "cost": {
                "type": "object",
                "properties": {
                  "amount": {
                    "type": "number"
                  },
                  "amount_micro_usd": {
                    "type": "string"
                  },
                  "currency": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "cost": {
          "type": "object",
          "properties": {
            "amount": {
              "type": "number"
            },
            "amount_micro_usd": {
              "type": "string"
            },
            "currency": {
              "type": "string"
            }
          }
        },
        "held": {
          "type": "object",
          "properties": {
            "amount": {
              "type": "number"
            },
            "amount_micro_usd": {
              "type": "string"
            },
            "currency": {
              "type": "string"
            }
          }
        }
      }
    },
    "balance": {
      "type": "object",
      "properties": {
        "remaining": {
          "type": "object",
          "properties": {
            "amount": {
              "type": "number"
            },
            "amount_micro_usd": {
              "type": "string"
            },
            "currency": {
              "type": "string"
            }
          }
        }
      }
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    },
    "retry_after_ms": {
      "type": "integer"
    },
    "message": {
      "type": [
        "string",
        "null"
      ],
      "description": "Natural-language clarification for needs_input."
    },
    "needs_input": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string"
          },
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "candidates": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "object"
      }
    },
    "approval_required_reason": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    },
    "metadata": {
      "type": "object",
      "description": "Attribution for a single result, when present."
    },
    "continuation": {
      "$ref": "#/$defs/Continuation"
    }
  },
  "$defs": {
    "Continuation": {
      "type": "object",
      "required": [
        "state",
        "actions"
      ],
      "properties": {
        "state": {
          "$ref": "#/$defs/ContinuationState"
        },
        "actions": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "object",
            "required": [
              "action_id",
              "kind",
              "label",
              "requires_authorization",
              "input_schema"
            ],
            "properties": {
              "action_id": {
                "type": "string",
                "format": "uuid"
              },
              "kind": {
                "type": "string",
                "enum": [
                  "select_entity",
                  "supply_input"
                ]
              },
              "label": {
                "type": "string"
              },
              "requires_authorization": {
                "type": "boolean",
                "const": false
              },
              "input_schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      }
    },
    "ContinuationState": {
      "type": "object",
      "additionalProperties": false,
      "description": "Signed snapshot returned by this run. Copy unchanged.",
      "required": [
        "schema_version",
        "state_ref",
        "revision",
        "expires_at",
        "focus",
        "state_token"
      ],
      "properties": {
        "schema_version": {
          "type": "string",
          "enum": [
            "2"
          ]
        },
        "state_ref": {
          "type": "string",
          "format": "uuid"
        },
        "revision": {
          "type": "integer",
          "minimum": 0
        },
        "expires_at": {
          "type": "string",
          "format": "date-time"
        },
        "focus": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "entity_refs",
            "goal_refs"
          ],
          "properties": {
            "entity_refs": {
              "type": "array",
              "items": {
                "type": "string",
                "format": "uuid"
              }
            },
            "goal_refs": {
              "type": "array",
              "items": {
                "type": "string",
                "format": "uuid"
              }
            }
          }
        },
        "state_token": {
          "type": "string"
        }
      }
    }
  }
}