The demo API

A live insurance API you can call from a browser. Every insurer, vehicle, person and policy in it is invented — it exists to be practised on.

Everything here is synthetic. No real policies, no real people, no real money. Credentials are throwaway and short-lived, and the data you create is deleted when they expire.

Do not enter anything real. Not a real registration number, not a real name, not a password you use anywhere else. There is no reason to, and this is a teaching sandbox rather than a confidential system. What this site does with data.

Pick a way in

Four routes to the same API. Each one is complete on its own — including getting credentials — so choose the tool you already use and ignore the rest.

Quick start

Nothing to install and no terminal. Press the button, then work through the quick-start page with the credentials it gives you.

Credentials are issued by one request, and the API's own documentation page can make it for you: open POST /mtpl/v1/demo-clients there, press Try it out, then Execute. Issue credentials in the API documentation.

Copy the secret now. It is shown once and is not stored anywhere it can be read back. Losing it costs nothing — press the button again for a fresh pair.

Using these credentials pushes the expiry back, so a session in progress will not be cut off. Leave them unused for a day and they are removed along with any policies you created.

Open the quick-start

It walks through the whole flow: list the coverage options, trade the credentials for a bearer token, then insure a vehicle.

cURL

Three commands from credentials to a created policy. Paste them in order and substitute the values the previous one returned.

1 · Throwaway credentials — no authentication needed

curl -X POST https://api.cybernotes.it/mtpl/v1/demo-clients

2 · A bearer token — valid for up to 60 minutes

curl -X POST https://api.cybernotes.it/mtpl/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET"}'

3 · Insure a vehicle — 201 the first time, 409 the second

curl -X POST https://api.cybernotes.it/mtpl/v1/policies \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"regNumber":"YOUR-PLATE"}'

Open the cURL cheat sheet

The cheat sheet covers the rest — updating and cancelling a policy, the rate-limited endpoint, and the signed-request exercise — and fills your own credentials into every command as you go.

Postman or Bruno

A ready-made collection with the whole workshop flow in order, including the requests that are meant to fail. Import it by URL:

https://api.cybernotes.it/mtpl/postman-collection.json

In Postman: Import → Link → paste → Continue. Run “Get demo credentials” first; the collection stores the client id, secret and token as variables, so the later requests fill themselves in.

Postman needs a free account to import. Signed out it only accepts pasted cURL. If you would rather not sign up, Bruno is a desktop client with no account at all, and Hoppscotch imports the same file in a browser tab — both read this collection format.

Download the collection

Swagger UI

Every endpoint, runnable in the page, with nothing installed and nothing pasted between windows.

Open the documentation page.
Find POST /mtpl/v1/demo-clients, press Try it out, then Execute. Copy the client id and secret from the response.
Do the same on POST /mtpl/v1/auth/token with those two values, and copy the access_token.
Press Authorize at the top, paste the token, and every endpoint below is now authenticated.

Open the API documentation

The same page also shows the request and response schemas, which is the part worth reading if you are writing a specification rather than calling one.

The one rule worth knowing

A vehicle can hold only one active policy. Insure a vehicle that already has cover and you get a 409 naming a policy you are not allowed to read — try it on ABC-101. That asymmetry is not a bug: a national register tells you a vehicle is insured without telling you whose policy it is. Deciding what an error may reveal is an interface design decision, and it is the one this API exists to make you notice.

The specifications

The series ships sample OpenAPI, WSDL, event and file-interface specifications — including one that is deliberately flawed, to be pulled apart rather than copied.

The sample specifications