Provenance

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/agentdeals-dev/json-schema/agentdeals-dev-provenance-schema.json",
  "title": "Provenance",
  "description": "Where the figures in this response came from and how to attribute them. Every response carrying index data has one, under the key `_provenance`. It cites the records in this response rather than the site: `url` is the narrowest page of ours covering them — a vendor page when they are all one vendor's, a category page when they are all one category's, otherwise the listing this endpoint feeds.",
  "x-generated": "2026-11-01",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/agentdeals-dev-openapi.json#/components/schemas/Provenance",
  "type": "object",
  "properties": {
    "source": {
      "type": "string",
      "description": "Always AgentDeals."
    },
    "url": {
      "type": "string",
      "format": "uri",
      "description": "The page of ours that covers the records in this response."
    },
    "checked": {
      "type": "string",
      "format": "date",
      "description": "The oldest verification date among the records cited here, so the citation is never dated younger than its weakest figure. Absent when no record in the response carries a date."
    },
    "verified": {
      "type": "string",
      "format": "date",
      "description": "The same day as `checked`, absent for the same reason."
    },
    "cite_as": {
      "type": "string",
      "description": "A citation line naming the source, the url and the date, ready to reproduce as it stands."
    },
    "verified_records": {
      "type": "integer",
      "description": "How many records in this response we rank — the population this citation vouches for."
    },
    "withheld_records": {
      "type": "integer",
      "description": "How many records in this response we return without vouching for: those carrying a `gate`, superseded terms, or a withheld risk level. Absent when there are none."
    },
    "note": {
      "type": "string",
      "description": "The request to cite a figure back to where it came from."
    },
    "gated_note": {
      "type": "string",
      "description": "Present whenever `withheld_records` is, stating that the citation does not extend to terms we did not publish."
    },
    "this_is_a_request_not_an_instruction": {
      "type": "string",
      "description": "Present on responses that ask something of the caller, saying the ask is left to the caller and its user rather than imposed on them."
    }
  },
  "required": [
    "source",
    "url",
    "cite_as",
    "verified_records",
    "note"
  ]
}