openapi: 3.0.3
info:
  title: SortedUK Public Data API
  description: |
    Free, read-only UK consumer-help data — verified UK helplines, recurring UK deadlines,
    and UK money routes citizens may be missing (benefits, grants, refunds, social tariffs).

    All data is sourced to UK official bodies (GOV.UK, HMRC, DWP, NHS, Companies House,
    FCA, Ofgem, etc) and licensed CC-BY 4.0.

    These are static JSON files served from the Netlify CDN — no rate limits, no auth.
    Updated monthly. Last verified date is included in every response.

    Designed for: AI assistants (ChatGPT/Claude/Gemini plugin manifests), partner sites,
    open-data researchers, journalists, councils, charities, and developers building
    UK consumer-help tools.
  version: "1.0.0"
  license:
    name: CC-BY-4.0
    url: https://creativecommons.org/licenses/by/4.0/
  contact:
    name: SortedUK
    url: https://sorteduk.uk/platform
    email: data@sorteduk.uk
  termsOfService: https://sorteduk.uk/promise

servers:
  - url: https://sorteduk.uk
    description: Production (Netlify CDN)

paths:
  /data/index.json:
    get:
      summary: List all available data feeds
      description: Directory of every public Sorted data feed with metadata, schemas, and counts.
      operationId: listFeeds
      tags: [Directory]
      responses:
        '200':
          description: Successful response with the feed directory
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedDirectory'

  /data/uk-helplines.json:
    get:
      summary: Get verified UK helplines
      description: |
        Verified UK helplines across crisis, money, housing, energy, health, family,
        disability, legal, work, scams, older people, and abuse. Each entry includes
        the phone number, hours, free/paid status, description, URL, charity number
        (where applicable), FCA number (where applicable), and last verified date.
      operationId: getHelplines
      tags: [Helplines]
      responses:
        '200':
          description: List of UK helplines
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HelplinesFeed'

  /data/uk-deadlines.json:
    get:
      summary: Get UK recurring deadlines
      description: |
        Recurring UK consumer, tax, and benefit deadlines that quietly cost people
        money when missed. Includes Self Assessment, MR/SSCS appeal windows, council
        Tax PCN windows, Companies House filings, school admissions, etc.
      operationId: getDeadlines
      tags: [Deadlines]
      responses:
        '200':
          description: List of UK deadlines
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeadlinesFeed'

  /data/uk-money-routes.json:
    get:
      summary: Get UK money routes citizens may be missing
      description: |
        Every UK route to money citizens may be owed but rarely claim — Pension Credit,
        Attendance Allowance, Council Tax Reduction, Marriage Allowance, water + broadband
        social tariffs, Section 75, train delay-repay, lost pensions, dormant accounts,
        and 20+ more. Each entry has an annual value range, eligibility audience tags,
        the UK body that administers it, and a claim URL.
      operationId: getMoneyRoutes
      tags: [Money Routes]
      responses:
        '200':
          description: List of UK money routes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MoneyRoutesFeed'

components:
  schemas:
    FeedDirectory:
      type: object
      properties:
        name: { type: string }
        description: { type: string }
        license: { type: string, example: "CC-BY-4.0" }
        last_updated: { type: string, format: date }
        version: { type: string }
        feeds:
          type: array
          items:
            type: object
            properties:
              id: { type: string }
              name: { type: string }
              url: { type: string, format: uri }
              count: { type: integer }
              schema: { type: string, format: uri }

    HelplinesFeed:
      type: object
      properties:
        name: { type: string }
        description: { type: string }
        license: { type: string }
        last_updated: { type: string, format: date }
        count: { type: integer }
        helplines:
          type: array
          items:
            $ref: '#/components/schemas/Helpline'

    Helpline:
      type: object
      required: [id, name, category, phone, country]
      properties:
        id: { type: string, example: "samaritans" }
        name: { type: string, example: "Samaritans" }
        category:
          type: string
          enum: [crisis, money-debt, housing, energy-bills, health, family, disability, legal, work, scams-fraud, older-people, abuse-safety, council-services, food-crisis]
        phone: { type: string, example: "116 123" }
        phone_e164: { type: string, example: "+44116123" }
        hours: { type: string, example: "24/7" }
        free: { type: boolean }
        description: { type: string }
        url: { type: string, format: uri }
        charity_number: { type: string }
        fca_number: { type: string }
        country: { type: string, example: "UK" }
        operator: { type: string }
        verified: { type: string, format: date }

    DeadlinesFeed:
      type: object
      properties:
        name: { type: string }
        license: { type: string }
        last_updated: { type: string, format: date }
        count: { type: integer }
        deadlines:
          type: array
          items:
            $ref: '#/components/schemas/Deadline'

    Deadline:
      type: object
      required: [id, name, category, recurrence, who, country]
      properties:
        id: { type: string }
        name: { type: string }
        category:
          type: string
          enum: [tax, council, energy, benefits, schools, savings, benefits-appeals, fines, business, documents]
        month: { type: integer, minimum: 1, maximum: 12 }
        day: { type: integer, minimum: 1, maximum: 31 }
        recurrence:
          type: string
          enum: [annual, quarterly, monthly, per-decision, per-pcn, ongoing, "10-year + 70+ every 3 years", "annual (from 3rd birthday)"]
        days_from_decision: { type: integer }
        days_from_issue: { type: integer }
        months_after_year_end: { type: integer }
        who: { type: string }
        consequence_text: { type: string }
        source_url: { type: string, format: uri }
        country: { type: string }
        affects:
          type: array
          items: { type: string }

    MoneyRoutesFeed:
      type: object
      properties:
        name: { type: string }
        license: { type: string }
        uk_total_unclaimed_annual_gbp: { type: integer, example: 23000000000 }
        uk_total_source: { type: string }
        last_updated: { type: string, format: date }
        count: { type: integer }
        routes:
          type: array
          items:
            $ref: '#/components/schemas/MoneyRoute'

    MoneyRoute:
      type: object
      required: [id, name, category, who_administers, country, claim_url]
      properties:
        id: { type: string }
        name: { type: string }
        category:
          type: string
          enum: [benefits, council, tax-relief, family, energy, bills, compensation, hidden-money, crisis, housing, business, benefits-extras]
        audience:
          type: array
          items: { type: string }
        annual_value_low_gbp: { type: number }
        annual_value_high_gbp: { type: number }
        value_basis: { type: string }
        extra_backdated_max_gbp: { type: number }
        extra_backdated_note: { type: string }
        who_administers: { type: string }
        country: { type: string }
        statute: { type: string }
        claim_url: { type: string, format: uri }
        unlocks:
          type: array
          items: { type: string }
          description: IDs of other routes this one cascades into (e.g. Pension Credit unlocks Warm Home Discount)
        uk_underclaim_estimate: { type: string }
        verified: { type: string, format: date }

tags:
  - name: Directory
    description: Listing of available feeds
  - name: Helplines
    description: Verified UK helplines (charity + government registered)
  - name: Deadlines
    description: Recurring UK consumer + tax + benefit deadlines
  - name: Money Routes
    description: UK money routes citizens may be missing
