> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lexq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API 개요

> REST API를 통해 LexQ 정책 실행을 애플리케이션에 통합합니다.

## Base URL

LexQ는 용도에 따라 두 개의 Base URL을 제공합니다:

| API                | Base URL                               | 용도                    |
| ------------------ | -------------------------------------- | --------------------- |
| **Management API** | `https://api.lexq.io/api/v1/partners`  | 정책 생명주기 (생성, 테스트, 배포) |
| **Execution API**  | `https://api.lexq.io/api/v1/execution` | 런타임 정책 평가 (고객 앱에서 호출) |

<Warning>
  두 Base URL을 혼용하지 마세요. Management 엔드포인트는 Execution Base URL에서 404를 반환하며, 그 반대도 마찬가지입니다.
</Warning>

## 인증

LexQ는 **API Key** 인증을 사용합니다. 모든 요청에 키를 포함하세요:

```bash theme={null}
x-api-key: YOUR_API_KEY
```

API 키는 콘솔의 **Management → API Keys**에서 생성 및 관리합니다.

<Warning>
  API 키는 조직의 정책 엔진에 대한 전체 접근 권한을 부여합니다. 클라이언트 측 코드나 공개 저장소에 노출하지 마세요.
</Warning>

## 요청 형식

모든 요청 및 응답 본문은 JSON을 사용합니다. `Content-Type` 헤더를 설정하세요:

```
Content-Type: application/json
```

## 응답 형식

모든 응답은 일관된 엔벨로프를 따릅니다:

<CodeGroup>
  ```json 성공 theme={null}
  {
      "result": "SUCCESS",
      "data": { ... },
      "message": null
  }
  ```

  ```json 에러 theme={null}
  {
      "result": "ERROR",
      "data": null,
      "code": "P-001",
      "message": "Policy group not found."
  }
  ```
</CodeGroup>

<Warning>
  최상위 필드는 `result` (값: `"SUCCESS"` 또는 `"ERROR"`)이며, `success: true/false`가 **아닙니다**. 연동 코드에서 항상 `result === "SUCCESS"`를 확인하세요.
</Warning>

## 에러 코드

에러 코드는 접두사 규칙을 따릅니다:

| 접두사       | 도메인                      |
| --------- | ------------------------ |
| `C-xxx`   | 공통 (입력 검증, 조회 실패, 속도 제한) |
| `A-xxx`   | 인증 (자격 증명, API 키, 세션)    |
| `P-xxx`   | 정책 엔진 (그룹, 버전, 규칙, 배포)   |
| `I-xxx`   | 멱등성                      |
| `S-xxx`   | 시스템 / 암호화                |
| `B-xxx`   | 결제 (구독, 결제, 할당량)         |
| `M-xxx`   | 멤버 & 계정                  |
| `AN-xxx`  | 분석 & 시뮬레이션               |
| `ACT-xxx` | 액션 검증 (할인, 포인트, 알림)      |
| `FD-xxx`  | 팩트 정의                    |
| `INT-xxx` | 연동                       |
| `FL-xxx`  | 장애 로그                    |
| `WH-xxx`  | 웹훅 구독                    |

자세한 내용은 [에러 레퍼런스](/ko/api/errors)를 참조하세요.

## 속도 제한

속도 제한은 **조직(tenant) 단위**로 적용됩니다 — 동일 조직의 모든 API 키가 같은 한도를 공유합니다. 한도는 플랜의 **Max TPS** 설정에 따라 결정됩니다:

| 플랜         | Max TPS |
| ---------- | ------- |
| Free       | 10      |
| Growth     | 100     |
| Pro        | 500     |
| Enterprise | 별도 협의   |

스로틀링은 1초 단위 strict fixed window 방식입니다 — 카운터는 매 epoch 초마다 리셋됩니다. 해당 초 안에서 TPS 한도를 초과한 요청은 HTTP `429 Too Many Requests`와 `C-007` 코드를 받습니다.

실행 엔드포인트의 경우, [배치와 복합 호출](/ko/api/execution#배치-실행)은 포함된 팩트 세트 수와 무관하게 TPS에 대해 **1건의 요청으로 계산**됩니다. 이 점이 플랜을 업그레이드하지 않고 트래픽 스파이크를 처리하는 가장 직접적인 방법입니다.

<Tip>
  API 키를 추가 발급해도 실효 TPS는 늘어나지 않습니다 — 모든 키가 동일한 tenant 버킷을 공유합니다. 한도를 올리려면 플랜을 업그레이드하거나, 호출을 배치로 묶어 한 요청 안에 더 많은 작업을 담으세요.
</Tip>

## 멱등성

실행 엔드포인트에 `Idempotency-Key` 헤더를 포함하여 중복 처리를 방지할 수 있습니다:

```bash theme={null}
Idempotency-Key: unique-request-id-123
```

동일한 키로 중복 요청 시 정책을 다시 실행하지 않고 원래 응답을 반환합니다.

## 페이지네이션

목록 엔드포인트는 페이지네이션된 결과를 반환합니다:

```json theme={null}
{
  "result": "SUCCESS",
  "data": {
    "content": [ ... ],
    "totalElements": 42,
    "totalPages": 3,
    "pageNo": 0,
    "pageSize": 20
  }
}
```

`pageNo` (0부터 시작)와 `pageSize` 쿼리 파라미터로 페이지를 탐색합니다.

## 다음 단계

<CardGroup cols={2}>
  <Card title="인증" icon="key" href="/ko/api/authentication">
    API 키 관리 및 보안 모범 사례.
  </Card>

  <Card title="정책 실행" icon="bolt" href="/ko/api/execution">
    라이브 트래픽에 대해 정책을 실행합니다.
  </Card>
</CardGroup>