Skillsail API

The Skillsail API is version 1. The OpenAPI description is https://skillsail.com/openapi.json. Course authoring is not a REST resource collection: agents create and edit modules through the Skillsail MCP server at https://skillsail.com/mcp.

OpenAPI specification

GET https://skillsail.com/openapi.json returns OpenAPI 3.1 JSON. It covers:

• GET /api/health — service reachability
• GET /.well-known/oauth-protected-resource/mcp — OAuth protected-resource metadata
• POST /mcp — authenticated Skillsail MCP transport

Related human docs: Skillsail developer resources and Skillsail auth instructions.

Versioning

Send the optional request header Skillsail-Api-Version: 1. If the header is omitted, Skillsail serves v1. The current info.version in the OpenAPI document is 1.0.0.

The MCP endpoint stays at /mcp. MCP clients should read the protocol version from the Skillsail MCP server card rather than from a REST path prefix.

Do not assume a future /v2 URL until Skillsail publishes one in this document and in OpenAPI.

Typed errors

REST discovery errors use RFC 9457 application/problem+json. GET /openapi.json uses this model when discovery is unavailable. Every problem object includes:

• type — URI that identifies the problem class
• title — short, stable summary
• status — HTTP status code
• detail — human-readable message
• code — machine-readable Skillsail error code

Example:

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

OAuth protected-resource metadata (/.well-known/oauth-protected-resource/mcp) uses OAuth JSON, not problem+json. A configuration outage returns 503 application/json:

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

Unknown suffixes on that well-known route return 404 with a text/plain body Not found.

The MCP HTTP transport at POST /mcp:

• No Authorization header: 401 with an empty body and WWW-Authenticate (resource_metadata, no error=). Parse JSON only when Content-Type is application/json.
• Invalid or malformed bearer token: 401 JSON { "error": "invalid_token", "error_description": "..." }
• Valid token without permission: 403 JSON { "error": "insufficient_scope", "error_description": "..." }
• Auth service outage: 503 JSON { "error": "temporarily_unavailable", "error_description": "..." } with Retry-After

Deprecation

When an operation or representation is deprecated, responses include:

• Deprecation: @1688169599 — RFC 9745 structured-field Date (Unix timestamp). This is not the boolean true.
• Sunset with an HTTP-date (RFC 8594)

Breaking changes are announced at least 90 days before the Sunset date. Additive, backwards-compatible changes may ship in v1 without a new version. After Sunset, Skillsail may remove the operation.

Successful REST responses may echo Skillsail-Api-Version: 1.

Related

• Skillsail developer resources
• Skillsail MCP server
• OpenAPI document