API pubblica di insegnanti, studi e lezioni

Leggi la stessa directory che le persone vedono su MoveMentors: insegnanti indipendenti, piccoli studi e le loro prossime lezioni. Niente registrazione, niente chiave, JSON semplice. Pensata perché agenti IA e piccoli strumenti indichino lezioni vicine senza fare scraping.

URL di base

https://movementors.com/api/v1

Tutti gli endpoint qui sotto partono da qui. Un semplice GET restituisce l'elenco di tutti in JSON.

Provala

Trova cinque insegnanti di pilates. Incolla questo in un terminale:

curl "https://movementors.com/api/v1/mentors?category=pilates&limit=5"

Endpoint

Tutti in sola lettura e gratuiti. Gli elenchi accettano page e limit (fino a 50).

EndpointCosa restituisce
GET/api/v1/mentorsCerca insegnanti indipendenti per testo, città o disciplina.
GET/api/v1/mentors/{slug}Il profilo pubblico di un insegnante: discipline, luoghi e certificazioni.
GET/api/v1/studiosCerca piccoli studi. Aggiungi rentable=1 per le sale che altri insegnanti possono affittare.
GET/api/v1/studios/{slug}Il profilo pubblico di uno studio e le sue sedi.
GET/api/v1/classesProssime sessioni, online o in presenza, con date, prezzi e host.
GET/api/v1/classes/{id}Una lezione con il suo calendario e il suo host.
GET/api/v1/healthSe il servizio è attivo.
GET/api/v1/openapi.jsonIl contratto OpenAPI 3.1 completo, per generatori di codice e agenti.

Autenticazione

Nessuna per gli endpoint di questa pagina. Per prenotare una lezione o gestire un calendario per qualcuno, un agente usa il nostro server MCP con OAuth, così la persona approva prima.

Collega un assistente IA

Errori

Ogni errore torna come JSON nel formato problem RFC 9457 (application/problem+json), mai come pagina HTML. Leggi code per decidere cosa fare e hint per capire come risolvere.

  • 400invalid_parameter

    Un parametro della query è sbagliato. Il campo param lo indica.

  • 404not_found

    Questo endpoint, insegnante, studio o lezione non esiste.

  • 405method_not_allowed

    Questi endpoint leggono soltanto. Usa GET.

  • 429rate_limited

    Troppe richieste. Aspetta i secondi indicati in Retry-After.

  • 500internal_error

    Qualcosa si è rotto da parte nostra. Riprova aspettando un po' di più ogni volta.

  • 503service_unavailable

    Il servizio è momentaneamente non disponibile. Riprova più tardi.

HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "https://movementors.com/developers#error-not_found",
  "title": "Not Found",
  "status": 404,
  "detail": "Teacher not found",
  "instance": "/api/v1/mentors/unknown",
  "code": "not_found",
  "hint": "Check the path and identifier. GET /api/v1 lists every public endpoint.",
  "error": "Teacher not found"
}

Limiti di utilizzo

I limiti sono per indirizzo IP: 100 richieste al minuto, più 5.000 al giorno sugli endpoint di elenco. Ogni risposta dice a che punto sei, così puoi rallentare prima di esaurirli.

  • RateLimit-Policy

    Le tue quote, per esempio "burst";q=100;w=60.

  • RateLimit

    Richieste rimaste e secondi prima che ogni quota si azzeri.

  • RateLimit-Limit / -Remaining / -Reset

    Lo stesso per la quota più vicina all'esaurimento, nel vecchio formato a valore singolo.

  • Retry-After

    Su un 429, quanti secondi aspettare.

Versioni

La versione è nel percorso, quindi niente cambia senza preavviso.

  • Nuovi endpoint, parametri e campi vengono aggiunti a v1 direttamente. Il tuo codice continua a funzionare.
  • Tutto ciò che romperebbe il codice esistente, come togliere o rinominare un campo, esce come /api/v2.
  • Prima che una versione venga spenta, le sue risposte portano un header Deprecation (RFC 9745) e un header Sunset (RFC 8594) con la data, con almeno 6 mesi di anticipo.

Per agenti e strumenti

Punti di ingresso leggibili dalle macchine: GET /api/v1 · OpenAPI 3.1 · API catalog (RFC 9727) · llms.txt · MCP server card

Domande, o ti serve un limite più alto? Scrivi a support@movementors.com