# Documentation de l'API Skillsail

Documentation de l’API Skillsail : description OpenAPI, erreurs API structurées, gestion des versions et politique de dépréciation pour les agents et les clients HTTP.

Cette documentation relative à l’API Skillsail décrit la version **1**. La description OpenAPI est disponible à l’adresse [https://skillsail.com/openapi.json](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](/fr/documentation/mcp/presentation) à 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](/fr/documentation/developpeurs) et [instructions d’authentification Skillsail](https://skillsail.com/auth.md).

## 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](https://skillsail.com/.well-known/mcp.json) 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 :

```json
{
  "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` :

```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](/fr/documentation/developpeurs)
- [Serveur MCP Skillsail](/fr/documentation/mcp/presentation)
- [Document OpenAPI](https://skillsail.com/openapi.json)