> 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": "체스 샘플",
"created": 1630335544.592,
"updated": 1630335741.988,
"images": 12,
"unannotated": 3,
"annotation": "pieces",
"versions": 3,
"public": false,
"splits": {
"train": 9,
"test": 1,
"valid": 2
},
"classes": {
"백색 퀸": 7,
"흑색 퀸": 4,
"흑색 비숍": 8,
"백색 나이트": 10,
"백색 비숍": 11,
"흑색 나이트": 11,
"흑색 룩": 10,
"백색 폰": 34,
"흑색 폰": 37,
"백색 룩": 10,
"흑색 킹": 8,
"백색 킹": 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": "체스 샘플",
"created": 1630335544.592,
"updated": 1630335741.988,
"images": 12,
"unannotated": 3,
"annotation": "pieces",
"public": false,
"splits": {
"valid": 2,
"train": 9,
"test": 1
},
"classes": {
"백색 퀸": 7,
"백색 킹": 8,
"흑색 나이트": 11,
"흑색 폰": 37,
"흑색 룩": 10,
"백색 폰": 34,
"흑색 비숍": 8,
"백색 나이트": 10,
"흑색 퀸": 4,
"백색 비숍": 11,
"흑색 킹": 8,
"백색 룩": 10
},
"versions": [
{
"id": "roboflow/chess-sample-4ckfl/3",
"name": "원본",
"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": "증강",
"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` 및 scope `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 실행 식별자입니다. group이 어떤 모델과도 일치하지 않으면 엔드포인트는 빈 배열을 반환합니다.
#### 응답
이 엔드포인트는 모델 객체의 JSON 배열을 반환합니다:
```json
[
{
"url": "my-workspace/my-project/3",
"version": "3",
"train": { "status": "finished" },
"modelType": "rfdetr-base",
"name": "내 모델",
"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 자식 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 실행 식별자 |
| `즐겨찾기` | 객체 | 사용자 ID와 즐겨찾기 상태의 매핑 |
| `권장됨` | 불리언 | 존재하며 `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()와 같은 데이터이지만 `list_projects()` 다음으로 반환됩니다: `프로젝트` 객체 목록(기존 별칭).
* `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()` 반환합니다 `버전` 메서드를 직접 호출할 수 있는 객체(`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": "내 워크스페이스", "url": "my-workspace", "link": "https://app.roboflow.com/my-workspace", "default": true},
{"name": "다른 워크스페이스", "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 객체 탐지 3 500
classifier my-workspace/classifier 분류 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
```