# CouncilMonitor API complete reference

Every UK council meeting, agenda item, decision and paper as JSON, each record with its official council address.

- Base URL: `https://api.councilmonitor.co.uk/v1`
- Authentication: none needed to start; a Pro Plus key in `Authorization: Bearer cmk_...` or `X-API-Key: cmk_...`
- Site: https://councilmonitor.co.uk
- Endpoints: 10
- Generated: 2026-10-29
- This file: https://councilmonitor.co.uk/documentation/manual.md

## Before anything else

The data is the public record of UK councils' meetings: what each council published about its committees, their agendas, the decisions recorded in its own words and the papers behind them. It is factual records only, with no ratings, scores or forecasts on any endpoint.

What it does not contain, on any plan, at any price:

- items a council took in private (exempt or confidential business): they are left out, not hidden behind a plan;
- councillors' home addresses, phone numbers or email addresses;
- webcasts or recordings themselves, or transcripts of what was said in the room;
- anything a council did not publish on its own site.

Every answer is one envelope: `{"data": ..., "meta": {...}}`. `meta` carries the counts and pages of a list (`count`, `page`, `per_page`, `total`, `total_pages`, `next_page`, `prev_page`, `next_cursor`) and any note about the answer. A failure is `{"error": {"code", "message", "docs"}}` instead.

## Plans

| Plan | Price | What it reads | Rate limit | Calls |
| --- | --- | --- | --- | --- |
| No key | Free | Every endpoint but a paper's full text; each paper's opening 1,500 characters | 60 an hour from one address | 60 an hour |
| Pro Plus | £449 a month or £4,490 a year | Everything, with the full text of every paper | none beyond the month | 250,000 a calendar month, shared with the MCP server |
| Data licence | Agreed with us | Everything, plus whole-archive delivery | agreed | agreed |

Plans and prices: https://councilmonitor.co.uk/pricing

## Coverage

Counted from the archive when this file was made: 186 councils, 228,996 meetings and 2.8 million papers, from 2000 on. `GET /v1/councils` lists every council covered, and `GET /v1/councils/{slug}` says how much of one is in the archive.

## Endpoints

### Councils

The councils covered and their slugs.

#### `GET /v1/councils`

Every council covered, with its slug.

Plans: No key, Pro Plus, Data licence. Docs: https://councilmonitor.co.uk/documentation/councils

| Parameter | In | Type | Required | Description | Example |
| --- | --- | --- | --- | --- | --- |
| `q` | query | string | no | Words in the council's name. | `housing` |

Errors: `bad_request`, `unauthorized`, `unknown_parameter`, `rate_limited`, `quota_exceeded`, `server_error`.

Sample: `GET /v1/councils?q=argy` (a real answer, shortened: lists show their first few and long text its opening)

```json
{
  "data": [
    {
      "slug": "argyll-and-bute",
      "name": "Argyll and Bute",
      "link": "https://councilmonitor.co.uk/council/argyll-and-bute",
      "official_url": "https://www.argyll-bute.gov.uk/moderngov/"
    }
  ],
  "meta": {
    "count": 1
  }
}
```

#### `GET /v1/councils/{slug}`

One council: its name, its official site and how much of it is in the archive.

Plans: No key, Pro Plus, Data licence. Docs: https://councilmonitor.co.uk/documentation/council

| Parameter | In | Type | Required | Description | Example |
| --- | --- | --- | --- | --- | --- |
| `slug` | path | string | yes | The council's slug, as /v1/councils gives it. | `adur-and-worthing` |

Errors: `bad_request`, `unauthorized`, `not_found`, `unknown_parameter`, `rate_limited`, `quota_exceeded`, `server_error`.

Sample: `GET /v1/councils/argyll-and-bute` (a real answer, shortened: lists show their first few and long text its opening)

```json
{
  "data": {
    "slug": "argyll-and-bute",
    "name": "Argyll and Bute",
    "link": "https://councilmonitor.co.uk/council/argyll-and-bute",
    "official_url": "https://www.argyll-bute.gov.uk/moderngov/",
    "meetings": 3202,
    "first_meeting": "1995-06-05",
    "last_meeting": "2026-11-17",
    "collected": "2026-11-17T10:39:00Z"
  },
  "meta": {}
}
```

### Meetings

Meetings, their agendas and each item.

