# Skillsail API

Skillsail OpenAPI description, typed errors, versioning, and deprecation policy for agents and HTTP clients.

The Skillsail API is version **1**. The OpenAPI description is [https://skillsail.com/openapi.json](https://skillsail.com/openapi.json). Course authoring is not a REST resource collection: agents create and edit modules through the [Skillsail MCP server](/docs/mcp/overview) 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](/docs/developers) and [Skillsail auth instructions](https://skillsail.com/auth.md).

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

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

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

```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](/docs/developers)
- [Skillsail MCP server](/docs/mcp/overview)
- [OpenAPI document](https://skillsail.com/openapi.json)