# API de Skillsail

Descripción OpenAPI de Skillsail, errores tipados, versionado y política de deprecación para agentes y clientes HTTP.

La API de Skillsail es la versión **1**. La descripción OpenAPI está en [https://skillsail.com/openapi.json](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](/es/documentacion/mcp/asistentes-de-ia) 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](/es/documentacion/desarrolladores) e [instrucciones de autenticación de Skillsail](https://skillsail.com/auth.md).

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

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

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

```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](/es/documentacion/desarrolladores)
- [Servidor MCP de Skillsail](/es/documentacion/mcp/asistentes-de-ia)
- [Documento OpenAPI](https://skillsail.com/openapi.json)