> 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/get-started/ko/platform/workspaces/list-workspaces-and-projects.md).
# 워크스페이스 및 프로젝트 목록
## 소개
워크스페이스 엔드포인트는 워크스페이스와 그 안의 모든 프로젝트에 대한 메타데이터를 반환합니다. 여기에는 각 프로젝트의 유형, 이미지 및 주석 수, 버전, 데이터셋 분할이 포함됩니다. API 키로 접근할 수 있는 프로젝트를 열거할 때(예: 데이터를 업로드하거나 버전을 내보내기 전에 프로젝트 ID를 찾는 용도)와 프로젝트에서 생성된 버전, 학습된 모델, 데이터셋 내보내기를 자세히 살필 때 사용하세요. 동일한 데이터는 REST API, Python SDK, CLI를 통해서도 사용할 수 있습니다.
## HTTP API
다음 `/:workspace` 엔드포인트는 워크스페이스와 그 안의 프로젝트에 대한 정보를 제공합니다. 이 엔드포인트는 API 키가 인증하는 워크스페이스의 모든 프로젝트를 나열하며, 각 프로젝트로 더 깊이 들어가 생성된 버전, 모델, 데이터셋 내보내기 정보를 확인할 수 있습니다.
엔드포인트 URL은 다음과 같습니다:
```url
curl "https://api.roboflow.com/roboflow?api_key=$ROBOFLOW_API_KEY"
```
다음은 이 엔드포인트의 응답 예시입니다:
{
"workspace": {
"name": "Roboflow",
"url": "roboflow",
"members": 7,
"projects": [
{
"id": "roboflow/chess-sample-4ckfl",
"type": "object-detection",
"name": "Chess Sample",
"created": 1630335544.592,
"updated": 1630335741.988,
"images": 12,
"unannotated": 3,
"annotation": "pieces",
"versions": 3,
"public": false,
"splits": {
"train": 9,
"test": 1,
"valid": 2
},
"classes": {
"white-queen": 7,
"black-queen": 4,
"black-bishop": 8,
"white-knight": 10,
"white-bishop": 11,
"black-knight": 11,
"black-rook": 10,
"white-pawn": 34,
"black-pawn": 37,
"white-rook": 10,
"black-king": 8,
"white-king": 8
}
}
]
}
}
### 프로젝트 가져오기 및 버전 나열
다음 REST 엔드포인트를 사용하여 프로젝트에 대한 정보를 가져올 수 있습니다:
```bash
curl "https://api.roboflow.com/roboflow/chess-sample-4ckfl?api_key=$ROBOFLOW_API_KEY"
```
이 엔드포인트는 다음 구조의 JSON 응답을 반환합니다:
```bash
{
"workspace": {
"name": "Roboflow",
"url": "roboflow",
"members": 7
},
"project": {
"id": "roboflow/chess-sample-4ckfl",
"type": "object-detection",
"name": "Chess Sample",
"created": 1630335544.592,
"updated": 1630335741.988,
"images": 12,
"unannotated": 3,
"annotation": "pieces",
"public": false,
"splits": {
"valid": 2,
"train": 9,
"test": 1
},
"classes": {
"white-queen": 7,
"white-king": 8,
"black-knight": 11,
"black-pawn": 37,
"black-rook": 10,
"white-pawn": 34,
"black-bishop": 8,
"white-knight": 10,
"black-queen": 4,
"white-bishop": 11,
"black-king": 8,
"white-rook": 10
},
"versions": [
{
"id": "roboflow/chess-sample-4ckfl/3",
"name": "raw",
"created": 1630335741.989,
"images": 12,
"splits": {
"train": 9,
"test": 1,
"valid": 2
},
"preprocessing": {
"auto-orient": {
"enabled": true
}
},
"augmentation": {},
"exports": [
"coco",
"voc"
]
},
{
"id": "roboflow/chess-sample-4ckfl/2",
"name": "416x416",
"created": 1630335730.142,
"images": 12,
"splits": {
"train": 9,
"test": 1,
"valid": 2
},
"preprocessing": {
"resize": {
"enabled": true,
"format": "Stretch to",
"width": 416,
"height": 416
},
"auto-orient": {
"enabled": true
}
},
"augmentation": {},
"exports": []
},
{
"id": "roboflow/chess-sample-4ckfl/1",
"name": "augmented",
"created": 1630335698.746,
"images": 30,
"splits": {
"valid": 2,
"train": 27,
"test": 1
},
"model": {
"id": "chess-sample-4ckfl/1",
"endpoint": "https://serverless.roboflow.com/infer/chess-sample-4ckfl/1",
"start": 1630335799.682,
"end": 1630337523.889,
"fromScratch": false,
"tfjs": true,
"oak": true,
"map": "62.87",
"recall": "85.29",
"precision": "23.44"
},
"preprocessing": {
"resize": {
"enabled": true,
"width": 416,
"format": "Stretch to",
"height": 416
},
"auto-orient": {
"enabled": true
},
"grayscale": {
"enabled": true
}
},
"augmentation": {
"exposure": {
"percent": "25",
"enabled": true
},
"brightness": {
"percent": "25",
"enabled": true,
"darken": true,
"brighten": true
},
"rotate": {
"degrees": "5",
"enabled": true
},
"image": {
"enabled": true,
"versions": "3"
},
"flip": {
"enabled": true,
"horizontal": true,
"vertical": false
},
"crop": {
"min": 0,
"percent": 30,
"enabled": true
},
"noise": {
"percent": "2",
"enabled": true
}
},
"exports": [
"yolov5pytorch"
],
"versionNotes": "수정: 회전된 박스 정렬 불일치"
}
]
}
}
```
### 프로젝트 모델 나열
다음 `/:workspace/:project/models` 엔드포인트를 사용하면 프로젝트에서 학습된 모든 모델을 가져올 수 있습니다. 여기에는 버전으로 학습된 모델과 독립형 모델(예: NAS 하위 모델)도 포함됩니다.
사용 시 [Roboflow로 로그인(시작하기)](https://docs.roboflow.com/reference/authentication/authentication/sign-in-with-roboflow-getting-started), 사용 `Authorization: Bearer` 및 스코프 `model:infer` 대신 `api_key`:
```bash
curl -H "Authorization: Bearer $ACCESS_TOKEN" \\
"https://api.roboflow.com/:workspace/:project/models"
```
#### 모든 모델 나열
```bash
curl "https://api.roboflow.com/:workspace/:project/models?api_key=$ROBOFLOW_API_KEY"
```
**NAS 그룹으로 필터링**
특정 NAS 실행의 모델만 나열하려면 `group` 쿼리 매개변수를 전달하세요:
```bash
curl "https://api.roboflow.com/:workspace/:project/models?group=GROUP_ID&api_key=$ROBOFLOW_API_KEY"
```
다음 `group` 값은 각 모델 객체에 반환되는 NAS 실행 식별자입니다. 그룹이 어떤 모델과도 일치하지 않으면 엔드포인트는 빈 배열을 반환합니다.
#### 응답
이 엔드포인트는 모델 객체의 JSON 배열을 반환합니다:
```json
[
{
"url": "my-workspace/my-project/3",
"version": "3",
"train": { "status": "finished" },
"modelType": "rfdetr-base",
"name": "My Model",
"created": "2026-04-01T00:00:00.000Z",
"metrics": {
"map50": 91.0,
"precision": 88.0,
"recall": 85.0
}
}
]
```
**NAS 모델 필드**
다음이 생성한 모델 [신경 아키텍처 탐색](https://docs.roboflow.com/models/train/neural-architecture-search) 에는 추가 필드가 포함됩니다:
```json
{
"url": "my-workspace/my-project-410-nas-gpu-066866",
"train": { "status": "finished" },
"modelType": "rfdetr-nas-S",
"name": "NAS Child 1",
"created": "2026-04-01T00:00:00.000Z",
"nasFamily": "child",
"group": "pVYKOWUB6AUIVJMgPc7u-410-rfdetrNasGroup",
"favorites": {},
"recommended": true,
"metrics": {
"map50": 81.2,
"map5095": 64.3,
"f1": 78.0,
"hardware": "gpu",
"latency": 1.157,
"paretoOptimalFor": ["gpu"]
}
}
```
| 필드 | 유형 | 설명 |
| -------------------------- | ------ | --------------------------------------------------- |
| `nasFamily` | 문자열 | `"child"` NAS에서 발견된 모델의 경우, `null` 기준 모델의 경우 |
| `group` | 문자열 | 같은 실행의 모든 모델이 공유하는 NAS 실행 식별자 |
| `favorites` | 객체 | 사용자 ID와 즐겨찾기 상태의 매핑 |
| `recommended` | 불리언 | 존재하며 `true` 이 모델이 하나 이상의 메트릭/하드웨어 조합에서 추천 선택일 때 |
| `metrics.map5095` | 숫자 | mAP\@50-95 점수(백분율) |
| `metrics.f1` | 숫자 | F1 점수(백분율) |
| `metrics.hardware` | 문자열 | 모델이 벤치마크된 하드웨어 대상(예: `"gpu"`, `"jetson-orin-nano"`) |
| `metrics.latency` | 숫자 | 대상 하드웨어에서의 추론 지연 시간(밀리초) |
| `metrics.paretoOptimalFor` | 문자열\[] | 이 모델이 파레토 프런티어에 있는 하드웨어 대상 |
이 필드는 NAS 모델에만 존재합니다. 일반 학습 모델에는 영향을 주지 않습니다.
## Python SDK
가져오세요 `워크스페이스` API 키가 인증하는 워크스페이스의 핸들:
```python
import roboflow
rf = roboflow.Roboflow(api_key="YOUR_API_KEY")
workspace = rf.workspace()
```
각 Roboflow API 키는 단일 워크스페이스에 범위가 지정됩니다. 다른 워크스페이스를 사용하려면 다른 API 키를 사용하거나, 공개 Universe 워크스페이스의 경우 워크스페이스 슬러그를 전달하세요:
```python
# 공개 Universe 워크스페이스 - API 키만 필요합니다.
public_ws = rf.workspace("roboflow-100")
```
### 워크스페이스 속성
반환된 `워크스페이스` 다음을 노출합니다:
* `workspace.url` - 워크스페이스의 URL 슬러그(예: `my-workspace`).
* `workspace.name` - 워크스페이스의 표시 이름.
* `workspace.list_projects()` - 워크스페이스의 프로젝트들, dict 목록으로.
* `workspace.projects()` - `list_projects()` 와 동일한 데이터지만 `Project` 객체 목록으로 반환됩니다(이전 별칭).
* `workspace.list_folders()` - [폴더 관리](https://docs.roboflow.com/datasets/manage/project-folders#python-sdk).
* `workspace.list_workflows()` - [워크플로 관리](https://docs.roboflow.com/workflows/manage/manage-workflows#python-sdk).
* `workspace.get_plan()` 및 `workspace.get_usage()` - [워크스페이스 요금제 및 사용량](/get-started/ko/platform/billing-and-plans/credits/view-credit-usage.md#python-sdk).
### 프로젝트와 버전 나열
#### 프로젝트 나열
워크스페이스의 프로젝트를 가져오세요:
```python
import roboflow
rf = roboflow.Roboflow(api_key="YOUR_API_KEY")
workspace = rf.workspace()
for project in workspace.list_projects():
print(project["id"], project["name"], project["type"])
```
각 항목에는 프로젝트의 id(URL 슬러그), 표시 이름, 프로젝트 유형, 이미지 수, 그리고 몇 가지 다른 메타데이터 필드가 포함됩니다.
공개 Universe 워크스페이스에 대해 작업하려면 슬러그를 전달하세요:
```python
universe_ws = rf.workspace("roboflow-100")
```
#### 프로젝트 가져오기
```python
project = workspace.project("my-detector")
```
또는 최상위 단축형을 사용하세요:
```python
project = rf.project("my-detector")
```
#### 버전 나열
```python
for version in project.versions():
print(version.version, version.name)
```
`project.versions()` 는 `Version` 객체를 반환하며, 이 객체에 직접 메서드를 호출할 수 있습니다(`download`, `train`, `delete`등). 가벼운 dict 응답이 필요하면 `project.list_versions()` 또는 `project.get_version_information()`.
#### 버전 가져오기
```python
version = project.version(3)
```
숫자 - 버전은 1부터 시작합니다.
## CLI
### 워크스페이스 나열
CLI를 사용하면 구성원인 모든 워크스페이스 목록을 가져올 수 있습니다.
CLI로 워크스페이스를 나열하려면 다음 명령을 사용하세요:
roboflow workspace list
그러면 해당 애플리케이션 링크와 워크스페이스 ID가 포함된 워크스페이스 목록이 반환됩니다:
```
이름 ID 기본
내 워크스페이스 my-workspace *
다른 워크스페이스 other-ws
```
출력을 JSON으로 가져오려면(스크립트나 AI 에이전트에서 사용):
```bash
roboflow workspace list --json
```
```json
[
{"name": "My Workspace", "url": "my-workspace", "link": "https://app.roboflow.com/my-workspace", "default": true},
{"name": "Other Workspace", "url": "other-ws", "link": "https://app.roboflow.com/other-ws", "default": false}
]
```
### 워크스페이스의 프로젝트 나열
워크스페이스의 프로젝트를 나열하려면 다음 명령을 사용하세요:
```bash
roboflow project list
```
기본 워크스페이스가 구성되어 있으면 `-w` 플래그는 선택 사항입니다. 그렇지 않으면 지정하세요:
```bash
roboflow project list -w WORKSPACE_ID
```
그러면 프로젝트 표가 반환됩니다:
```
이름 ID 유형 버전 수 이미지 수
my-dataset my-workspace/my-dataset object-detection 3 500
classifier my-workspace/classifier classification 1 200
```
출력을 JSON으로 가져오려면:
```bash
roboflow project list --json
```
### 프로젝트 가져오기
프로젝트에 대한 자세한 정보를 가져오려면 다음 명령을 사용하세요:
```bash
roboflow project get PROJECT_ID
```
리소스 축약형을 사용할 수 있습니다. 워크스페이스를 별도로 지정할 필요가 없습니다:
```bash
roboflow project get my-dataset # 기본 워크스페이스 사용
roboflow project get my-workspace/my-dataset # 워크스페이스 명시
```
그러면 버전을 포함한 프로젝트 정보가 반환됩니다:
```
프로젝트: my-dataset
ID: my-workspace/my-dataset
유형: object-detection
이미지 수: 500
버전 수: 3
클래스: car (200), truck (150), bus (150)
링크: https://app.roboflow.com/my-workspace/my-dataset
```
전체 JSON 응답을 가져오려면:
```bash
roboflow project get my-dataset --json
```
## MCP 서버
AI 에이전트를 다음에 연결하고 [MCP 서버](/get-started/ko/agents/mcp-server.md) 이 도구들로 워크스페이스의 내용을 나열할 수 있습니다:
| 도구 | 설명 |
|---|
projects_list | 작업 공간의 프로젝트 목록을 나열합니다. |
projects_get | 버전, 클래스, 분할 및 학습된 모델을 포함한 프로젝트 세부 정보를 가져옵니다. |