GAIP Witness Agent

Use this when about to depend on a public HTTPS service and you want neutral evidence of what it delivers. Pass `service_url`; `checks` default to HTTP 200 and a non-empty body. Returns a `terms_id`; then call witness_delivery. Free, no account; records a GAIP receipt only. Inputs must be public and non-personal.

{
  "type": "object",
  "properties": {
    "checks": {
      "description": "Checks: http_status_in {allowed}, content_type_is {value}, non_empty, json_parses.",
      "maxItems": 8,
      "minItems": 1,
      "type": "array"
    },
    "data_classification": {
      "default": "PUBLIC",
      "description": "PUBLIC (default) or NON_PERSONAL_PUBLIC. Never send personal data.",
      "enum": [
        "PUBLIC",
        "NON_PERSONAL_PUBLIC"
      ],
      "type": "string"
    },
    "seller_ref": {
      "description": "Optional: name of the supplier. Defaults to the host of service_url.",
      "type": "string"
    },
    "service_url": {
      "description": "Public https URL of the service.",
      "type": "string"
    }
  },
  "required": [
    "service_url"
  ],
  "examples": [
    {
      "checks": [
        {
          "allowed": [
            200
          ],
          "id": "http_status_in"
        },
        {
          "id": "json_parses"
        }
      ],
      "seller_ref": "example-weather-agent",
      "service_url": "https://weather.example.com/forecast.json"
    }
  ]
}

Use this when asked whether a service delivered what was agreed ("did the supplier deliver?"). Pass the `terms_id` from witness_register_terms and mode PUBLIC_REPLAY (GAIP fetches it) or BUYER_SUBMITTED. Returns PASS / FAIL / UNKNOWN per check and a receipt. Free, read-only, no account; inputs must be public and non-personal.

{
  "type": "object",
  "properties": {
    "body": {
      "description": "BUYER_SUBMITTED: the response body you received (max 32 KiB).",
      "maxLength": 32768,
      "type": "string"
    },
    "body_sha256": {
      "description": "BUYER_SUBMITTED: SHA-256 of the body, instead of the body.",
      "type": "string"
    },
    "content_type": {
      "description": "BUYER_SUBMITTED: the Content-Type you received.",
      "type": "string"
    },
    "continuity_handle": {
      "additionalProperties": false,
      "description": "Optional: the continuity_handle from an earlier GAIP result; links this call to your earlier ones.",
      "properties": {
        "continuity_id": {
          "type": "string"
        },
        "token": {
          "type": "string"
        }
      },
      "required": [
        "continuity_id",
        "token"
      ],
      "type": "object"
    },
    "data_classification": {
      "default": "PUBLIC",
      "description": "PUBLIC (default) or NON_PERSONAL_PUBLIC. Never send personal data.",
      "enum": [
        "PUBLIC",
        "NON_PERSONAL_PUBLIC"
      ],
      "type": "string"
    },
    "episode_id": {
      "description": "Optional: your own id to group related calls.",
      "type": "string"
    },
    "http_status": {
      "description": "BUYER_SUBMITTED: the HTTP status you received.",
      "type": "integer"
    },
    "independent_operator_id": {
      "description": "Optional: your operator id (recorded as a claim, not verified).",
      "type": "string"
    },
    "mode": {
      "description": "PUBLIC_REPLAY: GAIP fetches the public URL itself. BUYER_SUBMITTED: check a response you pass in.",
      "enum": [
        "BUYER_SUBMITTED",
        "PUBLIC_REPLAY"
      ],
      "type": "string"
    },
    "synthetic": {
      "description": "Optional: true marks a test call.",
      "type": "boolean"
    },
    "terms_id": {
      "description": "The terms_id returned when the terms were registered.",
      "type": "string"
    }
  },
  "required": [
    "terms_id",
    "mode"
  ],
  "additionalProperties": true,
  "examples": [
    {
      "mode": "PUBLIC_REPLAY",
      "terms_id": "<terms_id from witness_register_terms>"
    }
  ]
}

Use this when you need a GAIP receipt in another format. Pass `receipt_id` and `format`: x402 (attestation style), erc8004 (validation-response shape) or vc (W3C-VC-like JSON-LD). Unsigned; integrity via hash chain and Merkle proof; no on-chain write. Free, read-only, no account; inputs must be public and non-personal.

{
  "type": "object",
  "properties": {
    "format": {
      "description": "x402, erc8004 or vc.",
      "enum": [
        "x402",
        "erc8004",
        "vc"
      ],
      "type": "string"
    },
    "receipt_id": {
      "description": "A receipt_id returned by an earlier GAIP call.",
      "maxLength": 128,
      "minLength": 1,
      "type": "string"
    }
  },
  "required": [
    "receipt_id",
    "format"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "format": "x402",
      "receipt_id": "<receipt_id returned by any GAIP tool>"
    }
  ]
}

