> ## Documentation Index > Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt > Use this file to discover all available pages before exploring further. # API 개요 > CoreWeave Sandboxes control plane API의 기본 URL, 인증, 버전 관리, 페이지 매김 및 오류 처리. control plane은 러너와 각 러너에 적용되는 정책을 관리하는 REST API를 제공합니다. 이 페이지에서는 모든 엔드포인트에 공통으로 적용되는 behavior(인증, 버전 관리, 오류 형식, 페이지 매김)를 설명합니다. 정책의 모든 필드에 대한 스키마는 [정책 레퍼런스](/ko/products/sandboxes/reference/profile)를 참조하세요. 이러한 엔드포인트를 사용하는 작업 중심의 워크스루는 [샌드박스 정책 설정하기](/ko/products/sandboxes/profiles/configure) 및 [러너 배포 및 관리하기](/ko/products/sandboxes/operations/managed-runners)를 참조하세요.

기본 URL 및 버전 관리

```text theme={"system"} https://api.coreweave.com/v1/sandbox ``` 이것은 control plane base URL입니다. 이 URL은 이 페이지에서 설명하는 러너 엔드포인트를 호스팅하며, 이를 통해 러너를 배포하고, 각 러너에 적용할 정책을 설정하고, 상태를 쿼리할 수 있습니다. 이는 [cwsandbox Python client](/ko/products/sandboxes/client)가 샌드박스를 시작하고 명령어와 출력을 스트림하는 데 사용하는 샌드박스 data plane(`Sandbox.run()`, `sb.exec()`, 파일 오퍼레이션)과는 별개입니다. control plane 오퍼레이션은 샌드박스를 생성하는 인프라를 만들고 설정하며, data plane 오퍼레이션은 실행 중인 샌드박스와 상호 작용합니다. API 버전은 `v1`입니다. 하위 호환성을 유지하는 추가 변경 사항은 `v1` 내에서 제공됩니다. 호환성이 깨지는 변경 사항은 새 버전 접두사로 제공되며, CoreWeave는 릴리스 전에 이를 미리 공지합니다. 이전 `v1beta2` API도 여전히 사용 가능하며, 프로필 템플릿과 프로필 바인딩은 이 API에서 제공됩니다. 이 기능들은 정책으로 대체되었으며 `v1`에는 추가되지 않습니다. 새 인테그레이션은 `v1`을 기준으로 구현하세요.

인증

