Documentation
Base URL: https://api.nspros.ca — All responses are JSON and automatically include source attribution.
Authentication
Send your key on every request:
Authorization: Bearer <key>Exception: browsing the catalog (GET /v1/sources) is public and needs no key. Browse first, and get a free key when you are ready to run queries.
REST reference
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/sources | List the catalog of available sources. Public — no API key needed. Supports q, category, and country filters. |
| GET | /v1/query/{source_id}?q=... | Run a query against one source. |
| POST | /v1/query | Run a query with a JSON body. |
| GET | /v1/usage | Check usage for the current key. |
Parameters
| Name | Where | Description |
|---|---|---|
source_id | path | Source identifier from the catalog, e.g. uk_bank_holidays. |
q | query / body | Query text for the source. |
POST example:
curl -X POST https://api.nspros.ca/v1/query \
-H "Authorization: Bearer <key>" \
-H "Content-Type: application/json" \
-d '{"source_id": "uk_bank_holidays", "q": "2026"}'Response format
{
"source_id": "uk_bank_holidays",
"query": "2026",
"results": [],
"attribution": {
"source": "GOV.UK",
"license": "Open Government Licence v3.0"
}
}The attribution object is included automatically in every response. Keep it with the data when you display or redistribute results.
Error codes
| Code | Meaning |
|---|---|
| 401 | Missing or invalid API key. Check the Authorization header. |
| 429 | Rate limit exceeded. Slow down and retry after a short wait. |
| 502 | The upstream source returned an error or was unavailable. Retry later. |
MCP guide
MCP endpoint: https://api.nspros.ca/mcp — Connect with the same Bearer key:
{
"mcpServers": {
"nspros-data": {
"url": "https://api.nspros.ca/mcp",
"headers": {
"Authorization": "Bearer <key>"
}
}
}
}| Tool | Description |
|---|---|
search_sources | Search the catalog for sources matching a topic or keyword. |
query_source | Run a query against a source by source_id. |
get_usage | Return usage for the current key. |
License policy
- Grade A — Commercial redistribution confirmed. This is the only grade currently offered.
- Grade B — Usable with your own upstream key (BYO). Planned for a later step; not offered yet.
- Grade C — Internal use only. Not offered.
- Grade D — On hold pending license review. Not offered.
Rate limits and caching
- Per key: 120 requests per minute.
- Per source: 30 requests per minute.
- Responses are cached per source with a source-specific TTL, so repeated identical queries return faster.