Use this when you hold a GAIP receipt_id and want to confirm it ("is this receipt genuine?"). Returns the retained record, hash chain and Merkle inclusion proof. Integrity only: it does not make the underlying claim true. Free, read-only, no account; inputs must be public and non-personal.

{
  "type": "object",
  "properties": {
    "continuity_handle": {
      "additionalProperties": false,
      "description": "Optional: the continuity_handle from an earlier GAIP result; links this call to your earlier ones.",
      "properties": {
        "continuity_id": {
          "type": "string"
        },
        "token": {
          "type": "string"
        }
      },
      "required": [
        "continuity_id",
        "token"
      ],
      "type": "object"
    },
    "data_classification": {
      "description": "PUBLIC (default) or NON_PERSONAL_PUBLIC. Never send personal data.",
      "enum": [
        "PUBLIC",
        "NON_PERSONAL_PUBLIC"
      ],
      "type": "string"
    },
    "episode_id": {
      "description": "Optional: your own id to group related calls.",
      "type": "string"
    },
    "independent_operator_id": {
      "description": "Optional: your operator id (recorded as a claim, not verified).",
      "type": "string"
    },
    "receipt_id": {
      "description": "A receipt_id returned by an earlier GAIP call.",
      "maxLength": 128,
      "minLength": 1,
      "type": "string"
    },
    "synthetic": {
      "description": "Optional: true marks a test call.",
      "type": "boolean"
    }
  },
  "required": [
    "receipt_id"
  ],
  "additionalProperties": true,
  "examples": [
    {
      "receipt_id": "<receipt_id returned by any GAIP tool>"
    }
  ]
}

Use this when a witnessed delivery failed and you need to share the facts with the other party. Pass the delivery `receipt_id`. Returns a neutral, no-fault evidence bundle with verifiable receipts. Free, read-only, no account; inputs must be public and non-personal.

{
  "type": "object",
  "properties": {
    "receipt_id": {
      "description": "A receipt_id returned by an earlier GAIP call.",
      "type": "string"
    }
  },
  "required": [
    "receipt_id"
  ],
  "examples": [
    {
      "receipt_id": "<receipt_id from witness_delivery>"
    }
  ]
}

Use this when asked to keep an eye on an agent or MCP server ("tell me if it changes or goes down"). Pass the `continuity_handle` from any GAIP result, `kind` and `target_url`. GAIP re-checks every 24 hours (3 free watches), receipts each change and can call your webhook. Free, no account; records a GAIP receipt only. Inputs must be public and non-personal.

{
  "type": "object",
  "properties": {
    "continuity_handle": {
      "description": "The continuity_handle from an earlier GAIP result; proves you own these watches.",
      "properties": {
        "continuity_id": {
          "type": "string"
        },
        "token": {
          "type": "string"
        }
      },
      "required": [
        "continuity_id",
        "token"
      ],
      "type": "object"
    },
    "data_classification": {
      "default": "PUBLIC",
      "description": "PUBLIC (default) or NON_PERSONAL_PUBLIC. Never send personal data.",
      "enum": [
        "PUBLIC",
        "NON_PERSONAL_PUBLIC"
      ],
      "type": "string"
    },
    "interval_hours": {
      "default": 24,
      "description": "Optional: hours between checks (24 minimum on the free tier).",
      "maximum": 168,
      "minimum": 24,
      "type": "integer"
    },
    "kind": {
      "description": "AGENT_READINESS (agent URL), SUPPLIER_CARD (published card) or DELIVERY_TERMS (terms_id).",
      "enum": [
        "AGENT_READINESS",
        "DELIVERY_TERMS",
        "SUPPLIER_CARD"
      ],
      "type": "string"
    },
    "target_url": {
      "description": "Public https URL (AGENT_READINESS, SUPPLIER_CARD). No query string.",
      "format": "uri",
      "maxLength": 2048,
      "type": "string"
    },
    "terms_id": {
      "description": "DELIVERY_TERMS: terms_id from witness_register_terms.",
      "type": "string"
    },
    "webhook_url": {
      "description": "Optional: your own public https endpoint for signed change events.",
      "format": "uri",
      "maxLength": 2048,
      "type": "string"
    }
  },
  "required": [
    "continuity_handle",
    "kind"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "continuity_handle": {
        "continuity_id": "<continuity_handle.continuity_id returned by any GAIP tool>",
        "token": "<continuity_handle.token returned by any GAIP tool>"
      },
      "interval_hours": 24,
      "kind": "SUPPLIER_CARD",
      "target_url": "https://weather.example.com/.well-known/agent-card.json",
      "webhook_url": "https://hooks.example.com/gaip-watch"
    }
  ]
}

