JiveFinderAPI

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 GET under /v1 and answers JSON (or a calendar for .ics). GET /v1 lists 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: KEY also works. Keep keys out of browser code.
  • The host limits the data, whatever the key: jive.finderapi.dev only 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) and cursor, from the last page's next_cursor.
  • Every answer carries an attribution block. Show it, with its link, wherever the data appears. Each listing's url points at its JiveFinder page; keep it.
  • Every response has X-RateLimit-Limit and X-RateLimit-Remaining for the day (UTC). Over a limit you get 429 with Retry-After in 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."}}
StatusCodeMeans
401unauthorisedNo key, an unknown key, or a revoked key.
403forbiddenThe key is not for this host, or an organisation key has lapsed because its holder no longer manages the listing.
404not_foundNo such host, or nothing with that id in your scope.
429rate_limitedOver 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.

ParameterMeaning
nearlat,lng, a postcode or a place name.
within60m 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, toDates, 2026-11-24. from defaults to today. The widest range depends on your tier.
typeClass, Freestyle, Workshop, Weekender, Holiday, Tea Dance, Beginner Event. Comma-separated. See /v1/event-types.
competitiontrue for events with a competition.
styleStyles on this host only. Comma-separated. See /v1/styles.
lesson_onlytrue or false.
skill_levelbeginner, improver, intermediate, advanced, all.
price_maxPounds or euros, matched against the price amount.
weekdaymon to sun, comma-separated.
starts_after, starts_beforeTimes, 19:00.
organisation, venueAn organisation reference or a venue id, to narrow to one.
limit, cursorPaging.

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>