MTPL Policy Demo API — quick-start

A live, fully synthetic motor-insurance API for the analyst workshop series. Every insurer, vehicle, person and policy is fictional by construction — nothing here is real, so you can experiment freely from any device.

1 · Get credentials — one click, no terminal

Working through this on your own? Press the button. It creates a throwaway client id and secret for you, and nothing else is needed to finish every step on this page.

In a live workshop instead?

Use the client id on your card — analyst-01 … analyst-20 — with the shared secret the facilitator reads out. That path still works exactly as before, and your policies are still yours alone.

2 · Your first call — no auth needed

curl -s https://api.cybernotes.it/mtpl/v1/coverage-options
200 OK
{ "options": [ { "code": "MTPL-STD", "name": "Mandatory motor liability", "term": "P1Y" } ] }

3 · Get a bearer token (valid 60 min)

curl -s https://api.cybernotes.it/mtpl/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"client_id":"<your client_id>","client_secret":"<your client_secret>"}'
200 OK
{ "access_token": "eyJhbGciOiJIUzI1NiIs…", "token_type": "Bearer", "expires_in": 3600, … }

The token is a real JWT — paste it into jwt.io and inspect the sub, scope and exp claims.

4 · Insure a vehicle

curl -s -X POST https://api.cybernotes.it/mtpl/v1/policies \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"regNumber":"ABC-103"}'
201 Created
{ "id": "pol-…", "status": "active", "startDate": "…", "endDate": "…", … }

Good to know

Errorsalways RFC 9457 application/problem+json — read type, title, detail
Rate limits60 requests/min per address; watch the RateLimit-* headers. GET /limited/ping allows only 5/min — call it six times to see a live 429 + Retry-After
PaginationGET /policies?page=2&pageSize=20 — you only see policies your client created; fleet.demo owns 70+
Lifecycleactive → updated (PUT) → cancelled (POST …/cancel, idempotent); cancelled/expired are immutable
Clients Postman without an account accepts only pasted cURL — use the ready-made commands on the cURL cheat sheet: Import → paste one command → Send, one request at a time.
Postman signed in (free account) or Bruno (desktop, no account needed): import the full collection from https://api.cybernotes.it/mtpl/postman-collection.json — in Postman Import → paste the URL; in Bruno Import Collection → Postman format (URL or the downloaded file).
Specstruthful: /mtpl/v1/openapi.yaml · the gap-hunt draft: /mtpl/v0/openapi.yaml