{
  "openapi": "3.0.3",
  "servers": [
    {
      "url": "https://uk-source-intelligence.pages.dev"
    }
  ],
  "info": {
    "title": "UK Source Intelligence — AI agent API",
    "version": "0.7.3",
    "description": "Agent-oriented GOV.UK source inspections and six-page HMRC/VAT pilot plus user-selected GOV.UK watches. £9 one-off for 30 days, 100 requests/day. Stripe Checkout and access activation are automatic after verified card payment."
  },
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "opaque API key"
      }
    }
  },
  "paths": {
    "/health": {
      "get": {
        "summary": "Service health",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/db-status": {
      "get": {
        "summary": "Six fixed monitored pages and database status",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/trial": {
      "post": {
        "summary": "Instant three-day free trial, no email or approval; one key per IP, daily availability cap",
        "responses": {
          "200": {
            "description": "Trial key (shown once)"
          },
          "409": {
            "description": "Trial already used"
          },
          "429": {
            "description": "Daily trial capacity reached"
          }
        }
      }
    },
    "/v1/watches": {
      "get": {
        "summary": "List your customer-selected watched GOV.UK pages (bearer key required)",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Watchlist"
          }
        }
      },
      "post": {
        "summary": "Register a canonical GOV.UK page for scheduled snapshot monitoring",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Queued"
          },
          "409": {
            "description": "Watchlist full"
          }
        }
      },
      "delete": {
        "summary": "Remove a watched URL owned by this API key; pass URL in query string",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Removed"
          }
        }
      }
    },
    "/v1/checkout": {
      "post": {
        "summary": "Start hosted Stripe Checkout (requires human purchase authorization)",
        "responses": {
          "200": {
            "description": "Checkout URL"
          },
          "503": {
            "description": "Not ready"
          }
        }
      }
    },
    "/v1/activate": {
      "post": {
        "summary": "Verify completed Stripe Checkout and issue API key automatically",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "session_id",
                  "claim"
                ],
                "properties": {
                  "session_id": {
                    "type": "string"
                  },
                  "claim": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "One-time API key issuance"
          },
          "409": {
            "description": "Payment not verified or already activated"
          }
        }
      }
    },
    "/v1/inspect": {
      "post": {
        "summary": "Inspect supported canonical GOV.UK Content API page; quote check is text matching, not factual correctness",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "quote": {
                    "type": "string",
                    "maxLength": 400
                  },
                  "previous_fingerprint": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result or inconclusive"
          },
          "401": {
            "description": "API key required"
          },
          "429": {
            "description": "Daily quota reached"
          }
        }
      }
    },
    "/v1/history": {
      "get": {
        "summary": "Historical fingerprints for the six fixed and each key-owned watchlist pages",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "History"
          },
          "401": {
            "description": "Unauthorised"
          },
          "404": {
            "description": "Page not monitored"
          }
        }
      }
    },
    "/v1/changes": {
      "get": {
        "summary": "Block-level changes between two latest DISTINCT stored versions",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved change comparison"
          },
          "401": {
            "description": "Unauthorised"
          }
        }
      }
    }
  }
}