Use this when asked which agents or services you are watching. Pass your `continuity_handle`. Returns each watch's kind, target, last verdict, last and next check and webhook endpoint (never the secret). Free, read-only, no account; inputs must be public and non-personal.

{
  "type": "object",
  "properties": {
    "continuity_handle": {
      "description": "The continuity_handle from an earlier GAIP result; proves you own these watches.",
      "properties": {
        "continuity_id": {
          "type": "string"
        },
        "token": {
          "type": "string"
        }
      },
      "required": [
        "continuity_id",
        "token"
      ],
      "type": "object"
    }
  },
  "required": [
    "continuity_handle"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "continuity_handle": {
        "continuity_id": "<continuity_handle.continuity_id returned by any GAIP tool>",
        "token": "<continuity_handle.token returned by any GAIP tool>"
      }
    }
  ]
}

Use this when asked to stop watching an agent or service. Pass your `continuity_handle` and the `watch_id`. Its stored events are deleted; retained receipts stay verifiable. Free, no account; records a GAIP receipt only. Inputs must be public and non-personal.

{
  "type": "object",
  "properties": {
    "continuity_handle": {
      "description": "The continuity_handle from an earlier GAIP result; proves you own these watches.",
      "properties": {
        "continuity_id": {
          "type": "string"
        },
        "token": {
          "type": "string"
        }
      },
      "required": [
        "continuity_id",
        "token"
      ],
      "type": "object"
    },
    "watch_id": {
      "description": "The watch_id returned by gaip_watch_register.",
      "type": "string"
    }
  },
  "required": [
    "continuity_handle",
    "watch_id"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "continuity_handle": {
        "continuity_id": "<continuity_handle.continuity_id returned by any GAIP tool>",
        "token": "<continuity_handle.token returned by any GAIP tool>"
      },
      "watch_id": "<watch_id from gaip_watch_register>"
    }
  ]
}

Use this when asked what changed on a watched agent or service. Pass your `continuity_handle` and optionally a `watch_id`. Returns recent change events: verdict before and after, a change summary, the receipt and webhook delivery status. Free, read-only, no account; inputs must be public and non-personal.

{
  "type": "object",
  "properties": {
    "continuity_handle": {
      "description": "The continuity_handle from an earlier GAIP result; proves you own these watches.",
      "properties": {
        "continuity_id": {
          "type": "string"
        },
        "token": {
          "type": "string"
        }
      },
      "required": [
        "continuity_id",
        "token"
      ],
      "type": "object"
    },
    "limit": {
      "description": "Optional: maximum events to return.",
      "maximum": 50,
      "minimum": 1,
      "type": "integer"
    },
    "watch_id": {
      "description": "The watch_id returned by gaip_watch_register.",
      "type": "string"
    }
  },
  "required": [
    "continuity_handle"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "continuity_handle": {
        "continuity_id": "<continuity_handle.continuity_id returned by any GAIP tool>",
        "token": "<continuity_handle.token returned by any GAIP tool>"
      },
      "limit": 10,
      "watch_id": "<watch_id from gaip_watch_register>"
    }
  ]
}

Use this when asked to verify citations or quotes ("do these sources really say this?"). Pass `citations` (1-20 {url, quote}). GAIP fetches each page once (robots.txt respected); returns QUOTE_FOUND / QUOTE_NOT_FOUND_IN_FETCHED_VERSION / SOURCE_UNREACHABLE..., an excerpt and a receipt. Free, read-only, no account; inputs must be public and non-personal.

{
  "type": "object",
  "properties": {
    "citations": {
      "description": "1-20 citations, each {url, quote?, claimed_title?, claimed_date?}.",
      "items": {
        "additionalProperties": false,
        "properties": {
          "claimed_date": {
            "maxLength": 64,
            "type": "string"
          },
          "claimed_title": {
            "maxLength": 500,
            "type": "string"
          },
          "quote": {
            "maxLength": 2000,
            "type": "string"
          },
          "url": {
            "format": "uri",
            "maxLength": 2048,
            "type": "string"
          }
        },
        "required": [
          "url"
        ],
        "type": "object"
      },
      "maxItems": 20,
      "minItems": 1,
      "type": "array"
    },
    "data_classification": {
      "default": "PUBLIC",
      "description": "PUBLIC (default) or NON_PERSONAL_PUBLIC. Never send personal data.",
      "enum": [
        "PUBLIC",
        "NON_PERSONAL_PUBLIC"
      ],
      "type": "string"
    }
  },
  "required": [
    "citations"
  ],
  "additionalProperties": true,
  "examples": [
    {
      "citations": [
        {
          "claimed_title": "GAIP",
          "quote": "GAIP",
          "url": "https://www.gaipagents.com/"
        }
      ]
    }
  ]
}