모든 요청은 TLS를 통한 Bearer 토큰 인증을 사용합니다. `[API-ACCESS-TOKEN]`을 CoreWeave API 액세스 토큰으로 바꾸세요. ```text theme={"system"} Authorization: Bearer [API-ACCESS-TOKEN] ``` cloud console의 [토큰](https://console.coreweave.com/tokens) 페이지에서 API Access 토큰을 생성하세요. 토큰은 소속된 사용자의 권한을 상속하며, 서버는 모든 요청에서 해당 권한을 강제 적용합니다. CoreWeave Sandboxes에는 다음 두 가지 IAM 액션이 적용됩니다. * `SANDBOX_ADMIN`: 러너를 생성, 조회, 업데이트, 삭제하고, 러너가 전달하는 정책을 설정합니다. 이 페이지에 설명된 모든 엔드포인트는 조회를 포함해 이 액션이 필요합니다. `SANDBOX_USER`를 포함합니다. * `SANDBOX_USER`: 샌드박스를 생성하고 운영합니다. 이 페이지의 엔드포인트에 대한 액세스 권한은 부여하지 않습니다. cloud console의 [Access Policies](https://console.coreweave.com/organization/iam/access-policies) 페이지에서 액션 중 하나를 부여하세요. Access Policies의 작동 방식과 단계별 부여 흐름에 대한 배경 정보는 [Identity and Access Management (IAM)](/security/iam) 및 [Manage Access Policies](/security/iam/access-policies/manage)를 참조하세요. 토큰에 대한 자세한 내용은 [API 액세스 토큰 관리](/security/authn-authz/manage-api-access-tokens)를 참조하세요. 인증되지 않은 요청은 `google.rpc.Status` 형태의 본문과 함께 `401 Unauthenticated`를 반환합니다. [CoreWeave Intelligent CLI](https://github.com/coreweave/cwic) (`cwic`)는 이러한 REST 엔드포인트를 래핑합니다. CLI 사용자는 `cwic auth login`으로 한 번 인증하며, `cwic`는 토큰을 로컬 `cwic` 설정에 저장합니다. CLI 워크플로는 [샌드박스 정책 설정](/ko/products/sandboxes/profiles/configure#before-you-begin)를 참조하세요.

콘텐츠 유형

모든 요청 및 응답 본문은 JSON 형식입니다. ```text theme={"system"} Content-Type: application/json ``` API는 [connectrpc](https://connectrpc.com/)를 통해 HTTP/2로 실행되지만, 표준 `curl` 또는 `fetch` 스타일 클라이언트가 투명하게 작동합니다. gRPC 클라이언트는 필요하지 않습니다. 이 엔드포인트의 기반이 되는 게시된 Protobuf 정의와 이를 바탕으로 생성된 SDK는 [Protobuf](/ko/products/sandboxes/reference/protos)를 참조하세요.

리소스 패밀리

control plane은 managed runner를 관리용 리소스로 노출합니다. | 패밀리 | 기본 경로 | 오퍼레이션 | | - | - | - | | Managed runner | `/v1/sandbox/managedRunners` | Create, Get, List, Update, Delete, `:applyAvailableUpdate` | 정책은 독립적으로 주소를 지정할 수 없습니다. 정책은 러너의 필드이므로, 러너를 가져와서 조회하고 `policy`로 마스킹한 러너 업데이트로 기록합니다. 쓰기 작업을 할 때마다 문서 전체가 대체됩니다. 워크플로는 [Configure a sandbox policy](/ko/products/sandboxes/profiles/configure)를 참조하세요. 프로필 템플릿은 러너의 `profile_bindings` 필드와 함께 `v1beta2` 인터페이스의 `/v1beta2/sandbox/profile-templates`에서 계속 사용할 수 있습니다. 프로필 템플릿은 정책으로 대체되었으며, `v1` 모델에 포함되지 않고 앞으로도 추가되지 않습니다. 개념 모델과 게이트웨이가 런타임 요청을 중개하는 방식은 [Sandboxes architecture](/ko/products/sandboxes/architecture)를 참조하세요. 이 페이지에서는 엔드포인트 계약을 설명합니다.

페이지 매김

목록 엔드포인트는 커서 기반 페이지 매김을 지원합니다: * `pageSize`: 페이지 크기입니다. 기본값은 `50`, 최대 `100`입니다. * `pageToken`: 이전 페이지에서 `nextPageToken`으로 반환된 커서입니다. 빈 문자열은 더 이상 페이지가 없음을 의미합니다. ```bash title="Paginate managed runners" theme={"system"} curl -H "Authorization: Bearer $TOKEN" \ 'https://api.coreweave.com/v1/sandbox/managedRunners?pageSize=50' # 커서 따르기 curl -H "Authorization: Bearer $TOKEN" \ 'https://api.coreweave.com/v1/sandbox/managedRunners?pageSize=50&pageToken=[NEXT-PAGE-TOKEN]' ``` CoreWeave Intelligent CLI는 `cwic sandbox runner get`과 같은 목록 명령어의 결과를 자동으로 페이지로 나눕니다.

업데이트 시 필드 마스크

업데이트 엔드포인트는 선택적 `update_mask`를 허용합니다. 존재할 경우, 마스크에 나열된 필드만 적용되며, API는 요청 객체의 다른 모든 항목을 무시합니다. 존재하지 않을 경우, 요청 객체의 모든 비어 있지 않은 변경 가능한 필드가 적용됩니다. 경로는 점 표기법과 `snake_case` 필드 이름을 사용합니다(표준 `google.protobuf.FieldMask` 규칙). 일반적으로 사용되는 변경 가능한 경로: | Path | Applies to | Purpose | | - | - | - | | `spec.release_channel` | Managed runner | 릴리스 채널을 전환합니다(`RELEASE_CHANNEL_STABLE` 또는 `RELEASE_CHANNEL_RAPID`). | | `spec.maintenance_policy` | Managed runner | 자동 업데이트 유지 관리 윈도우를 조정합니다. | | `spec.overrides` | Managed runner | 러너 파드의 tolerations, 노드 셀렉터, 런타임 클래스를 조정합니다. | | `spec.enforce_resource_limits` | Managed runner | 러너의 샌드박스가 CPU와 메모리 limits를 선언하도록 강제 적용합니다. | | `policy` | Managed runner | 전체 정책 문서를 교체합니다. policy에 대해 구현된 유일한 마스크 경로입니다. | | `profile_bindings` | Managed runner | profile bindings의 전체 목록을 교체합니다. 레거시이며, `v1beta2` 전용입니다. `v1` 쓰기에서는 거부됩니다. | REST 표면에서, 마스크를 단일 쉼표로 구분된 `updateMask` 쿼리 매개변수로 제공하고, 각 경로의 JSON (camelCase) 형식을 사용하며, 리소스 자체를 래퍼 없이 요청 본문으로 전송합니다: ```bash theme={"system"} curl -X PATCH "https://api.coreweave.com/v1/sandbox/managedRunners/[RUNNER-ID]?updateMask=spec.releaseChannel,spec.maintenancePolicy" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "spec": { "releaseChannel": "RELEASE_CHANNEL_RAPID" } }' ``` per-endpoint 레퍼런스는 각 리소스에 대한 변경 가능한 경로를 나열합니다.

오류

오류는 적절한 HTTP 상태 코드와 `google.rpc.Status` 본문을 반환합니다. ```json theme={"system"} { "code": 3, "message": "runner.identity.zone is required", "details": [] } ``` 다음 table에는 일반적인 매핑이 나와 있습니다. | HTTP | `code` | 의미 | | - | - | - | | 400 | 3 (`INVALID_ARGUMENT`) | 필수 필드가 누락되었거나, 입력 형식이 잘못되었거나, 사양이 유효하지 않습니다. | | 401 | 16 (`UNAUTHENTICATED`) | API 토큰이 없거나 유효하지 않습니다. | | 403 | 7 (`PERMISSION_DENIED`) | 토큰에 해당 액션을 수행하는 데 필요한 권한이 없습니다. | | 404 | 5 (`NOT_FOUND`) | 리소스가 존재하지 않습니다. | | 409 | 6 (`ALREADY_EXISTS`) | `displayName` 또는 `runnerId`가 중복되었거나, 동일한 클러스터에 두 번째 러너를 생성하려고 했습니다. | | 503 | 14 (`UNAVAILABLE`) | 의존성(예: 클러스터 검증)을 일시적으로 사용할 수 없습니다. 안전하게 재시도할 수 있습니다. | | 500 | 13 (`INTERNAL`) | 예기치 않은 서버 오류입니다. 지수 백오프를 적용하여 재시도하세요. | 검증 메시지는 안정적으로 유지되는 인터페이스의 일부이므로 최종 사용자에게 그대로 표시해도 됩니다.

멱등성

control plane API는 다음과 같은 멱등성을 보장합니다. * `Delete*` 엔드포인트는 멱등성을 가집니다. 이미 삭제된 리소스에 `DELETE`를 호출하면 부작용 없이 `404`를 반환합니다. * `Create*` 엔드포인트는 멱등성을 가지지 않습니다. 동일한 `runnerId` 또는 `displayName`을 두 번 지정하면 `409 Conflict`를 반환합니다. 안전하게 재시도하려면 `GET`으로 리소스가 이미 존재하는지 먼저 확인하세요. * `Update*` 엔드포인트는 필드 마스크를 사용하여 변경하려는 필드만 설정하면 안전하게 재시도할 수 있습니다.

Heartbeats

러너 heartbeats는 러너 liveness를 추적합니다. control plane이 liveness 윈도우 내에 heartbeat를 수신하지 못하면, 러너의 `connectionStatus`가 `DISCONNECTED`로 전환됩니다. 러너가 연결 불가능해진 시점과 control plane이 이를 반영하는 시점 사이에 최대 30초의 지연이 발생할 수 있습니다. 러너 조회 응답에서 `connectionStatus`와 관련 `installStatus` 필드를 모두 조회할 수 있습니다.

참고 항목

* [샌드박스 아키텍처](/ko/products/sandboxes/architecture): 네 가지 리소스 분류 체계와 게이트웨이가 런타임 요청을 중개하는 방식을 설명합니다. * [정책 개요](/ko/products/sandboxes/profiles/profiles): 샌드박스가 정책에 따라 어떻게 결정되는지 설명합니다. * [샌드박스 정책 설정](/ko/products/sandboxes/profiles/configure): CoreWeave Intelligent CLI 워크플로와 프로필 사양의 필드별 워크스루를 제공합니다. * [러너 배포 및 관리](/ko/products/sandboxes/operations/managed-runners): 러너 라이프사이클에 대한 CoreWeave Intelligent CLI 및 REST 워크스루를 제공합니다. * [정책 레퍼런스](/ko/products/sandboxes/reference/profile): 프로필에 설정할 수 있는 모든 필드를 설명합니다. * [Protobuf](/ko/products/sandboxes/reference/protos): 게시된 Protobuf 모듈의 위치, 각 서비스를 제공하는 호스트, 생성된 SDK의 설치 방법을 설명합니다.