# Documentação da API do Skillsail

Documentação da API do Skillsail: descrição da OpenAPI, erros estruturados de API, controle de versões e política de descontinuação para agentes e clientes HTTP.

Esses documentos da API do Skillsail descrevem a versão **1**. A descrição da OpenAPI está [em https://skillsail.com/openapi.json](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](/pt/documentacao/mcp/visao-geral) 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](/pt/documentacao/desenvolvedores) e [instruções de autenticação do Skillsail](https://skillsail.com/auth.md).

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

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

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` :

```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](/pt/documentacao/desenvolvedores)
- [Servidor MCP do Skillsail](/pt/documentacao/mcp/visao-geral)
- [Documento da OpenAPI](https://skillsail.com/openapi.json)