This API lets a martial arts school's own website read the school's public information (studio details, programs, classes, a dated schedule, events, trial offers, instructors), see how full each class is, and send visitors in as leads, as full prospects with their students, or onto the waitlist of a full class. Everything comes back as JSON.
It is for whoever builds or runs the school's website. The school owner creates the key in Dojo and gives it to you together with the address below.
Want it as plain text for your notes or an AI assistant? Download this page as Markdown.
https://YOUR-DOJO-ADDRESS/pub/dm/v1
Each school has its own address. The owner copies it from Settings → Website API → Address (there is a Copy button beside it).
Send the API key on every request:
Authorization: Bearer YOUR_KEY
If your tool cannot set an Authorization header, send X-API-Key: YOUR_KEY
instead. Both work.
There are two kinds of key:
dm_pk_...): safe to put in a web page. It works only from
the websites the school lists against it, and it can never read student,
attendance or payment records.dm_sk_...): for code running on a server. Never put it in a
web page.A browser request from a website the key does not list is refused. Ask the
school to add your domain, including https:// (and your staging domain, if you
have one). Server-to-server calls send no Origin header, so the key alone
authorizes them.
If your website's server posts the forms to Dojo, use a secret key (the
school ticks Server key for families and documents when it creates the key),
and send the address of the visitor who filled in the form in an X-Visitor-IP
header:
X-Visitor-IP: 203.0.113.42
Every call from your server comes from the same address. Without this header,
Dojo counts all of your visitors as one: the per-visitor limits
(see Limits) cover your whole site, and a few bot submissions can get your
server blocked for a day. With it, limits and blocks apply to each visitor, and
the school's activity window shows the visitor's address. The header is
ignored on a publishable key, on calls from a browser, and when it is not an IP
address. Behind a proxy, take the address the proxy itself saw (usually the
last X-Forwarded-For entry), not one the visitor's browser could have sent.
curl -H "Authorization: Bearer YOUR_KEY" https://YOUR-DOJO-ADDRESS/pub/dm/v1/ping
A working key returns the school's name and the key's permissions. A bad key
returns 401.
The school can rotate a key in Settings. That issues a new key with the same
websites and permissions, and the old key keeps working for a period the school
chooses (from immediately up to seven days) so you can swap it in without any
downtime. After that the old key returns 401 key_expired. Keep the key in one
place in your code so a swap is a one-line change.
Every response is JSON in the same envelope:
{ "ok": true, "data": { }, "meta": { } }
{ "ok": false, "error": { "code": "invalid_key", "message": "..." }, "meta": { } }
meta describes the call itself, on success and on failure:
"meta": {
"request_id": "req_4f9c2a1be07d3a55",
"method": "GET",
"endpoint": "/pub/dm/v1/schedule",
"query": { "start": "2026-10-01", "end": "2026-10-14" },
"received_at": "2026-09-24T18:02:11Z",
"api_version": "v1"
}
request_id is also sent in the X-Request-Id header. Quote it when something
looks wrong, and the school can find that exact call under Recent activity
in their settings.
Read responses are cached for up to five minutes, so a change made in Dojo
shows on the website within a few minutes, not instantly. Class availability
(/classes and /classes/{id}/availability) is cached for only 30 seconds, so a
class that fills stops offering a trial almost at once. A cached answer repeats
the request_id of the call that filled the cache.
| Method | Path | What it does |
|---|---|---|
| GET | /ping |
Checks the key; returns the school name and the key's permissions |
| GET | /studio |
Name, phone, email, address, map link, logo, social links, time zone |
| GET | /programs |
The styles taught |
| GET | /classes |
The weekly class timetable, with live availability |
| GET | /classes/{id}/availability |
One class's availability: the quick call a page makes on load |
| GET | /schedule |
Classes and events on real calendar dates |
| GET | /events |
Events the school has chosen to show on its website |
| GET | /trials |
Trial and intro offers |
| GET | /instructors |
Instructor names, titles, ranks, bios and programs |
| GET | /parties |
Birthday party packages, their add-ons and the school's booking links |
| GET | /parties/availability |
Open party times for one package |
| GET | /form-token |
A one-use form check, for keys that require it (see Spam protection) |
| POST | /leads |
A contact form: creates a lead |
| POST | /trial-requests |
"Book a free class": a lead that records what they picked |
| POST | /prospects |
A full prospect: the account plus each student, as records |
| POST | /waitlist |
Puts a child on the waitlist of a full class |
The read endpoints need the key's read permission. The four POST endpoints
and /form-token need the key to allow submitting leads; the school sets that
when it creates the key.
Everything a header, footer or contact page needs: name, phone, email,
timezone, address (line1, line2, city, state, postal_code,
one_line, maps_url), logo_url and socials (platform, url).
programs: each with id, name, short_name, description.
The recurring weekly timetable. classes: each with id, name, program,
days (such as ["MON","WED"]), start_time and end_time ("18:30"),
start_label and end_label ("6:30 PM"), duration_minutes, age_min,
age_max, age_label, starts_on, ends_on. Also returns timezone.
Each class also says how much room it has, worked out by Dojo. Your site should never count spots itself.
{
"id": "5b0c...", "name": "Mini Elite", "program": "Tumbling",
"availability": {
"status": "FULL", "capacity": 8, "enrolled": 8,
"members": 7, "confirmed_trials": 1,
"waitlisted": 2, "spots_left": 0, "held_for_waitlist": 0
},
"accepts_trials": false,
"accepts_waitlist": true
}
status |
What your site should do |
|---|---|
OPEN |
Show the normal trial option |
LIMITED |
Same, and you can say "only a few spots left" (two or fewer) |
FULL |
Show the waitlist option |
WAITLIST |
Full, and families are already waiting: show the waitlist option |
CLOSED |
Reserved. A class that is not running is left out of the list, so you will not normally see this |
accepts_trials and accepts_waitlist are the answer to "which button do I
show". They combine the class's status with the school's own switches, which the
school sets per class (Show this class on my website, Offer online trials,
Offer the online waitlist). A class the school hides is not returned at all.spots_left is what can still be sold. A spot that has opened for a family
already waiting is not counted, so a stranger cannot take it ahead of them.
held_for_waitlist is how many open spots are being offered to the waitlist.confirmed_trials are trial students who have actually started. A trial
request that has not been completed holds no spot.OPEN with capacity, enrolled, spots_left and the other
counts left null.availability is null and both
accepts_ flags are false. Fall back to a contact form.Just the availability of one class (id, name, program, availability,
accepts_trials, accepts_waitlist). Use it when a page loads, or to re-check a
class just before showing a form. Returns 404 not_found for a class that does
not exist or that the school does not show on its website.
The classes placed on real dates, with events merged in, so you can draw an actual calendar.
| Query | Meaning |
|---|---|
start |
First date, YYYY-MM-DD. Defaults to today. |
end |
Last date, YYYY-MM-DD. Defaults to 30 days after start. At most 180 days after it. |
Returns timezone, start, end and days: each day has date, weekday
and entries, sorted by start time. Each entry has kind ("class" or
"event") and the fields from /classes or /events.
Takes the same start and end as /schedule. events: each with id,
name, description, location, category, date, start, end (in the
school's own time zone), start_time, start_label, cost, capacity.
Only events the school has marked for its website appear.
trials: each with id, name, description, price, duration_value,
duration_type ("classes" or "days"), duration_label.
instructors: each with id, name, title, rank, bio, programs. No
photos or personal contact details.
enabled is false, with empty lists, when the school is not taking party
bookings online. packages: each with id, name, description, included (a
list), price, duration_minutes, guest_limit, deposit, and addons (each with
id, name, pricing of "flat" or "per_guest", price). booking_links: each
with name, url and package_ids. Families book and pay on the page at
url -- point your "Book a Birthday Party" button there. The API never takes a
booking or a payment.
Takes package (an id from /parties) and the same start and end as
/schedule. slots: each with date, start_time, start_label, end_label, in
the school's own time zone, and only inside the dates the school takes bookings
for. Cached for 30 seconds, so a time can still be taken by the time a family
clicks through; the booking page always shows what is open right now.
Class times are plain weekly times such as "18:30", with a ready-made label
such as "6:30 PM". Event times are already converted to the school's own time
zone, which every payload with a time also returns as timezone. You do not
need to convert anything.
All four POST endpoints accept JSON or an ordinary form post. They land on the school's dashboard as a new lead straight away, and the school can choose to get an email or text when one arrives.
The simplest option: a contact form.
{
"first_name": "Sam",
"last_name": "Example",
"email": "[email protected]",
"phone": "903-555-0142",
"message": "Looking for kids classes on weekends.",
"interest": "Kids Karate",
"source": "Contact page"
}
first_name and last_name are required, plus at least one of email or
phone. If the email already belongs to someone the school knows, no duplicate
is made: the enquiry is added to that person's history and the response says
"existing": true.
Returns lead_id, existing and received.
Add ?with_signup_link=1 to also get a signup_url, valid for seven days, that
sends the visitor into the school's own full signup (students, waivers and card
details). Do not collect card details on your own site.
The same fields as /leads, plus any of trial_id, class_id,
preferred_date and student_name. It makes the same kind of lead and records
exactly what the visitor picked, so the school can call back already knowing.
If the class_id you send has since filled up, the request is refused with
409 class_full instead of being taken: show that class's waitlist option. A
trial request never holds a spot by itself; a spot is held only once the trial
has actually started.
Brings a family in as real records: the account with its address and emergency contact, and each student marked as a prospect. These are the same records the school's own sign-up link creates.
{
"first_name": "Sam",
"last_name": "Example",
"email": "[email protected]",
"phone": "903-555-0142",
"address": "12 Main St",
"city": "Springfield",
"state": "TX",
"zip_code": "75001",
"emergency_name": "Pat Example",
"emergency_phone": "903-555-0199",
"message": "Two kids, evenings work best.",
"interest": "Kids Karate",
"source": "Enroll page",
"students": [
{ "first_name": "Riley", "dob": "2017-05-14", "gender": "F" },
{ "first_name": "Jordan", "last_name": "Example", "dob": "2014-11-02",
"medical_notes": "Mild asthma, has an inhaler" }
]
}
| Field | Required | Notes |
|---|---|---|
first_name, last_name |
Yes | The account holder (usually the parent) |
email |
Yes | Must be a valid address |
phone |
Yes | A 10-digit U.S. number, or an international number starting with + |
address, city, state, zip_code |
No | |
emergency_name, emergency_phone |
No | Saved as the account's emergency contact |
message |
No | Saved on the account as what they are looking for |
interest, source |
No | Noted on the account's history |
students |
No | Up to 10. Each needs first_name; last_name defaults to the account's; dob is YYYY-MM-DD; gender and medical_notes are optional |
A plain HTML form cannot post a list, so a form post may send one student as
student_first_name, student_last_name, student_dob, student_gender and
student_medical_notes.
Returns 201:
{
"ok": true,
"data": {
"received": true,
"account_id": 81,
"account_number": "ACC-00081",
"students": [
{ "id": 501, "first_name": "Riley", "last_name": "Example",
"dob": "2017-05-14", "status": "prospect" },
{ "id": 502, "first_name": "Jordan", "last_name": "Example",
"dob": "2014-11-02", "status": "prospect" }
]
},
"meta": { }
}
/prospects always makes a new account. If the email or phone matches a family
the school already has, the school is warned to check for a duplicate. Nothing
is merged automatically. A refused field comes back with error.field naming
it, so your form can point at it.
A website cannot create a parent-portal login or store a card through this API.
To take payment, send the visitor to a signup_url from /leads.
Puts a child on the waitlist of a class that is full. Dojo stays the only waitlist: nothing is kept on your side.
{
"class_id": "5b0c...",
"first_name": "Sam", "last_name": "Example",
"email": "[email protected]", "phone": "903-555-0142",
"student_first_name": "Riley", "student_last_name": "Example",
"student_dob": "2020-05-14",
"message": "Tuesdays work best."
}
| Field | Required | Notes |
|---|---|---|
class_id |
Yes | From /classes |
first_name, last_name |
Yes | The parent. A single parent_name is also accepted and split at the first space |
email, phone |
Yes | Same rules as /prospects |
student_first_name, student_last_name |
Yes | The child. A single child_name is also accepted |
student_dob |
One of these two | YYYY-MM-DD. Send student_age (a whole number) if you only ask for an age |
message, source |
No | Noted on the family's history |
Returns 201 with the place they now hold:
{ "ok": true, "data": { "received": true, "existing": false,
"waitlist": { "position": 3, "status": "WAITING",
"class": { "id": "5b0c...", "name": "Mini Elite", "program": "Tumbling" } } } }
The family and child are created the same way as /prospects, and the school is
told (and by email or text if it has switched those on). When a spot opens, the
school sees who is next and contacts them; you do not need to do anything.
Idempotency-Key header (any unique string, such as a UUID made
when the form loads). If the visitor double-clicks or your request is retried,
the same key returns the first answer instead of adding a second family.
Keys are remembered for 24 hours. A refused request is not remembered, so the
visitor can fix the form and send it again.200, "existing": true, and
their current position.409 class_has_openings: the class has room now. Show the trial option instead.409 not_accepting: the school has turned the online waitlist off for this class.404 not_found: the class does not exist or is not shown on the website.409 request_in_progress: the first request with this key is still running.
Wait a moment and send the same request again.Nothing is merged into an existing family automatically. If the email or phone
matches a family the school already has, the school is warned to check for a
duplicate, exactly as with /prospects.
Add a text input named website, hidden with CSS and left empty. People never
see it; spam bots fill in every field they find. A submission with it filled in
gets a normal-looking answer and is held back for the school to review.
<input type="text" name="website" tabindex="-1" autocomplete="off"
style="position:absolute;left:-9999px;" aria-hidden="true">
A submission with a link in a name, or with three or more links in the message, is held back the same way. A held submission becomes a lead only if the school lets it through.
The school can also turn on two stronger checks for a key. Each one needs your
form to send something, so add it before the school turns the check on, or the
form will be refused with bot_check_failed. Both are safe to send to a key
that does not require them.
Form timing check. When the form is shown, call GET /form-token and put
the form_token it returns in a hidden field named form_token, or send it as
an X-Form-Token header. A token works once, must be at least 3 seconds old
when the form is sent, and lasts 2 hours. Fetch a new one after each submission.
const t = await fetch('https://YOUR-DOJO-ADDRESS/pub/dm/v1/form-token', {
headers: { 'Authorization': 'Bearer YOUR_PUBLISHABLE_KEY' }
}).then(r => r.json());
document.querySelector('#enquiry [name=form_token]').value = t.data.form_token;
{ "form_token": "1791234567.9f2c41d07ab3e815.5d…", "min_seconds": 3,
"expires_in": 7200, "required": true }
required says whether this key enforces the check.
Cloudflare Turnstile. The school creates a Turnstile widget for its website
in its own Cloudflare account and enters the widget's secret key in Dojo.
You add the widget to the form with its site key. The widget's hidden
cf-turnstile-response field goes along with the form; a form that sends JSON
may send the same value as captcha_token.
If your own server already checks the Turnstile result with Cloudflare, leave the Turnstile secret out of Dojo for that key. A Turnstile result can be checked only once, so a second check in Dojo would refuse every form. Check it in one place: on your server, or in Dojo.
An address that fails these checks three times in an hour is blocked for a day,
and the school can also block an address itself. A blocked address gets
403 blocked on every call. A server that sends forms for its visitors should
name each one (see Sending forms from your own server), or it is the address
that gets blocked.
<form id="enquiry">
<input name="first_name" placeholder="First name" required>
<input name="last_name" placeholder="Last name" required>
<input name="email" type="email" placeholder="Email" required>
<input name="phone" placeholder="Phone">
<textarea name="message" placeholder="How can we help?"></textarea>
<input type="text" name="website" tabindex="-1" autocomplete="off"
style="position:absolute;left:-9999px;" aria-hidden="true">
<button>Send</button>
</form>
<script>
document.getElementById('enquiry').addEventListener('submit', async (e) => {
e.preventDefault();
const res = await fetch('https://YOUR-DOJO-ADDRESS/pub/dm/v1/leads', {
method: 'POST',
headers: { 'Authorization': 'Bearer YOUR_PUBLISHABLE_KEY',
'Content-Type': 'application/json' },
body: JSON.stringify(Object.fromEntries(new FormData(e.target)))
});
const out = await res.json();
alert(out.ok ? 'Thanks! We will be in touch.' : out.error.message);
});
</script>
| What | Limit |
|---|---|
| Reads, per key | 600 requests every 5 minutes |
| Submissions, per key | 120 an hour |
| Submissions, per visitor | 5 an hour, and 20 a day. From your own server, see X-Visitor-IP |
A limited request returns 429 with a Retry-After header in seconds. Successful
responses carry X-RateLimit-Limit and X-RateLimit-Remaining.
| Status and code | Meaning |
|---|---|
401 missing_key |
No key was sent. Check the Authorization header. |
401 invalid_key |
The key is wrong, or the school revoked it. |
401 key_expired |
The school rotated this key and the old one has stopped. Ask for the new key. |
403 insufficient_scope |
The key is not allowed to submit leads. |
403 origin_not_allowed |
Your website is not on the key's list. Ask the school to add it, with https://. |
403 server_only |
A secret key was used from a web page. Secret keys work only from your website's server; use a publishable key in the page. |
403 server_not_allowed |
The school has listed the servers allowed to use this secret key, and this request came from another address. Ask the school to add your server's address. |
403 blocked |
The school has blocked the address this request came from. |
400 / 403 bot_check_failed |
The form did not pass the key's timing or Turnstile check. Fetch a new form token or reset the widget, then send again. |
400 bad_request |
A date is malformed, or the range is too long. |
400 missing_field |
A required field is empty. The message (and error.field on /prospects) names it. |
400 invalid_field / invalid_email |
A value is not valid, such as an email or a date of birth. |
400 too_many_students |
More than 10 students in one /prospects call. |
404 not_found |
The class does not exist, or the school does not show it on its website. |
409 class_full |
A trial request named a class that has filled. Offer its waitlist. |
409 class_has_openings |
A waitlist request for a class that has room. Offer the trial. |
409 not_accepting |
The school has turned the online waitlist off for this class. |
409 request_in_progress |
The first request with this Idempotency-Key is still running. |
429 rate_limited |
Too many requests. Wait for Retry-After. |
500 server_error / 503 server_error |
Something went wrong on our side. Try again. |
A CORS error in the browser usually means origin_not_allowed. The school can
confirm it in Settings → Website API → Open activity window, which lists
every call, why any failed or were blocked, and the lead each one brought in.
Every response carries a request_id; quote it and the school can find that
exact call.
That is what makes a publishable key safe to put in a web page.