#### `GET /v1/meetings`

Meetings, newest first, or coming up first with upcoming=true.

Plans: No key, Pro Plus, Data licence. Docs: https://councilmonitor.co.uk/documentation/meetings

| Parameter | In | Type | Required | Description | Example |
| --- | --- | --- | --- | --- | --- |
| `council` | query | string | no | A council slug. | `adur-and-worthing` |
| `committee` | query | string | no | Words in the committee's name. | `planning` |
| `from` | query | string | no | On or after, YYYY-MM-DD. | `2026-01-01` |
| `to` | query | string | no | On or before, YYYY-MM-DD. | `2026-03-31` |
| `upcoming` | query | boolean | no | Only meetings from today on, soonest first. | `false` |
| `page` | query | integer | no | Page number, from 1. | `1` |
| `per_page` | query | integer | no | Results per page, at most 100. | `25` |
| `cursor` | query | string | no | The next_cursor from the previous answer; faster than page for walking far. |  |

Errors: `bad_request`, `unauthorized`, `unknown_parameter`, `rate_limited`, `quota_exceeded`, `server_error`.

Sample: `GET /v1/meetings?council=argyll-and-bute&to=2026-11-17&per_page=2` (a real answer, shortened: lists show their first few and long text its opening)

```json
{
  "data": [
    {
      "id": "mt_czxtzsef",
      "council": {
        "slug": "argyll-and-bute",
        "name": "Argyll and Bute"
      },
      "committee": "Planning, Protective Services and Licensing Committee",
      "date": "2026-11-17",
      "time": "10.30am",
      "venue": "By Microsoft Teams",
      "state": "today",
      "items": 9,
      "papers": 6,
      "link": "https://councilmonitor.co.uk/council/argyll-and-bute/meeting/2026-11-17-planning-protective-services-and-licensing-committee",
      "official_url": "https://www.argyll-bute.gov.uk/moderngov/ieListDocuments.aspx?MId=17135"
    },
    {
      "id": "mt_ca39nwh6",
      "council": {
        "slug": "argyll-and-bute",
        "name": "Argyll and Bute"
      },
      "committee": "Planning, Protective Services and Licensing Committee (Civic Hearings)",
      "date": "2026-11-17",
      "time": "2.30pm",
      "venue": "By Microsoft Teams",
      "state": "today",
      "items": 3,
      "papers": 0,
      "link": "https://councilmonitor.co.uk/council/argyll-and-bute/meeting/2026-11-17-planning-protective-services-and-licensing-committee-civic-hearings-17136",
      "official_url": "https://www.argyll-bute.gov.uk/moderngov/ieListDocuments.aspx?MId=17136"
    }
  ],
  "meta": {
    "count": 2,
    "next_cursor": "eyJvIjoyfQ",
    "page": 1,
    "per_page": 2,
    "total": 3194,
    "total_pages": 1597,
    "next_page": 2,
    "prev_page": null
  }
}
```

#### `GET /v1/meetings/{id}`

One meeting with its agenda: every item, what was decided and its papers.

Plans: No key, Pro Plus, Data licence. Docs: https://councilmonitor.co.uk/documentation/meeting

| Parameter | In | Type | Required | Description | Example |
| --- | --- | --- | --- | --- | --- |
| `id` | path | string | yes | The id, as the other endpoints give it. | `mt_hk4faxbe` |

Errors: `bad_request`, `unauthorized`, `not_found`, `unknown_parameter`, `rate_limited`, `quota_exceeded`, `server_error`.

Sample: `GET /v1/meetings/mt_hk4faxbe` (a real answer, shortened: lists show their first few and long text its opening)

