# OpenAPI 명세

> /v1/openapi.json에서 Nodaro OpenAPI 3.1 명세를 내려받고, 포함된 엔드포인트를 확인하고, Go, Rust, Python 등의 언어로 타입 클라이언트를 생성하세요.

Source: https://nodaro.ai/ko/docs/developers/api/openapi

**Nodaro OpenAPI 명세**는 Nodaro REST API의 핵심을 OpenAPI 3.1로 기술한 기계 판독용 설명으로, 서버가 실시간으로 제공합니다. 이 명세로 Go, Rust, Python 또는 OpenAPI 생성기가 있는 모든 언어의 타입 클라이언트를 생성하거나, OpenAPI를 읽는 도구에서 API를 살펴보세요. TypeScript와 JavaScript에서는 [SDK](https://nodaro.ai/docs/developers/sdk)가 바로 쓸 수 있는 클라이언트입니다.

## 명세 받기
```bash
curl -s https://app.nodaro.ai/v1/openapi.json -o nodaro-openapi.json
```

명세는 공개되어 있어 토큰이 필요 없으며, 5분 동안 캐시됩니다. 셀프 호스팅 설치는 같은 경로인 `/v1/openapi.json`에서 자체 명세를 제공합니다. 설정의 **API 토큰** 페이지에도 이 명세로 가는 링크가 있습니다.

## 명세가 다루는 범위
명세는 API의 **엄선된 일부**입니다. 모든 라우트가 아니라 자동화 핵심을 설명합니다. 다루는 범위는 다음과 같습니다.

| 영역 | 경로 |
| --- | --- |
| 워크플로 | `GET /v1/projects/{projectId}/workflows`, `POST /v1/workflows/{id}/run`, `POST /v1/workflows/{id}/move` |
| 작업 | `GET /v1/jobs/{id}`, `GET /v1/jobs/{id}/status` |
| 노드 탐색 | `GET /v1/nodes`, `GET /v1/nodes/{type}` |
| 생성 | `POST /v1/generate-image`, `POST /v1/generate-video` |
| OAuth | `POST /v1/oauth/token`, `GET /v1/oauth/app-info`, 그리고 `/v1/oauth/plugin/` 아래의 플러그인 연결 라우트 |
| 크레딧 | `POST /v1/credits/model-costs`, `POST /v1/credits/video-pro-estimate` |

공유 스키마 `WorkflowSummary`, `Job`, `JobStatus`, `NodeDescriptor` 4개를 정의합니다. 서버가 자체 라우트 정의로 명세를 만들므로, 정확한 목록은 실시간 파일에서 확인하세요.

사용할 때 알아 둘 점은 다음과 같습니다.

- **보안 스킴 하나.** `bearerAuth`는 `bearerFormat`이 없는 HTTP Bearer 토큰입니다. 그 설명에 받는 토큰이 나와 있습니다. 세션 JWT, 개인 API 토큰(`ndr_…`), OAuth 액세스 토큰(`ndr_app_…`), 결제 연동 키(`ndr_bill_…`)입니다. [인증](https://nodaro.ai/docs/developers/api/authentication)을 참조하세요.
- **상대 서버.** 명세의 서버는 `/`이므로, 클라이언트를 만들 때 `https://app.nodaro.ai` 같은 기본 URL을 설정하세요.
- **공개 오퍼레이션.** 모든 오퍼레이션에는 `bearerAuth`가 필요하지만, `security: []`로 표시되어 토큰을 받지 않는 9개는 예외입니다. `GET /v1/nodes`, `GET /v1/nodes/{type}`, `POST /v1/oauth/token`, `GET /v1/oauth/app-info`, `/v1/oauth/plugin/` 아래의 플러그인 연결 라우트 4개, `POST /v1/credits/model-costs`입니다.
- **생성 필드.** `POST /v1/generate-image`와 `POST /v1/generate-video`는 `connectedReferences`, `direction`, `subject`를 포함한 전체 요청 본문을 나열합니다. 각 필드의 역할은 [노드](https://nodaro.ai/docs/developers/api/nodes)를 참조하세요.

## 클라이언트 생성
```bash
# Go
oapi-codegen -generate types,client -package nodaro https://app.nodaro.ai/v1/openapi.json

# Rust
openapi-generator generate -i https://app.nodaro.ai/v1/openapi.json -g rust -o nodaro-rs

# Python
openapi-generator generate -i https://app.nodaro.ai/v1/openapi.json -g python -o nodaro-py
```

그런 다음 클라이언트가 내 기본 URL을 가리키게 하고, 공개 오퍼레이션을 제외한 모든 요청에 `Authorization: Bearer <token>`을 보내세요. 나머지는 모두 다른 페이지에서 설명한 대로 작동합니다. JSON 본문, [오류](https://nodaro.ai/docs/developers/api/errors)의 `{ "error": { "code", "message" } }` 래퍼, [작업](https://nodaro.ai/docs/developers/api/jobs)의 결과 폴링이 그렇습니다.

## 명세 밖의 엔드포인트 호출
명세에 없는 부분도 REST API는 모든 언어에서 쓸 수 있습니다. Bearer 토큰을 보내고, JSON을 보내고, JSON을 받으면 됩니다.

- **모든 노드의 라우트는 같습니다.** 노드 설정을 본문으로 보내는 `POST /v1/{node-type}`는 명세에 있는 두 노드뿐 아니라 모든 노드를 실행합니다. 노드의 필드는 `GET /v1/nodes/{type}`의 `inputSchema` 아래와 [노드 레퍼런스](https://nodaro.ai/docs/nodes)의 해당 페이지에서 확인하세요.
- **나머지 엔드포인트는 모두 이 문서에서 설명합니다.** [워크플로](https://nodaro.ai/docs/developers/api/workflows)와 [실행](https://nodaro.ai/docs/developers/api/executions)부터 [업로드](https://nodaro.ai/docs/developers/api/uploads)와 [크레딧](https://nodaro.ai/docs/developers/api/credits)까지 있습니다. 생성한 클라이언트의 원시 요청 메서드나 아무 HTTP 라이브러리로 호출하세요.

## 자주 묻는 질문

### Nodaro OpenAPI 명세는 어디에 있나요?

Nodaro Cloud의 경우 https://app.nodaro.ai/v1/openapi.json에 있습니다. 공개되어 있어 토큰이 필요 없으며, 셀프 호스팅 설치는 같은 경로에서 자체 명세를 제공합니다.

### OpenAPI 명세에 Nodaro의 모든 엔드포인트가 포함되나요?

아니요. 명세는 API의 일부를 엄선한 것으로, 자동화 핵심, 워크플로 실행, 작업 상태, 노드 탐색, 이미지와 동영상 생성, OAuth 토큰 교환, 크레딧 비용 조회를 다룹니다. 나머지 엔드포인트는 이 문서의 각 페이지에서 설명합니다.

### 명세에 없는 노드는 어떻게 호출하나요?

모든 노드는 같은 라우트를 따릅니다. POST /v1/ 뒤에 노드 타입을 붙이고, 노드 설정을 본문으로 보냅니다. GET /v1/nodes/:type에서 노드의 필드를 읽은 다음, 생성한 클라이언트의 원시 요청 메서드나 아무 HTTP 라이브러리로 요청을 보내세요.

### 명세는 어떤 인증을 선언하나요?

bearerAuth라는 스킴 하나로, 형식이 정해지지 않은 HTTP Bearer 토큰입니다. 세션 JWT, 개인 API 토큰, OAuth 액세스 토큰, 결제 연동 키를 받습니다. GET /v1/nodes 같은 공개 오퍼레이션 9개는 security: []로 표시되어 있으며 토큰을 받지 않습니다.