# 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

### 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

### 1.2. 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.3. Sitemap
- **Route:** `GET /sitemap.xml`
- **Output:** XML URL set containing canonical URLs, `lastmod` dates, change frequencies, and priority weights.

## 2. Entity Model & Graph Relations
- **Buyer (Contracting Authority):** Canonical route `/buyers/{sourceId}`. Represents public bodies, NHS trusts, councils, central government departments.
- **Supplier (Economic Operator):** Canonical route `/suppliers/{sourceId}`. Represents companies awarded public contracts.
- **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.

## 3. 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).