```json
{
  "data": {
    "id": "mt_hk4faxbe",
    "council": {
      "slug": "argyll-and-bute",
      "name": "Argyll and Bute"
    },
    "committee": "Helensburgh and Lomond Area Community Planning Group",
    "date": "2026-11-10",
    "time": "10.00am",
    "venue": "ON A HYBRID BASIS IN THE MARRIAGE SUITE, HELENSBURGH AND LOMOND CIVICI CENTRE, 38 EAST CLYDE STREET, HELENSBURGH AND BY MICROSOFT TEAMS",
    "state": "held",
    "items": 32,
    "papers": 14,
    "link": "https://councilmonitor.co.uk/council/argyll-and-bute/meeting/2026-11-10-helensburgh-and-lomond-area-community-planning-group",
    "official_url": "https://www.argyll-bute.gov.uk/moderngov/ieListDocuments.aspx?MId=17114",
    "agenda": [
      {
        "id": "it_bdghatnk",
        "number": "1",
        "title": "WELCOME AND APOLOGIES",
        "outcome": null,
        "decision": null,
        "papers": [],
        "link": null
      },
      {
        "id": "it_q2yess1d",
        "number": "2",
        "title": "DECLARATIONS OF INTEREST",
        "outcome": null,
        "decision": null,
        "papers": [],
        "link": null
      },
      {
        "id": "it_6evgnbqh",
        "number": "3",
        "title": "MINUTES OF THE HELENSBURGH AND LOMOND COMMUNITY PLANNING GROUP HELD ON 18 AUGUST 2026",
        "outcome": null,
        "decision": null,
        "papers": [
          {
            "id": "pp_6mm0nmer",
            "title": "MINUTES OF THE HELENSBURGH AND LOMOND COMMUNITY PLANNING GROUP HELD ON 18 AUGUST 2026",
            "kind": "minutes",
            "pages": null,
            "text": "read",
            "link": "https://councilmonitor.co.uk/council/argyll-and-bute/meeting/2026-11-10-helensburgh-and-lomond-area-community-planning-group/papers/a59f709c5732/minutes-of-the-helensburgh-and-lomond-community-planning-group-held-on-18-august.pdf",
            "official_url": "https://www.argyll-bute.gov.uk/moderngov/documents/s236218/Minutes%2018082026%20Helensburgh%20and%20Lomond%20Area%20Community%20Planning%20Group.pdf"
          }
        ],
        "link": null
      }
    ]
  },
  "meta": {}
}
```

#### `GET /v1/items/{id}`

One agenda item: the decision in the council's words, the minutes and its papers.

Plans: No key, Pro Plus, Data licence. Docs: https://councilmonitor.co.uk/documentation/item

| Parameter | In | Type | Required | Description | Example |
| --- | --- | --- | --- | --- | --- |
| `id` | path | string | yes | The id, as the other endpoints give it. | `it_8b708b48` |

Errors: `bad_request`, `unauthorized`, `not_found`, `unknown_parameter`, `rate_limited`, `quota_exceeded`, `server_error`.

Sample: `GET /v1/items/it_8b708b48` (a real answer, shortened: lists show their first few and long text its opening)

```json
{
  "data": {
    "id": "it_8b708b48",
    "meeting": {
      "id": "mt_hk4faxbe",
      "council": {
        "slug": "argyll-and-bute",
        "name": "Argyll and Bute"
      },
      "committee": "Helensburgh and Lomond Area Community Planning Group",
      "date": "2026-11-10",
      "time": "10.00am",
      "venue": "ON A HYBRID BASIS IN THE MARRIAGE SUITE, HELENSBURGH AND LOMOND CIVICI CENTRE, 38 EAST CLYDE STREET, HELENSBURGH AND BY MICROSOFT TEAMS",
      "state": "held",
      "items": 32,
      "papers": 14,
      "link": "https://councilmonitor.co.uk/council/argyll-and-bute/meeting/2026-11-10-helensburgh-and-lomond-area-community-planning-group",
      "official_url": "https://www.argyll-bute.gov.uk/moderngov/ieListDocuments.aspx?MId=17114"
    },
    "number": "8a",
    "title": "Police Scotland Update",
    "outcome": "noted",
    "decision": "Decision The Helensburgh and Lomond Area Community Planning Group noted the information provided. (Reference: Report by Police Scotland dated October/November 2026, submitted)",
    "minutes": "The Group gave consideration to a report highlighting Police Scotland’s priorities for the Cowal, Bute and Helensburgh area including information on acquisitive crime; road safety; anti-social behaviour and violent crime; public protection; the rural partners day; fraud and scam ...",
    "papers": [
      {
        "id": "pp_29qe3n61",
        "title": "Police Scotland Update",
        "kind": "report",
        "pages": null,
        "text": "read",
        "link": "https://councilmonitor.co.uk/council/argyll-and-bute/meeting/2026-11-10-helensburgh-and-lomond-area-community-planning-group/papers/20616c463c0d/police-scotland-update.pdf",
        "official_url": "https://www.argyll-bute.gov.uk/moderngov/documents/s236005/Police%20Scotland%20NOV%202026.pdf"
      }
    ],
    "link": "https://councilmonitor.co.uk/council/argyll-and-bute/meeting/2026-11-10-helensburgh-and-lomond-area-community-planning-group/item/8a"
  },
  "meta": {}
}
```

