Skillsail API 문서

이 Skillsail API 문서는 버전 1을 설명합니다. OpenAPI 설명은 https://skillsail.com/openapi.json에서 확인할 수 있습니다. 과정 제작은 REST 리소스 모음이 아닙니다. 에이전트는 https://skillsail.com/mcp 의 Skillsail MCP 서버를 통해 모듈을 생성하고 편집합니다.

OpenAPI 사양

GET https://skillsail.com/openapi.json OpenAPI 3.1 JSON을 반환합니다. 다음을 포함합니다:

• GET /api/health — 서비스 가용성
• GET /openapi.json — 이 OpenAPI 문서
• GET /.well-known/oauth-protected-resource/mcp — OAuth 보호 리소스 메타데이터
• POST /mcp — 인증된 Skillsail MCP 전송

관련 사용자 문서: Skillsail 개발자 리소스 및 Skillsail 인증 안내서.

버전 관리

선택 사항인 요청 헤더 Skillsail-Api-Version: 1 를 전송하십시오. 헤더가 생략된 경우, Skillsail은 v1을 제공합니다. OpenAPI 문서의 현재 info.version 는 1.0.0 입니다.

MCP 엔드포인트는 /mcp 로 유지됩니다. MCP 클라이언트는 REST 경로 접두사가 아닌 Skillsail MCP 서버 카드에서 프로토콜 버전을 읽어야 합니다.

Skillsail이 본 문서와 OpenAPI에 URL을 공개하기 전까지는 /v2 URL이 적용된다고 가정하지 마십시오.

구조화된 API 오류

REST 검색 오류는 RFC 9457 application/problem+json 을 따릅니다. GET /openapi.json 은 검색이 불가능할 때 이 모델을 사용합니다. 모든 문제 객체에는 다음이 포함됩니다:

• type — 문제 클래스를 식별하는 URI
• title — 간결하고 일관된 요약
• status — HTTP 상태 코드
• detail — 사람이 읽기 쉬운 메시지
• code — 기계가 읽을 수 있는 Skillsail 오류 코드

예시:

{
  "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 보호 리소스 메타데이터(/.well-known/oauth-protected-resource/mcp)는 problem+json이 아닌 OAuth JSON을 사용합니다. 구성 오류가 발생하면 503 application/json 와 같은 오류 메시지가 반환됩니다:

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

/.well-known/oauth-protected-resource/mcp 경로에 알 수 없는 접미사가 붙으면 404 상태 코드와 Not found가 담긴 text/plain 본문을 반환합니다.

POST /mcp 의 MCP HTTP 전송:

• Authorization 헤더가 없는 경우: 본문이 비어 있는 401 및 WWW-Authenticate (resource_metadata, error= 제외). Content-Type 이 application/json 일 때만 JSON을 파싱하십시오.
• 유효하지 않거나 형식이 잘못된 베어러 토큰: 401 JSON { "error": "invalid_token", "error_description": "..." }
• 권한이 없는 유효한 토큰: 403 JSON { "error": "insufficient_scope", "error_description": "..." }
• 인증 서비스 중단: 503 JSON { "error": "temporarily_unavailable", "error_description": "..." } with Retry-After

사용 중단

특정 기능이나 표현 방식이 더 이상 권장되지 않을 경우, 응답에는 다음 내용이 포함됩니다:

• Deprecation: @1688169599 — RFC 9745 구조화된 필드 Date(유닉스 타임스탬프). 이는 부울 값인 true 와는 다릅니다.
• Sunset HTTP 날짜 형식(RFC 8594)을 사용하여

중대한 변경 사항은 지원 종료일 최소 90일 전에 공지됩니다. 추가적이며 하위 호환성이 보장되는 변경 사항은 새로운 버전 번호 없이 v1에 포함될 수 있습니다. 지원 종료 후, Skillsail은 해당 기능을 제거할 수 있습니다.

성공적인 REST 응답은 Skillsail-Api-Version: 1 와 유사할 수 있습니다.

관련 항목

• Skillsail 개발자 리소스
• Skillsail MCP 서버
• OpenAPI 문서