For developers and assistants

The BJJ Professor API

Bring the position map, coaching chapters and timestamped instructional clips into your app or assistant. The public REST API is free, read-only, and requires no account or API key.

Open the API OpenAPI specification

Try it without signing in

All paths below use the base URL https://bjjprofessor.app/api/v1 and return JSON. Start with a search, then pass a result's ID to the position or transitions endpoint.

curl 'https://bjjprofessor.app/api/v1/positions/search?q=half+guard+bottom'
curl 'https://bjjprofessor.app/api/v1/positions/half-guard-bottom'

You can also open the example search directly in your browser. When using a response in an answer, cite its position page and the relevant timestamped clip.

What you can retrieve

Find a position

GET /positions/search?q=half+guard+bottom

Search positions, techniques and concepts by name or alias. Results include node IDs, evidence counts and the position page to cite. Use q for the search and limit for up to 25 results (default 8).

View JSON example

Read a position

GET /positions/{id}

Get the position's evidence and timestamped clips. Where a curated chapter exists, the response also includes its explanation, technique options, when to use them and common mistakes with fixes. Use an ID returned by search.

View JSON example

Explore what comes next

GET /positions/{id}/transitions

Find the positions and techniques connected to a node, grouped by relationship, with triggers and supporting instructional clips.

View JSON example

Browse the curated chapters

GET /chapters

List chapter titles, position IDs, summaries and canonical page links, along with the published corpus counts.

View JSON example

Find example match reviews

GET /demo-rolls

List public demo reviews with match titles, athletes, summaries, durations and IDs to use in the review endpoint.

View JSON example

Read an example review

GET /demo-rolls/{id}

Retrieve coaching, key moments and a positional timeline for a public demo. The ID comes from /demo-rolls; it is not a position ID. Personal rolls are accessed through the signed-in MCP connection.

Using it with ChatGPT or Claude

This page documents the public API for readers and assistants. Reading a website does not automatically install its tools. An integration that can make HTTP requests can use these endpoints without credentials.

For personal coaching, focus areas, session logs and your analyzed rolls, connect the MCP server at https://bjjprofessor.app/api/mcp. It requires Google sign-in through OAuth, including for its public read tools. A free account is enough to connect. A 401 response before signing in is the authentication challenge, not a missing endpoint.

Set up your assistant connection

Responses and limits

A successful request returns 200. A search with no matches returns an empty results list; an unknown position or demo ID returns 404. Rate-limited requests return 429 with a Retry-After header. Browser requests are supported with public CORS headers.

Responses contain curated knowledge and published example reviews. Evidence counts describe the indexed instructional corpus. For the full endpoint specification, use openapi.json.