### Decisions

What councils decided, in their own words.

#### `GET /v1/decisions`

Decisions councils have recorded, newest first, or best match first with q.

Plans: No key, Pro Plus, Data licence. Docs: https://councilmonitor.co.uk/documentation/decisions

| Parameter | In | Type | Required | Description | Example |
| --- | --- | --- | --- | --- | --- |
| `q` | query | string | no | Words in the item or its decision. | `housing` |
| `council` | query | string | no | A council slug. | `adur-and-worthing` |
| `from` | query | string | no | On or after, YYYY-MM-DD. | `2026-01-01` |
| `to` | query | string | no | On or before, YYYY-MM-DD. | `2026-03-31` |
| `page` | query | integer | no | Page number, from 1. | `1` |
| `per_page` | query | integer | no | Results per page, at most 100. | `25` |
| `cursor` | query | string | no | The next_cursor from the previous answer; faster than page for walking far. |  |

Errors: `bad_request`, `unauthorized`, `unknown_parameter`, `rate_limited`, `quota_exceeded`, `server_error`.

Sample: `GET /v1/decisions?council=argyll-and-bute&per_page=2` (a real answer, shortened: lists show their first few and long text its opening)

```json
{
  "data": [
    {
      "item": "it_cwptadjr",
      "meeting": "mt_5h4ndz14",
      "council": {
        "slug": "argyll-and-bute",
        "name": "Argyll and Bute"
      },
      "committee": "Argyll and Bute Local Review Body",
      "date": "2026-11-10",
      "number": "3",
      "title": "Consider notice of review request: inveraray shinty club, dalmally road, inveraray, pa32 8xd (ref: 26/0006/lrb)",
      "outcome": "agreed",
      "decision": "Decision The Members of the LRB agreed to adjourn the meeting to allow Members time to seek advice on the preparation of a competent Motion to approve the application subject to mitigation measures being put in place to reduce the impact the proposed development would have on the...",
      "link": "https://councilmonitor.co.uk/council/argyll-and-bute/meeting/2026-11-10-argyll-and-bute-local-review-body/item/3"
    },
    {
      "item": "it_pwpmq5nn",
      "meeting": "mt_hk4faxbe",
      "council": {
        "slug": "argyll-and-bute",
        "name": "Argyll and Bute"
      },
      "committee": "Helensburgh and Lomond Area Community Planning Group",
      "date": "2026-11-10",
      "number": "4",
      "title": "Helensburgh and lomond youth action council",
      "outcome": "noted",
      "decision": "Decision The Helensburgh and Lomond Area Community Planning Group noted the presentation. (Reference: Presentation by Helensburgh and Lomond Youth Action Council)",
      "link": "https://councilmonitor.co.uk/council/argyll-and-bute/meeting/2026-11-10-helensburgh-and-lomond-area-community-planning-group/item/4"
    }
  ],
  "meta": {
    "count": 2,
    "next_cursor": "eyJvIjoyfQ",
    "page": 1,
    "per_page": 2,
    "total": null,
    "total_pages": null,
    "next_page": 2,
    "prev_page": null
  }
}
```

### Papers

The papers behind every item, searched and read.

#### `GET /v1/papers/search`

Search the words inside every paper: officer reports, minutes, agendas and appendices.

Plans: No key, Pro Plus, Data licence. Docs: https://councilmonitor.co.uk/documentation/papers-search

| Parameter | In | Type | Required | Description | Example |
| --- | --- | --- | --- | --- | --- |
| `q` | query | string | yes | The words, a "phrase", -leave out, this OR that. | `housing` |
| `council` | query | string | no | A council slug. | `adur-and-worthing` |
| `type` | query | string | no | Only one kind of paper. One of: report, minutes, agenda, appendix, other. |  |
| `years` | query | string | no | How far back. One of: 1, 2, 5, all. | `all` |
| `sort` | query | string | no | Best match or newest first. One of: best, newest. | `best` |
| `page` | query | integer | no | Page number, from 1. | `1` |
| `per_page` | query | integer | no | Results per page, at most 100. | `25` |
| `cursor` | query | string | no | The next_cursor from the previous answer; faster than page for walking far. |  |

