# Tenderline: Full AI Agent Specification & Knowledge Graph

> Comprehensive documentation for AI agents, LLMs, and automated crawlers accessing the Tenderline UK public procurement knowledge base.

## Overview
Tenderline operates a relational read model over official UK procurement notices published under the Procurement Act 2023 and the Public Contracts Regulations 2015. Raw JSON snapshots are deduplicated and retained immutably; data is normalized into an interconnected graph of contracting authorities, economic operators, procedure notices, award decisions, and signed contracts.

## 1. Machine Endpoints

Analytical sections (competition, prices, benchmarks) appear only where the published record holds enough evidence; a thin record says so instead of guessing.

### 1.1. Single Tender Markdown
- **Route:** `GET /tenders/{slug}.md` or `GET /tenders/{slug}` with header `Accept: text/markdown`
- **Output:** Clean GitHub-flavored Markdown containing:
  - H1: Tender title
  - Blockquote: 2-3 sentence fact synopsis (Executive Summary)
  - Key information list (Status, Buyer, Published Value, Submission Deadline, Lots, Method, CPV classifications, Legal Basis, OCID)
  - Submission gateway (External portal host and instructions)
  - Description
  - Lots specification (Lot title, value, criteria, contract period)
  - Awards and winning suppliers
  - Signed contracts
  - Provenance links
  - Interactive Intelligence Hook: Link to visual competition analysis (#procedure-competition-analysis)

### 1.2. Contracting Authority (Buyer) Markdown
- **Route:** `GET /buyers/{slug}.md` or `GET /buyers/{slug}` with header `Accept: text/markdown`
- **Output:** Clean GitHub-flavored Markdown containing:
  - H1: Authority name and country dossier
  - Synopsis: Classification, region, live open tenders count, total tracked procedures count
  - Key information list (Classification, Region, Registry ID, Live Open Tenders, Total Procedures)
  - Competition profile (Typical bids per notice, single-bidder procedure rate, price drop medians)
  - Primary procurement sectors (CPV breakdowns with procedure counts and percentage share)
  - Key awarded suppliers (Top counterparties by procedure and award counts)
  - Retender radar & upcoming contract expiries (Active contracts ending in 6m/18m)
  - Interactive Intelligence Hook: Link to full spend and counterparty dossier (#spend-analytics)

### 1.3. Winning Supplier Markdown
- **Route:** `GET /suppliers/{slug}.md` or `GET /suppliers/{slug}` with header `Accept: text/markdown`
- **Output:** Clean GitHub-flavored Markdown containing:
  - H1: Supplier name and UK public sector contract record
  - Synopsis: Company scale (SME/Large), total public awards count, delivery regions
  - Key information list (Scale, CRN registration, Total Awards, Primary Sector)
  - Market volume & benchmarks (Total published spend, median contract value)
  - Delivery geography (Active UK regions)
  - Top public sector clients (Top contracting authorities by award counts)
  - Contract expiries & upcoming recompetes (Active contracts ending in 18m)
  - Interactive Intelligence Hook: Link to full win-loss and contract history (#contract-history)

### 1.4. CPV Sector Dossier Markdown
- **Route:** `GET /sectors/{slug}.md` or `GET /sectors/{slug}` with header `Accept: text/markdown`
- **Output:** Clean GitHub-flavored Markdown containing:
  - H1: Sector name and CPV code
  - Synopsis: Classification level (Division or Class), parent division, open tenders count, 12m notice volume
  - Key information list (CPV Code, Level, Parent Division, Live Open Tenders, Active Authorities, Tender Window)
  - Market competition & benchmarks (Median bids per lot, IQR middle half, Net contract values, SME & Local win rates)
  - Sub-sectors / CPV Classes breakdown
  - Live open tender opportunities with direct tender URLs
  - Leading contracting authorities and awarded suppliers in the sector
  - Delivery geography (ITL-1 regions distribution)
  - Direct link to the sector RSS feed (`/sectors/{slug}/feed.xml`)

### 1.5. Regional Procurement Dossier Markdown
- **Route:** `GET /regions/{slug}.md` or `GET /regions/{slug}` with header `Accept: text/markdown`
- **Output:** Clean GitHub-flavored Markdown containing:
  - H1: Region name and ITL-1 prefix
  - Synopsis: Regional procurement volume, open notices, authority counts
  - Regional competition benchmarks (Typical bids per lot, SME win rate, Local supplier win rate)
  - Live open tenders delivered in the region
  - Leading regional contracting authorities and winning suppliers
  - Primary procurement sectors (CPV divisions) delivered in the region

### 1.6. E-Sourcing Portal Intelligence Markdown
- **Route:** `GET /platforms/{slug}.md` or `GET /platforms/{slug}` with header `Accept: text/markdown`
- **Output:** Clean GitHub-flavored Markdown containing:
  - H1: Portal name and commercial operator
  - Synopsis: Portal role, submission gateway hosts, open tender counts
  - How to Bid: Supplier registration advice, prerequisites, support contacts
  - Competition benchmarks (Typical bids per lot, single-bid rate, SME win rate)
  - Live open tenders routing submissions through this portal
  - Leading contracting authorities and suppliers using the gateway

### 1.7. Market Insights Dossier Markdown
- **Route:** `GET /market-insights.md` or `GET /market-insights` with header `Accept: text/markdown`
- **Output:** Clean GitHub-flavored Markdown containing:
  - H1: UK Public Procurement Market Insights & Pipeline
  - Live Market Pulse: Total open tenders, PIN pipelines, 12m volume, contracting authorities, awarded suppliers
  - Early-market engagement & PIN pipeline opportunities
  - UK-wide competition benchmarks & commercial vehicle distribution
  - Busiest CPV sectors, regional procurement activity, and portal distribution

### 1.8. Single Tender Public JSON API
- **Route:** `GET /api/public/tenders/{ocid}` or `GET /tenders/{slug}.json`

- **Response Schema:**
  ```json
  {
    "schemaVersion": "1.0",
    "id": "string (ocid)",
    "title": "string | null",
    "description": "string | null",
    "status": "string (active | complete | planned | cancelled)",
    "procurementStage": "string",
    "buyer": {
      "id": "string | null",
      "name": "string | null",
      "profileUrl": "string | null"
    },
    "value": {
      "amount": "number",
      "currency": "ISO currency code | null",
      "formatted": "string"
    },
    "deadline": "ISO 8601 string | null",
    "publishedAt": "ISO 8601 string | null",
    "classifications": ["string"],
    "locations": ["string"],
    "submissionGateway": {
      "url": "string | null",
      "portal": "string | null",
      "method": "string | null",
      "electronicSubmissionPolicy": "string | null"
    },
    "lotsCount": "number",
    "lots": [
      {
        "id": "string",
        "title": "string | null",
        "description": "string | null",
        "status": "string | null",
        "value": { "amount": "number", "currency": "string" },
        "contractPeriod": { "start": "ISO string", "end": "ISO string" },
        "suitability": { "sme": "boolean", "vcse": "boolean" }
      }
    ],
    "awards": [
      {
        "id": "string",
        "title": "string | null",
        "status": "string | null",
        "suppliers": "string | null",
        "value": { "amount": "number", "currency": "string" },
        "awardedAt": "ISO string | null"
      }
    ],
    "contracts": [
      {
        "id": "string",
        "title": "string | null",
        "status": "string | null",
        "value": { "amount": "number", "currency": "string" },
        "signedAt": "ISO string | null"
      }
    ],
    "provenance": {
      "source": "find-a-tender",
      "officialNoticeUrl": "string | null",
      "latestReleaseAt": "ISO string | null",
      "canonicalUrl": "string",
      "markdownUrl": "string"
    }
  }
  ```

### 1.9. Machine Sitemap Index & Shards
- **Root Directory Sitemap:** `GET /sitemap.xml` (core navigational hub routes).
- **Specialized & Sharded Sub-Sitemaps:**
  - `GET /sitemaps/tenders-active.xml`: Notices that still accept a response (deadline ahead, or no deadline on a non-planning notice updated within 12 months).
  - `GET /sitemaps/tenders.xml`: Sitemap index for closed/awarded catalogue (monthly historical shards).
  - `GET /sitemaps/tenders-planning.xml`: Pipeline / PME / planned notices (last 12m).
  - `GET /sitemaps/buyers.xml`: UK contracting authorities / public buyers dossier index.
  - `GET /sitemaps/suppliers.xml`: Sitemap index for winning suppliers (16 stable shards by id hash: `/sitemaps/suppliers-0.xml` … `/sitemaps/suppliers-f.xml`).
  - `GET /sitemaps/sectors.xml`: CPV divisions and the CPV classes with at least 10 notices.
  - `GET /sitemaps/regions.xml`: ITL-1 UK delivery geography index.
  - `GET /sitemaps/platforms.xml`: E-sourcing submission gateways index.
- **Output:** Valid Sitemaps XML protocol (0.9), edge-cached at Cloudflare.

### 1.10. Real-Time Stage RSS Feeds
- **Routes:**
  - `GET /feeds/tenders.rss`: UK tenders that still accept a response (100 latest, publication dates, estimated values, submission deadlines, CPV categories).
  - `GET /feeds/planning.rss`: Pipeline / PME / planned-procurement notices (top 50 latest; early signals before ITT).
  - `GET /feeds/awards.rss`: Recent UK public sector contract awards (top 50 latest, awarded suppliers, contract amounts, awarding authorities).
- **Format:** Standard RSS 2.0 with Atom self-links, formatted for instant syndication and automated feed readers.
- **Cache-Control:** Edge-cached (`s-maxage=900, stale-while-revalidate=86400`).

### 1.11. Research Studies
- **Hub:** `GET /research` (dated studies, newest first).
- **Study:** `GET /research/{slug}`: findings, tables with lots, 95% intervals and medians, method, limits and a citation line. First study: `/research/single-bid-contracts-2024-2026`.
- **Aggregates:** `GET /research/{slug}/data.csv` (one row per table and cut; `bid_count_measure` is `received` or `final`).
- **Refresh:** a study keeps its URL when its data is rebuilt; the page shows the published and updated dates.

## 2. Canonical Directory Hubs & Fast Navigation
- **Concise AI Summary Index:** `GET /llms.txt`
- **CPV Sectors Directory:** `/sectors` (individual dossiers: `/sectors/{cpv-slug}`)
- **UK Regions Directory:** `/regions` (individual dossiers: `/regions/{region-slug}`)
- **E-Sourcing Platforms Directory:** `/platforms` (individual dossiers: `/platforms/{platform-slug}`)
- **Contracting Authorities (Buyers):** `/buyers` (profiles: `/buyers/{canonical-slug}`)
- **Winning Suppliers:** `/suppliers` (profiles: `/suppliers/{canonical-slug}`)
- **Market Intelligence & PIN Pipelines:** `/market-insights` (raw mirror: `/market-insights.md`)
- **Methodology & Mathematical Formulas:** `/methodology` (data definitions, sample windows, competition benchmarks)

## 3. Entity Model & Graph Relations
- **Buyer (Contracting Authority):** Canonical route `/buyers/{slug}`. Represents public bodies, NHS trusts, councils, central government departments. Profile URLs carry permanent register-backed keys (`ons-`, `nhs-`, `gov-`, `coh-`).
- **Supplier (Economic Operator):** Canonical route `/suppliers/{slug}`. Represents commercial and third-sector suppliers awarded public contracts. Profile URLs carry Companies House verified keys (`coh-`).
- **Procedure (Process):** Canonical route `/tenders/{slug}-{ocid}`. Represents the unified procurement process from notice to award and delivery.
- **CPV (Common Procurement Vocabulary):** 8-digit EU/UK taxonomy code classifying goods, services, and works.

## 4. Legal and Regulatory Framework
- Regulated under UK Public Contracts Regulations (PCR 2015) and Procurement Act 2023.
- Above-threshold procurements must be published to Find a Tender.
- Devolved authorities in Scotland, Wales, and Northern Ireland maintain specific regional portals (Sell2Wales, Public Contracts Scotland, eTendersNI).