Documentazione API di Skillsail

Questa documentazione sull’API di Skillsail descrive la versione 1. La descrizione OpenAPI è disponibile all’indirizzo https://skillsail.com/openapi.json. La creazione dei corsi non è una raccolta di risorse REST: gli agenti creano e modificano i moduli tramite il server MCP di Skillsail all’indirizzo https://skillsail.com/mcp.

Specifiche OpenAPI

GET https://skillsail.com/openapi.json Restituisce JSON OpenAPI 3.1. Comprende:

• GET /api/health — accessibilità del servizio
• GET /openapi.json — questo documento OpenAPI
• GET /.well-known/oauth-protected-resource/mcp — Metadati delle risorse protette da OAuth
• POST /mcp — trasporto MCP autenticato di Skillsail

Documenti correlati redatti da persone: risorse per sviluppatori Skillsail e istruzioni di autenticazione Skillsail.

Gestione delle versioni

Invia l’intestazione opzionale Skillsail-Api-Version: 1. Se l’intestazione viene omessa, Skillsail fornisce la versione v1. L’attuale info.version nel documento OpenAPI è 1.0.0.

L'endpoint MCP rimane /mcp. I client MCP devono leggere la versione del protocollo dalla scheda del server MCP di Skillsail anziché dal prefisso del percorso REST.

Non dare per scontato che l’URL /v2 sia definitivo finché Skillsail non ne pubblicherà uno in questo documento e su OpenAPI.

Errori API strutturati

Gli errori di discovery REST seguono lo standard RFC 9457 application/problem+json. GET /openapi.json utilizza questo modello quando la discovery non è disponibile. Ogni oggetto che indica un problema include:

• type — URI che identifica la classe del problema
• title — riassunto breve e chiaro
• status — Codice di stato HTTP
• detail — messaggio leggibile da una persona
• code — codice di errore Skillsail leggibile da macchina

Esempio:

{
  "type": "https://skillsail.com/docs/api#not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "This URL is not a Skillsail API resource.",
  "code": "not_found"
}

I metadati delle risorse protette da OAuth (/.well-known/oauth-protected-resource/mcp) utilizzano il formato JSON di OAuth, non problem+json. Un’interruzione della configurazione restituisce 503 application/json :

{
  "error": "temporarily_unavailable",
  "error_description": "OAuth metadata is temporarily unavailable"
}

I suffissi sconosciuti sul percorso /.well-known/oauth-protected-resource/mcp restituiscono 404 con un corpo text/plain contenente Not found.

Il trasporto HTTP MCP su POST /mcp:

• Intestazione Authorization assente: 401 con il corpo vuoto e WWW-Authenticate (resource_metadata, non error=). Analizza il JSON solo quando Content-Type è application/json.
• Token di portatore non valido o mal formato: 401 JSON { "error": "invalid_token", "error_description": "..." }
• Token valido senza autorizzazione: 403 JSON { "error": "insufficient_scope", "error_description": "..." }
• Interruzione del servizio di autenticazione: 503 JSON { "error": "temporarily_unavailable", "error_description": "..." } con Retry-After

Deprecazione

Quando un’operazione o una rappresentazione è deprecata, le risposte includono:

• Deprecation: @1688169599 — Campo strutturato "Date" (timestamp Unix) secondo RFC 9745. Non si tratta del valore booleano " true".
• Sunset con una data HTTP (RFC 8594)

Le modifiche che comportano incompatibilità vengono annunciate almeno 90 giorni prima della data di fine supporto. Le modifiche aggiuntive e retrocompatibili potrebbero essere incluse nella v1 senza una nuova versione. Dopo la fine del supporto, Skillsail potrebbe rimuovere la funzionalità.

Le risposte REST riuscite potrebbero riportare Skillsail-Api-Version: 1.

Correlati

• Risorse per gli sviluppatori di Skillsail
• Server MCP di Skillsail
• Documento OpenAPI