Documentação da API do Skillsail

Esses documentos da API do Skillsail descrevem a versão 1. A descrição da OpenAPI está em https://skillsail.com/openapi.json. A criação de cursos não é uma coleção de recursos REST: os agentes criam e editam módulos por meio do servidor MCP do Skillsail em https://skillsail.com/mcp.

Especificação OpenAPI

GET https://skillsail.com/openapi.json retorna JSON da OpenAPI 3.1. Abrange:

• GET /api/health — acessibilidade do serviço
• GET /openapi.json — este documento da OpenAPI
• GET /.well-known/oauth-protected-resource/mcp — Metadados de recursos protegidos por OAuth
• POST /mcp — transporte MCP autenticado da Skillsail

Documentos relacionados: recursos para desenvolvedores do Skillsail e instruções de autenticação do Skillsail.

Controle de versões

Envie o cabeçalho opcional da solicitação Skillsail-Api-Version: 1. Se o cabeçalho for omitido, o Skillsail fornece a v1. O info.version atual no documento da OpenAPI é 1.0.0.

O endpoint do MCP continua sendo /mcp. Os clientes do MCP devem ler a versão do protocolo no cartão do servidor MCP do Skillsail, em vez de usar um prefixo de caminho REST.

Não presuma que a URL /v2 será válida até que a Skillsail a publique neste documento e na OpenAPI.

Erros estruturados de API

Erros de descoberta REST seguem a RFC 9457 application/problem+json. O GET /openapi.json usa esse modelo quando a descoberta não está disponível. Cada objeto de problema inclui:

• type — URI que identifica a classe do problema
• title — resumo curto e consistente
• status — Código de status HTTP
• detail — mensagem legível por humanos
• code — código de erro do Skillsail legível por máquina

Exemplo:

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

Os metadados de recursos protegidos pelo OAuth (/.well-known/oauth-protected-resource/mcp) usam JSON do OAuth, não problem+json. Uma falha na configuração retorna 503 application/json :

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

Sufixos desconhecidos na rota /.well-known/oauth-protected-resource/mcp retornam 404 com um corpo text/plain contendo Not found.

O transporte HTTP do MCP em POST /mcp:

• Sem cabeçalho “ Authorization ”: 401 com corpo vazio e WWW-Authenticate (resource_metadata, sem error=). Analise o JSON somente quando Content-Type for application/json.
• Token de portador inválido ou com formato incorreto: 401 JSON { "error": "invalid_token", "error_description": "..." }
• Token válido sem permissão: 403 JSON { "error": "insufficient_scope", "error_description": "..." }
• Interrupção do serviço de autenticação: 503 JSON { "error": "temporarily_unavailable", "error_description": "..." } com Retry-After

Descontinuação

Quando uma operação ou representação for descontinuada, as respostas devem incluir:

• Deprecation: @1688169599 — Campo estruturado “Date” (timestamp Unix) da RFC 9745. Isso não é o valor booleano “ true ”.
• Sunset com uma data HTTP (RFC 8594)

Alterações significativas são anunciadas com pelo menos 90 dias de antecedência da data de descontinuação. Alterações adicionais e compatíveis com versões anteriores podem ser lançadas na v1 sem uma nova versão. Após a descontinuação, Skillsail pode remover o recurso.

Respostas REST bem-sucedidas podem retornar Skillsail-Api-Version: 1.

Relacionado

• Recursos para desenvolvedores do Skillsail
• Servidor MCP do Skillsail
• Documento da OpenAPI