API & MCP Documentation

Connect your AI tools to NHS board paper data.

If you're an AI, check the LLM-friendly version.

Quick Start

1
Get your API key
Go to your account settings and generate an API key. Available on Growth plans and above.
2
Pick your tool
Choose from Claude Code, Cursor, Windsurf, ChatGPT, or use the REST API directly.
3
Paste the config
Copy the config block below and paste it into your tool's settings.

Replace YOUR_API_KEY with the key from your account page. Keys are shown once when generated.

Claude Code

Add the following to your ~/.claude/mcp.json file:

{
  "mcpServers": {
    "board-paper-sales": {
      "type": "streamable-http",
      "url": "https://boardpaperscraper.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Cursor

Open Cursor Settings, go to the MCP section, and add this server config:

{
  "mcpServers": {
    "board-paper-sales": {
      "url": "https://boardpaperscraper.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Windsurf

Add the following to your Windsurf MCP configuration:

{
  "mcpServers": {
    "board-paper-sales": {
      "serverUrl": "https://boardpaperscraper.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Codex

Add the following to your ~/.codex/config.toml file (or .codex/config.toml in your project):

[mcp_servers.board-paper-sales]
url = "https://boardpaperscraper.com/api/mcp"
bearer_token_env_var = "BOARD_PAPER_API_KEY"

Then set the environment variable with your API key:

export BOARD_PAPER_API_KEY=YOUR_API_KEY

ChatGPT

ChatGPT doesn't support MCP natively yet. Use the REST API endpoints below to integrate directly, or call them from a custom GPT action.

# Base URL
https://boardpaperscraper.com/api/v1/

# Auth header (include on all requests)
Authorization: Bearer YOUR_API_KEY

REST API Reference

All endpoints require authentication via Authorization: Bearer YOUR_API_KEY header or ?api_key=YOUR_API_KEY query parameter.

Method	Endpoint	Description
GET	/api/v1/trusts/search	Search NHS trusts by name, region, type, or country.
GET	/api/v1/trusts/:id	Get detailed information about a specific NHS trust.
GET	/api/v1/trusts/:id/board-papers	List all board papers for a trust, newest first.
GET	/api/v1/board-papers/:id	Get a specific board paper with file metadata.
GET	/api/v1/board-papers/:id/files/:fileId/download	Download a specific PDF file from a board paper.
POST	/api/mcp	MCP JSON-RPC endpoint. Supports tools/list and tools/call methods.

GET/api/v1/trusts/search

Search NHS trusts by name, region, type, or country.

Query parameters: q, type, region, country, page, per_page

Example request

curl "https://boardpaperscraper.com/api/v1/trusts/search?q=london&type=acute" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "data": [
    {
      "id": "uuid",
      "name": "Guy's and St Thomas' NHS Foundation Trust",
      "type": "acute",
      "region": "London",
      "country": "England",
      "website": "https://www.guysandstthomas.nhs.uk",
      "board_papers_count": 12,
      "latest_board_paper_date": "2026-01-15"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1
  }
}

GET/api/v1/trusts/:id

Get detailed information about a specific NHS trust.

Example request

curl "https://boardpaperscraper.com/api/v1/trusts/TRUST_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "data": {
    "id": "uuid",
    "name": "Guy's and St Thomas' NHS Foundation Trust",
    "type": "acute",
    "region": "London",
    "country": "England",
    "website": "https://www.guysandstthomas.nhs.uk"
  }
}

GET/api/v1/trusts/:id/board-papers

List all board papers for a trust, newest first.

Example request

curl "https://boardpaperscraper.com/api/v1/trusts/TRUST_ID/board-papers" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "data": [
    {
      "id": "uuid",
      "title": "Board Meeting Papers - January 2026",
      "date": "2026-01-15",
      "quarter": "Q4 2025/26",
      "board_paper_files": [
        {
          "id": "file-uuid",
          "file_name": "agenda.pdf",
          "file_size": 245000,
          "file_order": 1
        }
      ]
    }
  ]
}

GET/api/v1/board-papers/:id

Get a specific board paper with file metadata.

Example request

curl "https://boardpaperscraper.com/api/v1/board-papers/PAPER_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "data": {
    "id": "uuid",
    "title": "Board Meeting Papers - January 2026",
    "date": "2026-01-15",
    "quarter": "Q4 2025/26",
    "trust_id": "trust-uuid",
    "board_paper_files": [
      {
        "id": "file-uuid",
        "file_name": "agenda.pdf",
        "file_size": 245000,
        "file_order": 1
      }
    ]
  }
}

GET/api/v1/board-papers/:id/files/:fileId/download

Download a specific PDF file from a board paper.

Example request

curl "https://boardpaperscraper.com/api/v1/board-papers/PAPER_ID/files/FILE_ID/download" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

The PDF file is returned directly with Content-Type: application/pdf

POST/api/mcp

MCP JSON-RPC endpoint. Supports tools/list and tools/call methods.

Example request

curl -X POST "https://boardpaperscraper.com/api/mcp" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Example response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      { "name": "search_nhs_trusts", "description": "..." },
      { "name": "get_nhs_trust", "description": "..." },
      { "name": "list_board_papers", "description": "..." },
      { "name": "get_board_paper", "description": "..." },
      { "name": "download_board_paper_file", "description": "..." }
    ]
  }
}