API de Skillsail

La API de Skillsail es la versión 1. La descripción OpenAPI está en https://skillsail.com/openapi.json. La creación de cursos no es una colección de recursos REST: los agentes crean y editan módulos a través del servidor MCP de Skillsail en https://skillsail.com/mcp.

Especificación OpenAPI

GET https://skillsail.com/openapi.json devuelve JSON de OpenAPI 3.1. Cubre:

• GET /api/health — disponibilidad del servicio
• GET /.well-known/oauth-protected-resource/mcp — metadatos de recurso protegido OAuth
• POST /mcp — transporte MCP autenticado de Skillsail

Documentación relacionada: recursos para desarrolladores de Skillsail e instrucciones de autenticación de Skillsail.

Versionado

Envíe la cabecera de petición opcional Skillsail-Api-Version: 1. Si se omite, Skillsail sirve v1. La info.version actual del documento OpenAPI es 1.0.0.

El endpoint MCP permanece en /mcp. Los clientes MCP deben leer la versión del protocolo en la tarjeta del servidor MCP de Skillsail, no en un prefijo de ruta REST.

No dé por sentada una futura URL /v2 hasta que Skillsail la publique en este documento y en OpenAPI.

Errores tipados

Los errores REST de descubrimiento usan RFC 9457 application/problem+json. GET /openapi.json usa este modelo cuando el descubrimiento no está disponible. Cada objeto de problema incluye:

• type — URI que identifica la clase de problema
• title — resumen corto y estable
• status — código de estado HTTP
• detail — mensaje legible por personas
• code — código de error de Skillsail legible por máquina

Ejemplo:

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

Los metadatos de recurso protegido OAuth (/.well-known/oauth-protected-resource/mcp) usan JSON de OAuth, no problem+json. Un fallo de configuración devuelve 503 application/json:

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

Los sufijos desconocidos en esa ruta well-known devuelven 404 con cuerpo text/plain Not found.

El transporte HTTP de MCP en POST /mcp:

• Sin cabecera Authorization: 401 con cuerpo vacío y WWW-Authenticate (resource_metadata, sin error=). Analice JSON solo cuando Content-Type sea application/json.
• Token bearer inválido o malformado: 401 JSON { "error": "invalid_token", "error_description": "..." }
• Token válido sin permiso: 403 JSON { "error": "insufficient_scope", "error_description": "..." }
• Indisponibilidad del servicio de autenticación: 503 JSON { "error": "temporarily_unavailable", "error_description": "..." } con Retry-After

Deprecación

Cuando se depreca una operación o representación, las respuestas incluyen:

• Deprecation: @1688169599 — fecha RFC 9745 (marca de tiempo Unix). No es el booleano true.
• Sunset con una fecha HTTP (RFC 8594)

Los cambios incompatibles se anuncian al menos 90 días antes de la fecha Sunset. Los cambios aditivos y compatibles hacia atrás pueden llegar en v1 sin un número de versión nuevo. Después de Sunset, Skillsail puede eliminar la operación.

Las respuestas REST correctas pueden devolver Skillsail-Api-Version: 1.

Relacionado

• Recursos para desarrolladores de Skillsail
• Servidor MCP de Skillsail
• Documento OpenAPI