Errors: `bad_request`, `unauthorized`, `unknown_parameter`, `rate_limited`, `quota_exceeded`, `server_error`.

Sample: `GET /v1/papers/search?q=housing&council=argyll-and-bute&per_page=1` (a real answer, shortened: lists show their first few and long text its opening)

```json
{
  "data": [
    {
      "id": "pp_7e9b95j6",
      "title": "CommunitiesScotlandInvestmentProg0708ANNEX, 05/07/2007 Pre-Agenda Briefing of the Executive",
      "kind": "appendix",
      "pages": null,
      "text": "read",
      "link": "https://councilmonitor.co.uk/council/argyll-and-bute/meeting/2007-07-19-executive/papers/70042bbc3d6b/communitiesscotlandinvestmentprog0708annex-05-07-2007-pre-agenda-briefing-of-the.pdf",
      "official_url": "https://www.argyll-bute.gov.uk/moderngov/documents/s29688/CommunitiesScotlandInvestmentProg0708ANNEX%2005072007%20Pre-Agenda%20Briefing%20of%20the%20Executive.pdf",
      "council": {
        "slug": "argyll-and-bute",
        "name": "Argyll and Bute"
      },
      "committee": "Executive",
      "date": "2007-07-19",
      "meeting": "mt_ea6t00yh",
      "quote": "...Fyne Homes Ballochgoy, Rothesay £0.900m Provision of 24 Regeneration of Ballochgoy «Housing» Estate,\n general needs «houses» Rothesay including environmental improvements.\n for..."
    }
  ],
  "meta": {
    "count": 1,
    "next_cursor": "eyJvIjoxfQ",
    "page": 1,
    "per_page": 1,
    "total": 9770,
    "total_pages": 9770,
    "next_page": 2,
    "prev_page": null,
    "total_is_at_least": false
  }
}
```

#### `GET /v1/papers/{id}`

One paper: where it belongs, its pages and its opening (the full text with a key).

Plans: No key, Pro Plus, Data licence. Docs: https://councilmonitor.co.uk/documentation/paper

| Parameter | In | Type | Required | Description | Example |
| --- | --- | --- | --- | --- | --- |
| `id` | path | string | yes | The id, as the other endpoints give it. | `pp_7e9b95j6` |

Errors: `bad_request`, `unauthorized`, `not_found`, `unknown_parameter`, `rate_limited`, `quota_exceeded`, `server_error`.

Sample: `GET /v1/papers/pp_7e9b95j6` (a real answer, shortened: lists show their first few and long text its opening)

```json
{
  "data": {
    "id": "pp_7e9b95j6",
    "title": "CommunitiesScotlandInvestmentProg0708ANNEX, 05/07/2007 Pre-Agenda Briefing of the Executive",
    "kind": "appendix",
    "pages": null,
    "text": "read",
    "link": "https://councilmonitor.co.uk/council/argyll-and-bute/meeting/2007-07-19-executive/papers/70042bbc3d6b/communitiesscotlandinvestmentprog0708annex-05-07-2007-pre-agenda-briefing-of-the.pdf",
    "official_url": "https://www.argyll-bute.gov.uk/moderngov/documents/s29688/CommunitiesScotlandInvestmentProg0708ANNEX%2005072007%20Pre-Agenda%20Briefing%20of%20the%20Executive.pdf",
    "council": {
      "slug": "argyll-and-bute",
      "name": "Argyll and Bute"
    },
    "committee": "Executive",
    "date": "2007-07-19",
    "meeting": "mt_ea6t00yh",
    "item": "it_1qwjj4p9",
    "characters": 13025,
    "opening": "ANNEX\n COMMUNITIES SCOTLAND’S INVESTMENT PROGRAMME 2007/2008\nBute & Cowal\n DEVELOPER PROJECT PLANNED NATURE OF COMMENTS\n INVESTMENT PROVISION\nArgyll & Bute Council Demolition of Spence £0.130m Demolition of Payment of Early Action Funding in support of this\n Court redundant flats...",
    "text_parts": 1
  },
  "meta": {
    "note": "The opening 1,500 of 13,025 characters. The full text is at /v1/papers/pp_7e9b95j6/text with a Pro Plus key.",
    "plan": "Pro Plus"
  }
}
```

