# Skillsail API 문서

Skillsail API 문서: 에이전트 및 HTTP 클라이언트에 대한 OpenAPI 설명, 구조화된 API 오류, 버전 관리 및 사용 중단 정책.

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

## 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 개발자 리소스](/ko/docs/developers) 및 [Skillsail 인증 안내서](https://skillsail.com/auth.md).

## 버전 관리

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

MCP 엔드포인트는 `/mcp` 로 유지됩니다. MCP 클라이언트는 REST 경로 접두사가 아닌 [Skillsail MCP 서버 카드에서](https://skillsail.com/.well-known/mcp.json) 프로토콜 버전을 읽어야 합니다.

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

## 구조화된 API 오류

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

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

예시:

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

```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 개발자 리소스](/ko/docs/developers)
- [Skillsail MCP 서버](/ko/docs/mcp/overview)
- [OpenAPI 문서](https://skillsail.com/openapi.json)