> 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 "https://api.roboflow.com/?api_key=$ROBOFLOW_API_KEY"
```

```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 키는 워크스페이스 범위입니다. 키를 쿼리 매개변수(`?api_key=...`)로 전달하거나, `POST` 요청의 본문에 넣거나, `Authorization: Bearer ...` 헤더로 전달하세요. 참조 [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) 에서 도구 간 오류 참고를 확인하세요.