#### `GET /v1/papers/{id}/text` (Pro Plus key)

A paper's full text, in parts of 30,000 characters.

Plans: Pro Plus, Data licence. Docs: https://councilmonitor.co.uk/documentation/paper-text

| Parameter | In | Type | Required | Description | Example |
| --- | --- | --- | --- | --- | --- |
| `id` | path | string | yes | The id, as the other endpoints give it. | `pp_7e9b95j6` |
| `part` | query | integer | no | Which part, from 1. | `1` |

Errors: `bad_request`, `unauthorized`, `upgrade_required`, `not_found`, `unknown_parameter`, `rate_limited`, `quota_exceeded`, `server_error`.

Sample: `GET /v1/papers/pp_7e9b95j6/text?part=1` (a real answer, shortened: lists show their first few and long text its opening)

```json
{
  "data": {
    "id": "pp_7e9b95j6",
    "part": 1,
    "parts": 1,
    "characters": 13025,
    "text": "ANNEX\n COMMUNITIES SCOTLAND’S INVESTMENT PROGRAMME 2007/2008\nBute & Cowal\n DEVELOPER PROJECT PLANNED NATURE OF COMMENTS\n INVESTMENT PROVISION\nArgyll & Bute Council Demolition of Spence £0.130m Demolition of Payment of Early Action Funding in support of this\n Court redundant flats..."
  },
  "meta": {
    "next_part": null
  }
}
```

### Your key

What a key or an address has used.

#### `GET /v1/usage`

What this key or address has used, its limits and when they reset (not counted).

Plans: No key, Pro Plus, Data licence. Docs: https://councilmonitor.co.uk/documentation/usage

Errors: `bad_request`, `unauthorized`, `unknown_parameter`, `server_error`.

Sample: `GET /v1/usage` (a real answer, shortened: lists show their first few and long text its opening)

```json
{
  "data": {
    "plan": "No key",
    "key": null,
    "limit": 60,
    "period": "hour",
    "used": 3,
    "remaining": 57,
    "resets": "2026-11-17T12:00:00Z",
    "full_text": false
  },
  "meta": {}
}
```

## Guides

### Getting started

The base address, the envelope every answer comes in, and a first call without a key. https://councilmonitor.co.uk/documentation/start

Every address starts `https://api.councilmonitor.co.uk/v1/` (the `/v1` may be left off). Answers are JSON, always in one envelope: `data` with the records and `meta` with counts and notes, or `error` when something is wrong. No sign-up, no key: try it.

```
curl "https://api.councilmonitor.co.uk/v1/meetings?council=adur-and-worthing&upcoming=true"
```

