Docs
The examples use jive.finderapi.dev, the Modern Jive host. Every other host works the same way over its own styles. Replace KEY with a key from your account.
Basics
- Every endpoint is a
GETunder/v1and answers JSON (or a calendar for.ics).GET /v1lists them all. - To get a key, sign in with Continue with JiveFinder, which uses your JiveFinder account, or with a code we email you. There is no password.
- Send your key as
Authorization: Bearer KEY.X-API-Key: KEYalso works. Keep keys out of browser code. - The host limits the data, whatever the key:
jive.finderapi.devonly ever returns jive. An organisation key narrows it further to that organisation's own events, venues and teachers. - Lists are cursor-paged:
limit(default 25, at most 100) andcursor, from the last page'snext_cursor. - Every answer carries an
attributionblock. Show it, with its link, wherever the data appears. Each listing'surlpoints at its JiveFinder page; keep it. - Every response has
X-RateLimit-LimitandX-RateLimit-Remainingfor the day (UTC). Over a limit you get429withRetry-Afterin seconds.
A wrong parameter is a 400 whose message names it. Other errors look like this:
{"error": {"code": "unauthorised", "message": "That key is not recognised."}}
| Status | Code | Means |
|---|---|---|
| 401 | unauthorised | No key, an unknown key, or a revoked key. |
| 403 | forbidden | The key is not for this host, or an organisation key has lapsed because its holder no longer manages the listing. |
| 404 | not_found | No such host, or nothing with that id in your scope. |
| 429 | rate_limited | Over the per-minute or per-day allowance. |
Events
GET /v1/events
The event search: what is on within a drive or a distance of a place, between two dates, with filters.
| Parameter | Meaning |
|---|---|
near | lat,lng, a postcode or a place name. |
within | 60m for drive minutes or 40km for distance. Minutes only work when both ends are in Great Britain; elsewhere give km. A minutes search routes the 100 nearest halls by straight line; a hall further out than those is not checked, so for wide searches use km. |
from, to | Dates, 2026-11-24. from defaults to today. The widest range depends on your tier. |
type | Class, Freestyle, Workshop, Weekender, Holiday, Tea Dance, Beginner Event. Comma-separated. See /v1/event-types. |
competition | true for events with a competition. |
style | Styles on this host only. Comma-separated. See /v1/styles. |
lesson_only | true or false. |
skill_level | beginner, improver, intermediate, advanced, all. |
price_max | Pounds or euros, matched against the price amount. |
weekday | mon to sun, comma-separated. |
starts_after, starts_before | Times, 19:00. |
organisation, venue | An organisation reference or a venue id, to narrow to one. |
limit, cursor | Paging. |
A filter on skill_level or price_max only matches events where we know the value. An unknown is null, never a guess.
curl -H "Authorization: Bearer KEY" \
"https://jive.finderapi.dev/v1/events?near=Bristol&within=60m&from=2026-11-20&to=2026-11-30&type=Freestyle"
One event in the answer:
{
"id": 123456,
"title": "Ceroc Bristol Tuesday",
"type": "Class",
"competition": false,
"styles": ["Ceroc"],
"date": "2026-11-24",
"start": "19:30", "end": "23:00",
"lesson_only": false,
"skill_level": null,
"price": {"text": "£11, members £9", "amount": 11.0, "currency": "GBP"},
"venue": {"id": 77, "name": "...", "town": "Bristol", "lat": 51.45, "lng": -2.59},
"organisation": {"reference": "ceroc-bristol", "name": "...", "verified": true, "url": "..."},
"rooms": [],
"travel": {"minutes": 42, "km": 31.5, "method": "road"},
"source": {"url": "https://...", "last_read": "2026-11-18T03:30:00Z"},
"url": "https://jivefinder.com/event/123456"
}
travel is there when you gave near. minutes is road time when both ends are in Great Britain, and null elsewhere, where method is straight_line and only km is given. An event with several rooms lists each room and its own styles.
GET /v1/events/{id}
One event.
curl -H "Authorization: Bearer KEY" https://jive.finderapi.dev/v1/events/123456
GET /v1/events.ics
The same search as a calendar feed. It takes every parameter of /v1/events.
curl -H "Authorization: Bearer KEY" \
"https://jive.finderapi.dev/v1/events.ics?near=51.45,-2.59&within=40km"
Venues
GET /v1/venues
Halls with something on, by area or name. Parameters: near, within (in km), q (words in the venue's name or town), limit, cursor.
curl -H "Authorization: Bearer KEY" "https://jive.finderapi.dev/v1/venues?near=Bath&within=20km"
GET /v1/venues/{id}
GET /v1/venues/{id}/events
One venue, and its upcoming events. The events take the date and filter parameters of /v1/events.
curl -H "Authorization: Bearer KEY" https://jive.finderapi.dev/v1/venues/77/events
Organisations
GET /v1/organisations/{reference}
GET /v1/organisations/{reference}/events
A club or organiser, and its upcoming events. The events are also a calendar at /v1/organisations/{reference}/events.ics.
curl -H "Authorization: Bearer KEY" https://jive.finderapi.dev/v1/organisations/ceroc-bristol/events
Teachers and judges
GET /v1/teachers
GET /v1/teachers/{reference}
Teacher and judge profiles: the same public content as their pages on JiveFinder. Parameters: q (words in the name), role (teacher or judge; both if left out), limit, cursor.
curl -H "Authorization: Bearer KEY" "https://jive.finderapi.dev/v1/teachers?role=judge"
Styles and event types
GET /v1/styles
GET /v1/event-types
/v1/styles lists the values style accepts on this host. /v1/event-types lists the event types in use on this host; the type filter accepts any known event type name, so a type with nothing on this host yet simply finds nothing.
curl -H "Authorization: Bearer KEY" https://jive.finderapi.dev/v1/styles
MCP server
Assistants can search the listings through the MCP server at https://jive.finderapi.dev/mcp (streamable HTTP). It has the same scope as the API. There are two ways in: sign in with your JiveFinder account (add the server with no key and your client opens a browser to sign in; this is how claude.ai connectors work), or send a developer key as the bearer token. Its tools are search_events, get_event, find_venues, organisation_events, find_teachers, get_teacher and list_styles; every result carries the JiveFinder link and the date we last read the listing.
Claude (claude.ai, desktop and mobile)
Settings, Connectors, Add custom connector, then paste https://jive.finderapi.dev/mcp. Claude opens finderapi.dev to sign in with your JiveFinder account and asks you to allow it. The connection appears on your account page as a connected app, and you can revoke it there.
Claude Code
claude mcp add --transport http jivefinder https://jive.finderapi.dev/mcp
Then run /mcp in Claude Code to sign in. With a key instead:
claude mcp add --transport http jivefinder https://jive.finderapi.dev/mcp --header "Authorization: Bearer KEY"
Claude Desktop with a key
Add this to claude_desktop_config.json (Settings, Developer, Edit Config), then restart Claude Desktop:
{
"mcpServers": {
"jivefinder": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://jive.finderapi.dev/mcp",
"--header", "Authorization: Bearer KEY"]
}
}
}
Club widget
A claimed club can show its next dates on its own site with one line, and no key. Each date links to its JiveFinder page. Use your organisation reference, the last part of your page's address on JiveFinder.
<script src="https://jive.finderapi.dev/widget.js" data-org="REFERENCE" async></script>