Documentation de l'API Skillsail

Cette documentation relative à l’API Skillsail décrit la version 1. La description OpenAPI est disponible à l’adresse https://skillsail.com/openapi.json. La création de cours ne constitue pas un ensemble de ressources REST : les agents créent et modifient des modules via le serveur MCP de Skillsail à l’adresse https://skillsail.com/mcp.

Spécification OpenAPI

GET https://skillsail.com/openapi.json renvoie des données JSON au format OpenAPI 3.1. Il couvre :

• GET /api/health — accessibilité du service
• GET /openapi.json — ce document OpenAPI
• GET /.well-known/oauth-protected-resource/mcp — Métadonnées des ressources protégées par OAuth
• POST /mcp — transport MCP Skillsail authentifié

Documents connexes rédigés par des humains : ressources pour les développeurs Skillsail et instructions d’authentification Skillsail.

Gestion des versions

Envoyez l’en-tête de requête facultatif « Skillsail-Api-Version: 1 ». Si cet en-tête est omis, Skillsail fournit la version v1. La valeur actuelle de info.version dans le document OpenAPI est 1.0.0.

Le point de terminaison MCP reste accessible à l'adresse /mcp. Les clients MCP doivent lire la version du protocole à partir de la fiche du serveur MCP de Skillsail plutôt qu'à partir d'un préfixe de chemin REST.

Ne présumez pas d’une future URL /v2 tant que Skillsail n’en aura pas publié une dans ce document et dans OpenAPI.

Erreurs API structurées

Les erreurs de découverte REST suivent la norme RFC 9457 application/problem+json. L’URL GET /openapi.json utilise ce modèle lorsque la découverte n’est pas disponible. Chaque objet signalant un problème comprend :

• type — URI identifiant la classe de problèmes
• title — résumé court et stable
• status — Code d'état HTTP
• detail — message lisible par l’utilisateur
• code — Code d’erreur Skillsail lisible par machine

Exemple :

{
  "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"
}

Les métadonnées des ressources protégées par OAuth (/.well-known/oauth-protected-resource/mcp) utilisent le format JSON OAuth, et non « problem+json ». Une interruption de la configuration renvoie 503 application/json :

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

Les suffixes inconnus sur la route /.well-known/oauth-protected-resource/mcp renvoient 404 avec un corps text/plain contenant Not found.

Le transport HTTP MCP à l'adresse POST /mcp:

• Pas d’en-tête « Authorization » : 401 avec un corps vide et WWW-Authenticate (resource_metadata, sans error=). Analysez le JSON uniquement lorsque Content-Type est application/json.
• Jeton de porteur non valide ou mal formé : 401 JSON { "error": "invalid_token", "error_description": "..." }
• Jeton valide sans autorisation : 403 JSON { "error": "insufficient_scope", "error_description": "..." }
• Interruption du service d’authentification : 503 JSON { "error": "temporarily_unavailable", "error_description": "..." } avec Retry-After

Obsolescence

Lorsqu’une opération ou une représentation est obsolète, les réponses peuvent inclure :

• Deprecation: @1688169599 — Champ structuré « Date » (horodatage Unix) selon la RFC 9745. Il ne s’agit pas de la variable booléenne « true ».
• Sunset avec une date HTTP (RFC 8594)

Les modifications entraînant une rupture de compatibilité sont annoncées au moins 90 jours avant la date de fin de prise en charge. Les modifications additives et rétrocompatibles peuvent être intégrées à la version 1 sans qu'une nouvelle version ne soit publiée. Après la fin de prise en charge, Skillsail peut supprimer la fonctionnalité.

Les réponses REST réussies peuvent renvoyer Skillsail-Api-Version: 1.

Connexes

• Ressources pour les développeurs Skillsail
• Serveur MCP Skillsail
• Document OpenAPI