The whole reference in one file for your assistant or to read offline: [manual.md](https://councilmonitor.co.uk/documentation/manual.md). For tools: [OpenAPI](https://councilmonitor.co.uk/openapi.json) and a [Postman collection](https://councilmonitor.co.uk/postman-collection.json).

### Keys

What a Pro Plus key adds, where to make one and how to send it. https://councilmonitor.co.uk/documentation/keys

Without a key the API gives every meeting, item and decision, paper search with a quoted line, and the opening of each paper, 60 requests an hour from one address. A **free key**, made on any account, covers those same endpoints at 1,000 requests a day. A **Pro Plus** key adds the full text of every paper and 250,000 a month. Make keys on [your account](https://councilmonitor.co.uk/account/api-keys) (each can be revoked); the same keys work with [the MCP server](https://councilmonitor.co.uk/mcp). Pro Plus also has [webhooks](https://councilmonitor.co.uk/account/webhooks): your own endpoints told the moment a paper, decision or agenda lands, in the same record shapes.

How to send your key, and rotating it, is in the [Authentication](https://councilmonitor.co.uk/documentation/authentication) guide.

### Authentication

The two ways to send your key, and rotating it. https://councilmonitor.co.uk/documentation/authentication

Send your key in a request header, either form:

```
Authorization: Bearer cmk_...
X-API-Key: cmk_...
```

A key in the address (`?key=`) is refused with a 400, so it never lands in a log or a browser history. Make and revoke keys on [your account](https://councilmonitor.co.uk/account/api-keys); the same keys work with [the MCP server](https://councilmonitor.co.uk/mcp).

To rotate a key, make a new one, move your calls across, then revoke the old. A **free key** gives the open endpoints at 1,000 requests a day; a **Pro Plus** key adds the full text of papers and 250,000 a month.

### Limits

Requests an hour without a key, a month with one, and the headers that count them. https://councilmonitor.co.uk/documentation/limits

|  | Requests | Full text of papers |
| --- | --- | --- |
| No key | 60 an hour from one address | The opening 1,500 characters |
| Free key | 1,000 a day | The opening 1,500 characters |
| Pro Plus key | 250,000 a calendar month, with the MCP server | All of it, in parts of 30,000 characters |
| Data licence | Agreed with us | All of it, plus whole-archive delivery |

Every answer carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (Unix seconds); a key's answers add `X-Quota-Remaining`. [/v1/usage](https://councilmonitor.co.uk/documentation/usage) shows the same without using a request.

### Errors

The error envelope and every code, with its status and when it comes. https://councilmonitor.co.uk/documentation/errors

An error is `{"error": {"code", "message", "docs"}}`, with `plan` when a plan would allow it. The message is for people; the code is for code, and never changes.

| Code | Status | When |
| --- | --- | --- |
| `bad_request` | 400 | A value is not in its shape: a date, a number, one of a list, or a key in the address |
| `unauthorized` | 401 | The key is not one of ours, or has been revoked |
| `upgrade_required` | 403 | The endpoint needs a Pro Plus key |
| `not_found` | 404 | No such council, meeting, item, paper or endpoint |
| `unknown_parameter` | 422 | A parameter the endpoint does not take: the message lists the ones it does |
| `rate_limited` | 429 | The hourly limit without a key: Retry-After says when it frees up |
| `quota_exceeded` | 429 | A key's month is used up: it resets on the 1st |
| `server_error` | 500 | Our fault; it is logged |

An empty result is not an error: it is a `200` with `meta.count` at 0.

### Pages of results

Walking a long list with page or cursor, and what meta says about it. https://councilmonitor.co.uk/documentation/pages

Lists take `page` (from 1) and `per_page` (up to 100, 25 by default). The first answer's `meta` has `count`, `page`, `per_page`, `total`, `total_pages`, `next_page` and `prev_page`, plus `next_cursor`. To walk a long list, send `cursor` instead of `page`: those answers carry only `count` and `next_cursor`, which is faster. `total` is `null` where counting everything would be slow.

### Ids and links

Council slugs, the ids of meetings, items and papers, dates, and the two links on every record. https://councilmonitor.co.uk/documentation/ids

Councils are named by their slug (`adur-and-worthing`). Meetings, items and papers have ids of their own: `mt_`, `it_` and `pp_` followed by eight letters and digits. They stay the same for good. Every record carries `link`, its page on CouncilMonitor, and `official_url`, its address on the council's own site.

Dates are the council's own day, `YYYY-MM-DD`; times are as the council gives them. A meeting's `state` is `upcoming`, `today` or `held`. Version 1 only ever gains fields: none is renamed, retyped or removed.

### Use with Claude and agents

The agent skill: one file that teaches Claude and other agents to use the API and the MCP server. https://councilmonitor.co.uk/documentation/agents

The CouncilMonitor agent skill is one markdown file that tells Claude, Cursor, Codex and other agents what CouncilMonitor answers, which endpoint or MCP tool to call for each question, the limits and the error codes. Agents that look for skills find it by themselves at `/.well-known/agent-skills/index.json`.

[Download skill.md](https://councilmonitor.co.uk/skill.md)

To install it, save it as `~/.claude/skills/councilmonitor/SKILL.md`, or upload it as a skill in Claude's settings. The [MCP server](https://councilmonitor.co.uk/mcp) works alongside it with the same keys.

## Errors

Every error is `{"error": {"code", "message", "docs"}}`, with `plan` when a plan would allow it. The code never changes; the message is for people. The full list: https://councilmonitor.co.uk/documentation/errors

## About this document

Generated from the API's registry, its guides and the pricing configuration, never written by hand. The date at the top is the date of the newest of those sources: two copies with the same date are the same. Machine-readable alternatives: https://councilmonitor.co.uk/openapi.json, https://councilmonitor.co.uk/postman-collection.json and the MCP server at https://councilmonitor.co.uk/mcp.
