> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/reference/ko/platform/rest-api.md).

# REST API

Roboflow REST API는 플랫폼의 공식 인터페이스입니다. 모든 기능은 여기에서 먼저 제공되며, [Python SDK](/reference/ko/platform/python-sdk.md) 및 [CLI](/reference/ko/platform/cli.md) 는 모두 내부적으로 이를 호출합니다. Python 패키지를 설치할 수 없는 환경에서 작업하거나, 웹훅이나 브라우저에서 호출하거나, Python이 아닌 통합을 구축할 때는 REST API를 직접 사용하세요.

알아두어야 할 기본 호스트는 두 가지입니다:

| 호스트                               | 용도                                                                                                                                      |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `https://api.roboflow.com`        | 관리 - 워크스페이스, 프로젝트, 버전, 학습, 워크플로우, 데이터셋, 비전 이벤트, 휴지통.                                                                                    |
| `https://serverless.roboflow.com` | 호스팅 추론 - 학습된 모델 또는 워크플로우를 이미지나 비디오에 적용. 참조: [이미지에서 모델 실행](https://docs.roboflow.com/deployment/roboflow-cloud/serverless-api#http-api). |

[전용 배포](https://docs.roboflow.com/deployment/roboflow-cloud/dedicated-deployments#http-api) 는 세 번째 호스트에서 관리됩니다 (`https://roboflow.cloud`).

## 리소스 계층 구조

Roboflow 데이터 모델은 계층 구조이며 API URL도 이 계층 구조를 따릅니다:

* `/:workspace` - 워크스페이스의 프로젝트 목록과 워크스페이스 메타데이터.
* `/:workspace/:project` - 프로젝트의 메타데이터와 버전 목록.
* `/:workspace/:project/:version` - 특정 데이터셋 버전, 해당 모델(학습된 경우), 다운로드 URL.
* `/:workspace/:project/:version/:format` - 특정 [내보내기 형식](https://roboflow.com/formats).
* `/:workspace/workflows/:workflow` - 참조: [워크플로우 관리](https://docs.roboflow.com/workflows/manage/manage-workflows#http-api).
* `/:workspace/groups` - 프로젝트 폴더. 참조: [프로젝트 폴더 관리](https://docs.roboflow.com/datasets/manage/project-folders#http-api).
* `/:workspace/trash` - 소프트 삭제된 프로젝트, 버전, 워크플로우. 참조: [휴지통 관리](https://docs.roboflow.com/platform/workspaces/trash#http-api).

## 루트 엔드포인트

최상위 수준에서(`https://api.roboflow.com/`)에서 `api_key` 가 작동하는지 확인할 수 있습니다. 응답에는 해당 키가 속한 워크스페이스가 표시됩니다:

```bash
curl -H "Authorization: Bearer $ROBOFLOW_API_KEY" "https://api.roboflow.com/"
```

```json
{
  "welcome": "Roboflow API에 오신 것을 환영합니다.",
  "instructions": "성공적으로 인증되었습니다.",
  "docs": "https://docs.roboflow.com",
  "workspace": "my-workspace"
}
```

그다음에는 [워크스페이스 및 프로젝트 목록](https://docs.roboflow.com/platform/workspaces/list-workspaces-and-projects#http-api) 으로 들어가 워크스페이스에 무엇이 있는지 확인하세요.

## 인증 및 스코프

API 키는 워크스페이스 범위로 적용됩니다. 키는 `Authorization: Bearer ...` 헤더로 전송하세요. 쿼리 매개변수(`?api_key=...`)로 전달하거나 `POST` 요청 본문에 넣는 방식은 기존 채널입니다. 여전히 작동하지만 키가 URL과 로그에 남으므로 새 코드에는 권장되지 않습니다. 참조: [REST API로 인증](/reference/ko/platform/rest-api/authenticate-with-the-rest-api.md) 에서 자세한 내용을 확인하고 [스코프 API 키](/reference/ko/authentication/authentication/scoped-api-keys.md) 에서 리소스별 스코프 참고 정보를 확인하세요.

## 오류

API는 표준 HTTP 상태 코드와 JSON 오류 본문을 사용합니다. 참조: [오류 및 상태 코드](/reference/ko/errors-and-status-codes.md) 에서 도구 간 오류 참조를 확인하세요.