## 실행 조건

`바른`의 API는 기본적으로 [connectrpc](https://connectrpc.com/docs/introduction/)를 기반으로 동작합니다.
이 방식은 기존의 REST 방식 뿐만 아니라, grpc, grpc-web을 모두 하나의 서비스 방법으로 통합하였습니다.
기본적으로 프토토콜 버퍼를 사용하는 grpc 기반으로 하고 있고 이를 더욱 발전시킨 경우입니다. 때문에 REST 방식에 비해서 더 빠른 속도를 제공할 뿐 아니라 안정성도 매우 높습니다.

새로운 방법은 REST, GRPC, GRPC-WEB을 모두 하나의 서비스로 통합하였습니다.

### REST API 포트

!!! success "모든 서비스는 5656"
    하나의 서비스 포트를 통해서 grpc 나 REST, grpc-web을 모두 한번에 처리합니다. 
    아래 예시는 모두 이 포트를 사용하여 표시됩니다.
    참고로 이 포트를 통해서 3가지 서비스를 동시에 처리할 수 있습니다.

    - grpc API
    - REST API
    - `grpc-web` API

!!! success "v3.0.rc4 이후부터 적용"
    v3.0.rc4 이후부터는 `바른`의 모든 서비스 포트는 5656입니다.  이전 버전에서는 다양한 포트를 사용하도록 했습니다.

!!! success "클라우드 서비스는 HTTPS"
    api.bareun.ai를 통해서 호출을 하는 경우, 서비스 포트는 443입니다. 아래의 예시를 사용하실 때, `http://localhost:5656/` 부분을 `https://api.bareun.ai/`로 바꿔서 사용합니다.

## 사용해보기

Authorize를 눌러 <a href="https://bareun.ai/api-key" target="_blank" rel="noopener noreferrer">ApiKey</a>를 등록후 Try it out을 통해 이용해주세요.

<swagger-ui
  src="../../openapi/bareun.yaml"
  docExpansion="list"
  supportedSubmitMethods="['post']"
  tryItOutEnabled="false"
/>



## API URL 및 기능

| 기능 | URL | HTTP/1.1 METHOD |
|---|---|---|
| 형태소 분석 | `/bareun.LanguageService/AnalyzeSyntax` | POST |
| 형태소 분석(문장 분할 X) | `/bareun.LanguageService/AnalyzeSyntaxList` | POST |
| 단어 분리 | `/bareun.LanguageService/Tokenize` | POST |
| 사용자 사전 조회 | `/bareun.CustomDictionaryService/GetCustomDictionaryList` | POST |
| 사용자 사전 가져오기 | `/bareun.CustomDictionaryService/GetCustomDictionary` | POST |
| 사용자 사전 수정 | `/bareun.CustomDictionaryService/UpdateCustomDictionary` | POST |
| 사용자 사전 삭제 | `/bareun.CustomDictionaryService/RemoveCustomDictionaries` | POST |
| 사용자 사전 충돌 검사 | `/bareun.CustomDictionaryService/CheckConflict` | POST |
| 맞춤법 검사 | `/bareun.RevisionService/CorrectError` | POST |

!!! success "모두 다 POST 메서드"
    API는 모두 "POST" 방식을 사용합니다.

!!! success "Content-Type"
    Content-Type을 다양한 것이 허용되지만,
    기본적으로 "application/json"을 사용해주세요.


### 전체 URL

실제로 서비스되는 API는 다음과 같이 사용합니다.

```
http://localhost:5656/bareun.LanguageService/AnalyzeSyntax
```

클라우드 API를 사용하시려면 URL은 바뀝니다.
```
https://api.bareun.ai/bareun.LanguageService/AnalyzeSyntax
```


curl 과 같은 도구를 통해서 API를 테스트하려면 아래와 같이 하면 됩니다.

!!! info "앱 식별 헤더"
    최종 사용자의 키로 호출하는 앱(BYOK)은 `api-key` 와 함께 `X-Bareun-App-Id` 헤더를 보내면
    앱 단위로 사용량이 집계됩니다. <a href="/docs/howtouse/integration/byok-app-id" target="_blank" rel="noopener noreferrer">BYOK 앱 등록·헤더 규약</a> 참고.

## 예제

### 형태소 분석

=== "api.bareun.ai"
    ```shell
    curl \
      -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
      -H "Content-Type: application/json" \
      -X POST https://api.bareun.ai/bareun.LanguageService/AnalyzeSyntax \
      -d '{"document": {"content": "안녕하세요. 반가워요.","language": "ko-KR"}, "encoding_type": "UTF8", "custom_dict_names": ["testDomain"]}'
    ```

=== "설치본"
    ```shell
    curl \
      -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
      -H "Content-Type: application/json" \
      -X POST http://localhost:5656/bareun.LanguageService/AnalyzeSyntax \
      -d '{"document": {"content": "안녕하세요. 반가워요.","language": "ko-KR"}, "encoding_type": "UTF8", "custom_dict_names": ["testDomain"]}'
    ```


### 형태소 분석 + 동형이의어 의미 구분 (베타)

`with_sense`를 켜면 형태소마다 어깨번호(사전 의미 번호)와 뜻풀이가 함께 실립니다.
바른 3.1.0부터 제공하는 **베타** 기능입니다.
자세한 내용은 [동형이의어 의미 구분 API](homonym-sense.md)를 참고하세요.

=== "api.bareun.ai"
    ```shell
    curl \
      -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
      -H "Content-Type: application/json" \
      -X POST https://api.bareun.ai/bareun.LanguageService/AnalyzeSyntax \
      -d '{"document": {"content": "다리를 건넜다.","language": "ko-KR"}, "encoding_type": "UTF32", "with_sense": true}'
    ```

=== "설치본"
    ```shell
    curl \
      -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
      -H "Content-Type: application/json" \
      -X POST http://localhost:5656/bareun.LanguageService/AnalyzeSyntax \
      -d '{"document": {"content": "다리를 건넜다.","language": "ko-KR"}, "encoding_type": "UTF32", "with_sense": true}'
    ```

응답에서 의미가 부여된 형태소에만 `sense`가 실립니다(조사·어미에는 붙지 않습니다).

```json
{
  "text": { "content": "다리", "beginOffset": 0, "length": 2 },
  "tag": "NNG",
  "probability": 0.9917928,
  "outOfVocab": "IN_WORD_EMBEDDING",
  "sense": {
    "senseNo": 5,
    "meaning": "물을 건너거나 또는 한편의 높은 곳에서 다른 편의 높은 곳으로 건너다닐 수 있도록 만든 시설물.",
    "urimalTargetId": 836,
    "probability": 0.935963
  }
}
```

### 형태소 분석(문장 분할 X)

=== "api.bareun.ai"
    ```shell
    curl \
      -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
      -H "Content-Type: application/json" \
      -X POST https://api.bareun.ai/bareun.LanguageService/AnalyzeSyntaxList \
      -d '{"document": {"sentences": ['안녕하세요.', '바른 형태소분석기입니다.', '만나서 반갑습니다.'], "language": "ko-KR"}, "encoding_type": "UTF8", "custom_dict_names": ["testDomain"]}'
    ```

=== "설치본"
    ```shell
    curl \
      -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
      -H "Content-Type: application/json" \
      -X POST http://localhost:5656/bareun.LanguageService/AnalyzeSyntaxList \
      -d '{"document": {"sentences": ['안녕하세요.', '바른 형태소분석기입니다.', '만나서 반갑습니다.'], "language": "ko-KR"}, "encoding_type": "UTF8", "custom_dict_names": ["testDomain"]}'
    ```

### 단어 분리

=== "api.bareun.ai"
    ```shell
    curl \
      -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
      -H "Content-Type: application/json" \
      -X POST https://api.bareun.ai/bareun.LanguageService/Tokenize \
      -d '{"document": {"content": "안녕하세요. 반가워요.","language": "ko-KR"}, "encoding_type": "UTF8"}'
    ```

=== "설치본"
    ```shell
    curl \
      -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
      -H "Content-Type: application/json" \
      -X POST http://localhost:5656/bareun.LanguageService/Tokenize \
      -d '{"document": {"content": "안녕하세요. 반가워요.","language": "ko-KR"}, "encoding_type": "UTF8"}'
    ```


### 사전 목록 가져오기

모든 등록된 커스텀 사전에 대한 이름과 메타 정보를 반환합니다. 현재 서비스 되고 있는 사전의 목록을 여기에서 확인할 수 있습니다. 사용자 사전 목록을 가져올 때에는 데이터로 빈 값을 넘겨줘야 합니다.

=== "api.bareun.ai"
    ```shell
    curl \
      -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
      -H "Content-Type: application/json" \
      -X POST https://api.bareun.ai/bareun.CustomDictionaryService/GetCustomDictionaryList \
      -d '{}'
    ```

=== "설치본"
    ```shell
    curl \
      -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
      -H "Content-Type: application/json" \
      -X POST http://localhost:5656/bareun.CustomDictionaryService/GetCustomDictionaryList \
      -d '{}'
    ```

### 사전 가져오기

위 사전목록 가져오기 API를 통해서 모든 사전의 목록을 확인한 다음,
개별 사용자 사전의 내용을 다운로드할 수 있습니다.

=== "api.bareun.ai"
    ```shell
    curl \
      -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
      -H "Content-Type: application/json" \
      -X POST https://api.bareun.ai/bareun.CustomDictionaryService/GetCustomDictionary \
      -d '{ "domain_name": "mydomain"}'
    ```

=== "설치본"
    ```shell
    curl \
      -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
      -H "Content-Type: application/json" \
      -X POST http://localhost:5656/bareun.CustomDictionaryService/GetCustomDictionary \
      -d '{ "domain_name": "mydomain"}'
    ```

### 사용자 사전 수정 또는 생성

앞에서 다운로드 받은 데이터 형식 그대로 내용을 바꿔서 사전을 업데이트할 수 있습니다.
URL은 같지만, 이제는 POST 방식으로 보냅니다. 

=== "api.bareun.ai"
    ```shell
    curl \
      -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
      -H "Content-Type: application/json" \
      -X POST https://api.bareun.ai/bareun.CustomDictionaryService/UpdateCustomDictionary \
      -d '{ "domain_name": "mydomain", \
        "dict": \
          {"domain_name": "mydomain", \
            "np_set": { \
              "items": { \
                  "광화문": 1 \
                  "숭례문": 1 \
                  "흥인지문": 1 \
              }, "type": "WORD_LIST", "name": "np_set"}, \
            "cp_set": { \
              "items": {\
                  "논밭": 1 \
                  "봄비": 1 \
                  "자유여행": 1 \
              }, "type": "WORD_LIST", "name": "cp_set"},\
              "cp_caret_set": { \
              "items": { \
                  "가격^파괴": 1 \
                  "소비자^만족": 1 \
                  "블루투스^이어폰": 1 \
              },"type": "WORD_LIST", "name": "cp_caret_set"}}}'
    ```

=== "설치본"
    ```shell
    curl \
      -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
      -H "Content-Type: application/json" \
      -X POST http://localhost:5656/bareun.CustomDictionaryService/UpdateCustomDictionary \
      -d '{ "domain_name": "mydomain", \
        "dict": \
          {"domain_name": "mydomain", \
            "np_set": { \
              "items": { \
                  "광화문": 1 \
                  "숭례문": 1 \
                  "흥인지문": 1 \
              }, "type": "WORD_LIST", "name": "np_set"}, \
            "cp_set": { \
              "items": {\
                  "논밭": 1 \
                  "봄비": 1 \
                  "자유여행": 1 \
              }, "type": "WORD_LIST", "name": "cp_set"},\
              "cp_caret_set": { \
              "items": { \
                  "가격^파괴": 1 \
                  "소비자^만족": 1 \
                  "블루투스^이어폰": 1 \
              },"type": "WORD_LIST", "name": "cp_caret_set"}}}'
    ```


### 사용자 사전 삭제

사전을 삭제할 때는 전체를 삭제할 수도 있고, 일부만 삭제할 수도 있습니다.
`"all" : true` 이면 모든 내용을 삭제합니다.

=== "api.bareun.ai"
    ```shell
    curl \
      -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
      -H "Content-Type: application/json" \
      -X POST https://api.bareun.ai/bareun.CustomDictionaryService/RemoveCustomDictionaries \
      -d '{"domain_names": ["mydomain"],"all": true}'
    ```

=== "설치본"
    ```shell
    curl \
      -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
      -H "Content-Type: application/json" \
      -X POST http://localhost:5656/bareun.CustomDictionaryService/RemoveCustomDictionaries \
      -d '{"domain_names": ["mydomain"],"all": true}'
    ```

### 사용자 사전 충돌 검사

하나 이상의 사전을 동시에 사용할 수 있기 때문에 의도하지 않은 결과를 가져올 수 있습니다.
사용자 사전을 두 개 이상 지정하여 비교할 수 있습니다.

=== "api.bareun.ai"
    ```shell
    curl \
      -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
      -H "Content-Type: application/json" \
      -X POST https://api.bareun.ai/bareun.CustomDictionaryService/CheckConflict \
      -d '{"domain_names": ["compare1", "compare2"]}'
    ```

=== "설치본"
    ```shell
    curl \
      -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
      -H "Content-Type: application/json" \
      -X POST http://localhost:5656/bareun.CustomDictionaryService/CheckConflict \
      -d '{"domain_names": ["compare1", "compare2"]}'
    ```


### 맞춤법 검사

어법, 띄어쓰기, 표준어 등 교정할 문장을 보내고, 교정 결과를 받아볼 수 있습니다. 한 문단 단위로 입력을 해주시고, 여러 문단을 한꺼번에 보내도 됩니다.

=== "api.bareun.ai"
    ```shell
    curl \
      -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
      -H "Content-Type: application/json" \
      -X POST https://api.bareun.ai/bareun.RevisionService/CorrectError \
      -d '{"document": {"content": "밥이 떡처럼 되서 못먹었어요","language": "ko-KR"}, "encoding_type": "UTF32", "custom_dict_names": ["testDomain"]}'
    ```

=== "설치본"
    ```shell
    curl \
      -H "api-key: koba-ABCDEFG-1234567-LMNOPQR-7654321" \
      -H "Content-Type: application/json" \
      -X POST http://localhost:5656/bareun.RevisionService/CorrectError \
      -d '{"document": {"content": "밥이 떡처럼 되서 못먹었어요","language": "ko-KR"}, "encoding_type": "UTF32", "custom_dict_names": ["testDomain"]}'
    ```


## API 규격

### 형태소 분석
- 기능: 가장 핵심적인 형태소 분석을 수행합니다.
- Path: /bareun.LanguageService/AnalyzeSyntax
- Method: POST

#### 요청

|  이름 |  서브 |  설명 |
|----|---|---|
| document | {} | 입력 문서 |
| | content | 문서 및 문장이 들어갑니다. 여러 문장이라면 줄바꿈으로 구분해도 됩니다. 만일 자동 줄바꿈을 원한다면,  `auto_split_sentence` 옵션을 켜면 됩니다. |
| | language | 현재는 한국어만 지원하므로 지정하지 않아도 됩니다. ISO 또는 BCP-47 언어코드가 사용됩니다. ko_KR 과 같이 입력하면 됩니다.|
| encoding_type | - | `UTF8`, `UTF16`, `UTF32` 중에서 선택합니다. 통상적으로 개발 언어별로 그 쓰임새가 다릅니다. <br>파이썬 3의 경우는 `UTF32`, 자바의 경우는 `UTF16`, C나 golang의 경우에는 `UTF8`을 쓰면 됩니다. |
| auto_split_sentence | - | 여러 문장이 함께 올 경우 문장 분할 기능을 수행할지 여부, 기본적으로 줄바꿈 단위로 분장을 분할한다. |
| auto_spacing | - | 자동으로 띄어쓰기를 수행할지 여부를 정합니다. 라이브러리에서 기본값을 `true`로 둡니다. `REST`에서는 직접 지정해야 합니다. |
| auto_jointing | - | 자동으로 붙여쓰기를 수행할지 여부를 정합니다. 라이브러리에서 기본값을 `true`로 둡니다. `REST`에서는 직접 지정해야 합니다. |
| with_sense | - | 동형이의어 의미 구분(WSD, **베타**)을 함께 수행할지 정합니다. 기본값은 `false`이며, 켜면 응답 형태소에 `sense`(어깨번호·뜻풀이·우리말샘 번호·선택 확률)가 실립니다. |
| custom_domain | - | 사용할 사용자 사전의 이름을 지정합니다. 이 사용자 사전의 이름은 별도의 API를 통해서 미리 등록되어 있어야 합니다. 사용하려는 사전 이름이 없으면 무시됩니다.  ~~폐기되었습니다.~~ |
| custom_dict_names | - | 사용할 사용자 사전의 이름을 지정합니다. 미리 등록된 사전을 여러 개 지정할 수 있습니다. 적용 순서는 먼저 지정한 사전부터 적용됩니다.|

### 형태소 분석(문장 분할 하지 않음)
- 기능: 형태소 분석을 수행하되 복수의 입력 문장의 순서를 그대로 반환하고 문장을 분할하지 않습니다.
- Path: /bareun.LanguageService/AnalyzeSyntaxList
- Method: POST

### 요청

| 변수 | 설명 |
| --- | --- |
|sentences|  배열로 이루어진 텍스트를 넣습니다. |
|language| 현재는 한국어만 지원하므로 지정하지 않아도 됩니다. ISO 또는 BCP-47 언어코드가 사용됩니다. ko_KR 과 같이 입력하면 됩니다. |
|encoding_type| `UTF8`, `UTF16`, `UTF32` 중에서 선택합니다. 통상적으로 개발 언어별로 그 쓰임새가 다릅니다. 파이썬 3의 경우는 UTF32, 자바의 경우는 `UTF16`, C나 golang의 경우에는 `UTF8`을 쓰면 됩니다.|
|auto_spacing| 자동으로 띄어쓰기를 수행할지 여부를 정합니다. 라이브러리에서 기본값을 `true`로 둡니다. REST에서는 직접 지정해야 합니다.|
|auto_jointing| 자동으로 붙여쓰기를 수행할지 여부를 정합니다. 라이브러리에서 기본값을 `true`로 둡니다. REST에서는 직접 지정해야 합니다. |
| custom_domain | 사용할 사용자 사전의 이름을 지정합니다. 이 사용자 사전의 이름은 별도의 API를 통해서 미리 등록되어 있어야 합니다. 사용하려는 사전 이름이 없으면 무시됩니다. |
| custom_dict_names | - | 사용할 사용자 사전의 이름을 지정합니다. 미리 등록된 사전을 여러 개 지정할 수 있습니다. 적용 순서는 먼저 지정한 사전부터 적용됩니다.|

#### 응답

|  이름 |  Sub1 | Sub2 | Sub3 | Sub4 |  설명 |
|----|---|---|---|---|---|
| sentences | [] | | | | 한 개 이상의 문장으로 구분됩니다. |
| | refined | ||| 문장의 띄어쓰기, 붙여쓰기 등으로 바뀌었으면 정제되었다고 표시 |
| | text |{}||| 문장의 전체 텍스트 조각 |
| | | content|||  문장의 내용 |
| | | begin_offset||| 문장의 시작 위치 |
| | | length|||  문장의 길이 |
| | tokens | [] |||  어절의 배열 |
| | | text | {} || 어절의 텍스트 조각 |
| | | | content||  어절의 내용 |
| | | | begin_offset|| 어절의 시작 위치 |
| | | | length||  어절의 길이 |
| | | lemma | || 원형 |
| | | tagged | || 태깅 형태로 만든 문자열 |
| | | modified | || 붙여쓰기한 경우, 붙여진 결과 |
| | | morphemes | [] || 형태소의 배열 |
| | | | text |{}| 형태소의 텍스트 조각 |
| | | || content|  형태소의 내용 |
| | | || begin_offset| 형태소의 시작 위치 |
| | | || length| 형태소의 시작 위치 |
| | | | tag| |  형태소 태그, 모두 47개의 품사가 사용됩니다. |
| | | | probability | |  형태 분류의 정확도 |
| | | | out_of_vocab | | 형태 분류 중 사전 활용의 결과 표시. <br> `IN_WORD_EMBEDDING`: 워드임베딩에 포함된 내용 <br> `OUT_OF_VOCAB`: 자동 추측 <br> `IN_CUSTOM_DICT`: 사용자 제공 사전에 있는 내용 <br> `IN_BUILTIN_DICT` : 기본 사전에 포함된 내용 |
| | | | custom_dict_name | | 사용자 사전에서 지정된 단어일 경우, 그 사전의 이름을 표시합니다. |
| | | | sense | | 동형이의어 의미 구분(WSD, **베타**) 결과. `with_sense`를 켰고 그 형태소에 의미가 부여된 경우에만 실립니다. <br> `senseNo`: 어깨번호(우리말샘 의미 번호) <br> `meaning`: 뜻풀이(빈 값일 수 있음) <br> `urimalTargetId`: 우리말샘 표제어 번호 <br> `probability`: 후보 의미 중 이 의미를 고른 확률 |
| language | |||| 이 응답의 언어, ko_KR이 기본으로 사용됩니다. |


### 사용자 사전 조회

- 기능: 사용자 사전 조회 
- Path: /bareun.CustomDictionaryService/GetCustomDictionaryList 
- Method: POST

#### 요청

- 요청에 보낼 내용은 없습니다.
- 대신에 빈 JSON을 값을 보내줘야 합니다. `{}`

#### 응답

|  이름 |  Sub1 | Sub2 |   설명 |
|----|---|---|---|
| domain_dicts | [] | | 하나 이상의 meta 데이터 |
| | domain_name | | 사전의 이름 |
| | np_set | {} | 고유명사 사전 정보|
| | | name | 사전의 이름 |
| | | items_count | 사전 크기 정보 |
| | | type | "WORD_LIST" |
| | cp_set | {} | 복합명사 사전 정보 |
| | | name | 사전의 이름 |
| | | items_count | 사전 크기 정보 |
| | | type | "WORD_LIST" |
| | cp_caret_set | {} | 복합명사 분리 사전 정보 |
| | | name | 사전의 이름 |
| | | items_count | 사전 크기 정보 |
| | | type | "WORD_LIST" |
| | vv_set | {} | 동사사전  정보 |
| | | name | 사전의 이름 |
| | | items_count | 사전 크기 정보 |
| | | type | "WORD_LIST" |
| | va_set | {} | 형용사 사전 정보 |
| | | name | 사전의 이름 |
| | | items_count | 사전 크기 정보 |
| | | type | "WORD_LIST" |


#### 사용자 사전 가져오기

- 기능: 사용자 사전 조회
- Path: /bareun.CustomDictionaryService/GetCustomDictionary
- Method: POST

##### 요청

| 변수 | 설명 |
| --- | --- |
| domain_name |  가져올 사용사 사전의 이름을 넣습니다. |


##### 응답

|  이름 |  Sub1 | Sub2 | Sub3|  설명 |
|----|---|---|---|---|
| domain | | || 응답 도메인 이름 |
| dict | domain_name | ||| 사전의 이름 |
| | np_set | {} || 고유명사 사전 정보|
| | | name || 사전의 이름 |
| | | type | "WORD_LIST" |
| | | items| [] | 실제 사전 내용 정의 시작 |
| | | | KEY | 사전 텍스트 |
| | | | VALUE | 0이 아닌 정수값 |
| | cp_set | {} || 복합명사 사전 정보|
| | | name || 사전의 이름 |
| | | type | "WORD_LIST" |
| | | items| [] | 실제 사전 내용 정의 시작 |
| | | | KEY | 사전 텍스트 |
| | | | VALUE | 0이 아닌 정수값 |
| | cp_caret_set | {} || 복합명사 분리 사전 정보|
| | | name || 사전의 이름 |
| | | type | "WORD_LIST" |
| | | items| [] | 실제 사전 내용 정의 시작 |
| | | | KEY | 사전 텍스트 |
| | | | VALUE | 0이 아닌 정수값 |
| | vv_set | {} || 동사사전 정보|
| | | name || 사전의 이름 |
| | | type | "WORD_LIST" |
| | | items| [] | 실제 사전 내용 정의 시작 |
| | | | KEY | 사전 텍스트 |
| | | | VALUE | 0이 아닌 정수값 |
| | va_set | {} || 형용사사전 정보|
| | | name || 사전의 이름 |
| | | type | "WORD_LIST" |
| | | items| [] | 실제 사전 내용 정의 시작 |
| | | | KEY | 사전 텍스트 |
| | | | VALUE | 0이 아닌 정수값 |

#### 사용자 사전 수정

- 기능: 사용자 사전 수정
- URL: /bareun.CustomDictionaryService/UpdateCustomDictionary
- Method:  POST

#####  요청

|  이름 |  Sub1 | Sub2 | Sub3|  설명 |
|----|---|---|---|---|
| domain | | || 응답 도메인 이름 |
| dict | domain_name | ||| 사전의 이름 |
| | np_set | {} || 고유명사 사전 정보|
| | | name || 사전의 이름 |
| | | type | "WORD_LIST" |
| | | items| [] | 실제 사전 내용 정의 시작 |
| | | | KEY | 사전 텍스트 |
| | | | VALUE | 0이 아닌 정수값 |
| | cp_set | {} || 복합명사 사전 정보|
| | | name || 사전의 이름 |
| | | type | "WORD_LIST" |
| | | items| [] | 실제 사전 내용 정의 시작 |
| | | | KEY | 사전 텍스트 |
| | | | VALUE | 0이 아닌 정수값 |
| | cp_caret_set | {} || 복합명사 분리 사전 정보|
| | | name || 사전의 이름 |
| | | type | "WORD_LIST" |
| | | items| [] | 실제 사전 내용 정의 시작 |
| | | | KEY | 사전 텍스트 |
| | | | VALUE | 0이 아닌 정수값 |
| | vv_set | {} || 동사사전 정보|
| | | name || 사전의 이름 |
| | | type | "WORD_LIST" |
| | | items| [] | 실제 사전 내용 정의 시작 |
| | | | KEY | 사전 텍스트 |
| | | | VALUE | 0이 아닌 정수값 |
| | va_set | {} || 형용사사전 정보|
| | | name || 사전의 이름 |
| | | type | "WORD_LIST" |
| | | items| [] | 실제 사전 내용 정의 시작 |
| | | | KEY | 사전 텍스트 |
| | | | VALUE | 0이 아닌 정수값 |


##### 응답

|  이름 |  서브 |  설명 |
|----|---|---|
| updated_domain_name | - | 수정된 도메인 이름. |

#### 사용자 사전 삭제

- 기능: 사용자 사전 삭제
- URL: /bareun.CustomDictionaryService/RemoveCustomDictionaries
- Method:  POST


##### 요청

|  이름 |  서브 |  설명 |
|----|---|---|
| domain_names | []|  삭제할 도메인의 배열. |
| | VALUE | 삭제할 도메인 |
| all | | 모두 삭제 여부, `true` 이면 모든 사용자 사전 삭제 |


##### 응답

|  이름 |  서브 |  설명 |
|----|---|---|
| deleted_domain_names | {} | 객체 형식으로 반환 |
| | KEY | - | 객체의 키가 삭제된 도메인의 이름 |
| | VALUE` | - | `true` 또는 `false` |


### 맞춤법 검사
- 기능: 어법, 띄어쓰기, 표준어 등을 검사하고 교정합니다.
- Path: /bareun.RevisionService/CorrectError
- Method: POST

#### 요청

|  이름 |  서브 |  설명 |
|----|---|---|
| document | {} | 입력 문서 |
| | content | 문서 및 문장이 들어갑니다. 여러 문장이라면 줄바꿈으로 구분해도 됩니다. 만일 자동 줄바꿈을 원한다면,  `auto_split_sentence` 옵션을 켜면 됩니다. |
| | language | 현재는 한국어만 지원하므로 지정하지 않아도 됩니다. ISO 또는 BCP-47 언어코드가 사용됩니다. ko_KR 과 같이 입력하면 됩니다.|
| encoding_type | - | `UTF8`, `UTF16`, `UTF32` 중에서 선택합니다. 통상적으로 개발 언어별로 그 쓰임새가 다릅니다. <br>파이썬 3의 경우는 `UTF32`, 자바의 경우는 `UTF16`, C나 golang의 경우에는 `UTF8`을 쓰면 됩니다. |
| custom_dict_names | - | 사용할 사용자 사전의 이름을 지정합니다. 이 사용자 사전의 이름은 별도의 API를 통해서 미리 등록되어 있어야 합니다. 사용하려는 사전 이름이 없으면 무시됩니다. |
| config | {} | 상세한 호출 옵션입니다. |
| | disable_split_sentence | 문장 단위를 분할하지 않습니다. 기본값이므로 사용하지 않는 것이 좋습니다. |
| | disable_caret_spacing | 복합명사의 분리 사전을 적용하지 않습니다. 기본적으로 적용합니다. "인공지능"이라는 붙여 쓴 단어를 만나면, 원 정의가 "인공^자눙"이므로 "인공 지능"으로 분리해 냅니다. |
| | disable_vx_spacing | 보조 용언의 띄어쓰기를 최소화 합니다. 기본적으로 보조 용언을 최대한 띄어 씁니다. 이게 기본적인 띄어쓰기 검사의 규칙입니다. |
| | treat_as_title | 문장을 제목으로 다룹니다. 제목으로 사용하는 문장에서는 구두점을 비롯한 일부 처리가 달라집니다. |
| | enable_cleanup_whitespace | 문장에 포함된 불필요한 공백을 제거합니다. 특히, 문장의 시작이나 끝에 붙어 있는 불필요한 공백을 제거하도록 할 수 있습니다. |
| | enable_sentence_check | 문장 단위 점검을 켭니다. 서술어와 맞지 않는 목적격을 주격으로 고치고, 번역투 피동(`~에 의해 ~되다`)을 능동문으로 바꾼 표현을 확인 블록으로 제안합니다. 기본값은 `false`입니다. |
| | enable_public_term_refine | 공공 용어 순화 제안을 켭니다. 국립국어원이 다듬은 행정 용어와 일본어 투 용어에 쉬운 말을 확인 블록으로 제안하고 본문은 바꾸지 않습니다. 기본값은 `false`입니다. |
| | enable_contested_fix | 논란 여지 고침을 켭니다. 지침이 권하지만 흔히 쓰이는 표현(`좋은 하루 되세요`, `회의에 있어서` 등)을 확인 블록으로 제안하고, 수량 표현 뒤 복수 `-들`은 본문에서 뺍니다. 기본값은 `false`입니다. |
| | disable_bias_check | 낮잡는 말과 차별 표현에 중립 표현을 제안하는 확인 블록을 끕니다. 기본값은 `false`(켜 둠)입니다. |

#### 응답

| 변수 | 서브 | 설명 |
| --- | --- | --- |
| origin |  | 원래 요청 문서의 전체 문장 |
| revised |  | 교정 문서 전체 |
| revised_blocks[] |  | 교정의 블럭을 제시하여 다양한 교정 행위를 수행할 수 있다. |
|  | origin | 교정대상의 위치를 포함하는 원문의 텍스트 |
|  | revised | 교정된 결과물, 여러가지 중에 하나로서 가장 대표적인 경우 |
|  | revisions | 다양한 교정  예시들, 교정의 카테고리, 도움말 ID 정보를 포함 |
|  | nested | 여러 개의 블럭을 하나로 합친 경우에는  원래의 블럭이 틀리지 않았을 것이므로<br> 이들을 포함하여 내부에 가지도록 한다.  다만 이 nested 블럭은 각각은 개별 수정만을 포함하고 있으므로<br> 제대로 모든 블럭을 다 가지고 있을 수 없다.   고급 사용의 경우, 해당 내용만을 수정에 반영할 수 있도록 하기 위해서 마련되었다.  |
|  | lemma | 사용사 사전에 추가하기 위한 기본 단위, nested가 존재하는 쓸 수 없다. |
|  | pos | 사용사 사전에 추가할 품사 |
| whitespace_cleanup_ranges[] | |  교정대상에서 지워야할 공백들의 목록 |
|  | offset | 위치|
|  | length | 길이 |
|  | position | `START`, `END`, `MIDDLE` 등 3가지 값을 가집니다. |
| revised_sentences[] |  | 전체 문장 단위 교정, 문장은 자동으로 분리되어서 나타난다. |
|  | origin | 교정 대상의 문장 |
|  | revised | 교정된 문장 |
| helps{} |  |  |
|  | id | 도움말 ID, 고정된 도움말이 있을 수 있고, 동적으로 생성되는 도움말이 있을 수 있다. |
|  | category | 교정의 카테고리 |
|  | comment | 바뀌어야 하는 이유에 대한 섧명 |
|  | examples[] | 변경이 될 수 있는 문장들 |
|  | rule_article | 관련 규정 |
| language |  | 텍스트의 언어, 만일 언어가 지정되지 않은 경우에는 자동으로 탐지하여 반환한다.<br>언어가 지정된 경우에는 동일한 언어를 반환한다. 이때, 언어는 ko_KR 등과 같이 사용한다. |