API documentation

Getting started

The API base URL is issued when you request access — email us or use the contact page. Examples below use $BLINDSPOT_API_URL as a placeholder for the host you're given.

All responses are JSON unless explicitly noted (the AI streaming endpoint returns Server-Sent Events). The API is intended for read-mostly retrieval; there are no public write endpoints.

Health check:

curlcurl $BLINDSPOT_API_URL/api/health

Expected response:

json{
  "status": "ok",
  "records_indexed": 31000,
  "records_loaded": 493616,
  "policies_indexed": 673,
  "policies_loaded": 673
}

Authentication

Send your key as a header on any request:

httpAuthorization: Bearer bsl_live_xxxxxxxxxxxx

Mint and revoke keys from Manage Keys in the hub (up to 5 active keys per account).

Rate limits

Per source IP, on the public unauthenticated tier:

• 60 requests per minute on read endpoints
• 20 AI queries per hour on /api/query
• Burst capacity of up to 10 requests in any 5-second window

Limits return HTTP 429 with a Retry-After header. Keyed requests share the same limits during beta; plan-scaled limits arrive with paid tiers.

Precedents API

Filter and page through 493,616 planning records.

httpGET $BLINDSPOT_API_URL/api/records

Query parameters

Example

curlcurl "$BLINDSPOT_API_URL/api/records?council=Cork+City+Council&decision=GRANT&limit=5"

Response (truncated)

json{
  "records": [
    {
      "ref": "2460137",
      "council_name": "Cork City Council",
      "location": "Rathvilly Station House, Station Road, …",
      "proposal": "Construction of a single-storey rear extension …",
      "decision": "GRANT PERMISSION",
      "reg_date": "2024-07-12",
      "dec_date": "2024-09-30",
      "dev_category": "modification",
      "dev_scale": "single",
      "land_type": "private",
      "has_appeal": false
    }
  ],
  "total": 6763,
  "page": 1,
  "limit": 5,
  "pages": 1353
}

Single record

curlcurl "$BLINDSPOT_API_URL/api/records/2460137"

Returns the full record (all fields) or 404 if not found.

Policies — tree

Chapter → page list for the Dublin City Development Plan 2022–2028 Written Statement.

curlcurl $BLINDSPOT_API_URL/api/policies/tree

json[
  {
    "chapter": 11,
    "title": "Built Heritage and Archaeology",
    "pages": [
      { "id": "policy_p0359", "page": 359, "preview": "Development of Protected Structures …" }
    ]
  }
]

Policies — search

Semantic search over the Development Plan. Returns ranked page hits with chapter / page / citation / excerpt.

curlcurl "$BLINDSPOT_API_URL/api/policies/search?q=protected+structure+rear+extension&limit=3"

Query parameters

• q — required, ≥ 2 characters
• limit — int, 1–30, default 10

Response

json{
  "results": [
    {
      "id": "policy_p0359",
      "chapter": 11,
      "chapter_title": "Built Heritage and Archaeology",
      "page": 359,
      "citation": "Dev Plan Ch.11, p.359",
      "excerpt": "It is the Policy of Dublin City Council: Development of …",
      "relevance": 0.32
    }
  ]
}

Policies — page

Fetch the full text of a single Development Plan page.

curlcurl $BLINDSPOT_API_URL/api/policies/policy_p0359

json{
  "id": "policy_p0359",
  "page": 359,
  "chapter": 11,
  "chapter_title": "Built Heritage and Archaeology",
  "text": "Development of Protected Structures … (full page text)",
  "char_count": 3812
}

Errors

Error bodies are JSON of the form {"detail": "<description>"}.