Minute Book API

Getting started

1. An administrator of your organisation makes a key on the API keys page of their account. Give each program its own key.
2. Copy the key straight away. We keep only a scrambled form of it, so we can’t show it to you again. If you lose it, revoke it and make a new one.
3. Send the key with every request, in the Authorization header:

curl -H "Authorization: Bearer mb_live_…" \
  "https://minute-book.com/api/v1/search?q=corridor+care"

Every request starts /api/v1 and every answer is JSON, sent with Cache-Control: no-store so browsers and proxies don’t keep it. A path that doesn’t exist is a JSON 404 too.

Keeping keys safe

• Put the key only in the Authorization header. Never put it in a web address, in code that runs in someone’s browser, or in anything you publish.
• Your organisation can have up to 10 keys that work at once. Give each program its own, so you can stop one without stopping the others.
• To change a key, rotate it on the API keys page rather than copying one key between programs. The old key keeps working for 24 hours so you can switch over, then stops by itself. A key being rotated counts as two of your 10 until then.
• A revoked key stops working on the next request, and programs using it get 401 invalid_key.
• A key belongs to your organisation, not to a person, and your organisation is responsible for everything done with it. Keep it out of email, chat, tickets and shared documents.

Limits

Every request with a valid key counts, including ones that find nothing. Requests turned away for going over a limit don’t count. Months and days are UK time. If your agreement sets a higher monthly limit, that applies instead.

A shared address can lock itself out. Once an address has failed with a missing or wrong key more than 30 times in a minute or 300 in a day, every request from it gets 429 too_many_attempts, even with a valid key, until the count falls: for up to a day. If several programs reach us through one shared address (a company network, say), one program with a wrong key can stop the others. Fix a failing key quickly, and give each program its own.

Administrators see how much each key has used on the API keys page. For 10,000 requests a month and 60 a minute, that is the default; if you need more, talk to us.

Headers that tell you where you stand

Answers to requests with a valid key carry these headers, including a 429 for a limit, which also has a Retry-After header giving the number of seconds to wait. Answers that refuse the key itself (401, 403 no_plan, 403 not_included, 429 too_many_attempts) and the 503 when we can’t check the key don’t. The find headers are on find requests only.

Requests

There are four. The id of a document is the one search results give. For a coroner’s report or response (kind pfd-report or pfd-response), id is not a document id. Use url, the report’s page on Minute Book, and source_url, the report on judiciary.uk. The three document requests all answer 404 for it.

{
  "query": "corridor care",
  "total_documents": 214,
  "capped": false,
  "page": 1,
  "results": [
    {
      "document": {
        "id": "3c41e0…",
        "organisation": {
          "slug": "northfell-hospitals",
          "name": "Northfell Hospitals NHS Foundation Trust"
        },
        "meeting_body": { "type": "board", "name": "Board" },
        "meeting_date": "2026-09-10",
        "date_precision": "day",
        "kind": "minutes",
        "minutes_status": "draft",
        "draft_note": "These minutes were marked as a draft when we collected them. …",
        "reuse_status": "extracts_only",
        "extracts_only": true,
        "source_url": "https://www.northfell-hospitals.example/board/2026-09-minutes.pdf",
        "retrieved_at": "2026-09-12T07:41:00Z",
        "ocr": false,
        "page_known": true,
        "url": "https://minute-book.com/documents/3c41e0…?org=northfell-hospitals"
      },
      "matching_pages": 2,
      "hits": [
        { "page": 11, "snippet": { "text": "…corridor care had been used on 19 of the 31 days in August…" } }
      ]
    }
  ]
}

What you get back

Most organisations haven’t agreed that we can reuse their papers, so for those we give short extracts of up to 50 words, as on the site, and only the first 3 matching pages of a document. Where an organisation publishes under the Open Government Licence or has agreed to reuse, you get the full passage. Coroners’ reports are always in full. Each result says which with reuse_status and extracts_only.

Every result has the document’s source_url on the organisation’s own website, and when we collected it. On the document request, where the organisation has since taken the document down, archived_record is true and our unchanged copy is offered as an archived record (see the file request). Draft minutes keep their draft label: check minutes_status and show the draft_note with anything you quote from them. ocr: true means some text was read automatically from scanned pages, so it may contain errors.

Errors

Errors have a status, and a body with a code your program can check and a message you can show to a person:

{ "error": { "code": "key_minute_limit", "message": "Too many requests: up to 60 a minute for this key. Wait for the number of seconds in the Retry-After header, then try again." } }

Need more than your limits allow, or something the API doesn’t do? Talk to us.

Citing and reusing what you get

The terms apply to the API as to the site, and section 8.7 covers the API when available. Existing contracts retain their API promises until the required notice or express agreement. You may quote and cite what you find as long as you say where it came from. Cite it like this:

• Extracts only means extracts. Where extracts_only is true, quote the extract and link to the original for the rest.
• Don’t rebuild documents. Don’t chain searches or find requests to put a document, or large parts of it, back together from extracts. Link to the original instead. This is why find requests have a daily limit.
• No bulk extraction. Don’t download or copy what we hold in bulk, or work around the limits.
• No machine-learning training. Don’t use what you get to train or fine-tune machine-learning or AI models without our written agreement.
• No competing dataset. Don’t build a database, dataset or service from it that stands in for Minute Book.
• Keep the draft label. Anything you quote from draft minutes keeps its draft_note.
• Not for sales, and not for targeting people. Don’t use the API for sales leads, tenders or marketing to the organisations whose papers we hold, or to harass, intimidate or target the people named in them.
• Personal information. Results can contain personal information. Your organisation’s role follows why and how it uses that information, or the instructions it follows for another controller. Handle it in line with data protection law. Tell us promptly about requests to correct, restrict or remove information obtained from Minute Book so we can assess the request too. We notify recipients where the law requires it. Publisher licence and statutory rights remain.

Your searches and our logs

For API searches we count requests by key and kind of request, without keeping search words in those counts. Request addresses can include search or find words in our web host’s technical logs, as described in the privacy notice. See the privacy notice.