> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adrop.io/llms.txt
> Use this file to discover all available pages before exploring further.
# 문맥 타겟팅 API
> API 키로 서버에서 문맥 타겟팅과 타겟팅 옵션, 컨텍스트 ID를 관리하는 방법을 안내합니다.
문맥 타겟팅 API를 사용하면 서버에서 문맥 타겟팅을 관리할 수 있습니다. CMS의 섹션, 게시판, 태그를 타겟팅 옵션과 컨텍스트 ID에 대응시켜 두면, 콘텐츠가 바뀔 때마다 콘솔에서 일일이 수정하지 않고 자동으로 갱신할 수 있습니다.
API는 콘솔의 문맥 타겟팅과 같은 데이터를 다룹니다. API로 만든 타겟팅은 콘솔에 표시되고, 콘솔에서 만든 타겟팅도 API로 조회할 수 있습니다.
***
## 사전 준비
* `context-targeting:read`와 `context-targeting:write` 권한(scope)이 모두 있는 API 키가 필요합니다. 키는 프로젝트 소유자가 **\[관리]** > **\[연동]** 메뉴에서 발급하며, 이때 두 권한을 모두 선택합니다. 키 발급 방법은 [연동 & API 키](/ko/integrations/overview)를 참고하세요.
* 이미 발급한 키의 권한은 바꿀 수 없습니다. 지금 쓰는 키에 두 권한 중 하나라도 없다면 새 키를 발급하고, 기존 키가 더 이상 필요 없으면 폐기하세요.
주로 쓰기 요청만 보내더라도 두 권한을 모두 부여하세요. 엔드포인트마다 확인하는 권한은 하나뿐이며, `context-targeting:write`에는 `context-targeting:read`가 포함되지 않습니다. 쓰기 권한만 있는 키는 모든 `GET` 요청에서 `403`을 받으므로 ID를 찾거나, 현재 컨텍스트 ID를 읽거나, 변경 사항이 로드됐는지 확인할 수 없습니다.
API는 서버에서만 호출하세요. 앱이나 웹 페이지에 API 키를 넣지 마세요.
***
## 기본 정보
| 항목 | 값 |
| - | - |
| Base URL | `https://lake.adrop.io` |
| 인증 | `x-api-key` 헤더에 API 키를 넣습니다. 키로 프로젝트가 정해지므로 경로에는 프로젝트 ID가 들어가지 않습니다. |
| Content-Type | `application/json` |
| 요청 본문 최대 크기 | 8 MB. 이보다 큰 요청은 `413`을 반환합니다. |
| ID 형식 | 서버가 발급하는 26자 ULID입니다(예: `01JAB3XK5Q8V7M2N4P6R9T0W1Y`). 올바른 ULID가 아닌 ID를 보내면 `400`을 반환합니다. |
| 쓰기 처리 | API는 프로젝트별로 쓰기 요청을 한 번에 하나씩 처리합니다. 다른 쓰기 요청이 처리되는 동안 보낸 요청은 `409 CONTEXT_TARGETING_WRITE_IN_PROGRESS`로 실패할 수 있으니, 쓰기 요청은 병렬로 보내지 말고 하나씩 차례로 보내세요. 읽기 요청은 영향을 받지 않습니다. [동시 쓰기](/ko/integrations/context-targeting/errors#동시-쓰기)를 참고하세요. |
요청 한도 전체는 [한도](/ko/integrations/context-targeting/errors#한도)를 참고하세요.
***
## 용어
API 경로와 필드 중 일부는 콘솔과 다른 이름을 씁니다. 이 문서는 콘솔의 용어를 씁니다.
| API | 콘솔 용어 | 설명 |
| - | - | - |
| `targeting` | 타겟팅 | "News Sections" 같은 문맥 타겟팅입니다. 이 API는 문맥 타겟팅만 다룹니다. |
| `category` | 타겟팅 옵션(옵션) | "Sports"처럼 타겟팅에 속한 옵션입니다. |
| `contexts` | 컨텍스트 ID | `sport`처럼 옵션에 등록된 ID입니다. 앱이나 웹사이트는 광고 요청에 이 ID를 `contextId`로 보냅니다. |
| `type: "collection"` | 옵션 그룹 | 하위 옵션을 묶는 옵션입니다. 자신의 컨텍스트 ID와 하위 옵션의 컨텍스트 ID에 모두 매칭됩니다. 일반 옵션은 `type: "atomic"`입니다. |
| `children`, `parent` | 하위 옵션 | 옵션 그룹 안에 있는 옵션입니다. 옵션 그룹의 `children`에는 하위 옵션 목록이, 하위 옵션의 `parent`에는 소속 옵션 그룹이 들어 있습니다. |
| `exposeChildren` | 하위 옵션을 광고주에게 노출 | 광고주가 옵션 그룹의 하위 옵션을 하나씩 따로 선택할 수 있는지 여부입니다. 광고 송출에는 영향을 주지 않습니다. |
***
## 엔드포인트
경로는 Base URL 기준입니다. 각 엔드포인트를 호출하려면 표에 적힌 권한이 필요합니다.
| 메서드 | 경로 | 권한 | 설명 |
| - | - | - | - |
| `GET` | `/context-targeting` | `context-targeting:read` | [타겟팅 목록 조회](/ko/integrations/context-targeting/targetings#타겟팅-목록-조회) |
| `GET` | `/context-targeting/{targetingId}` | `context-targeting:read` | [타겟팅 조회](/ko/integrations/context-targeting/targetings#타겟팅-조회)(옵션 포함) |
| `POST` | `/context-targeting` | `context-targeting:write` | [타겟팅 생성](/ko/integrations/context-targeting/targetings#타겟팅-생성)(옵션도 함께 생성 가능) |
| `PATCH` | `/context-targeting/{targetingId}` | `context-targeting:write` | [타겟팅 이름 변경](/ko/integrations/context-targeting/targetings#타겟팅-이름-변경) |
| `DELETE` | `/context-targeting/{targetingId}` | `context-targeting:write` | [타겟팅 삭제](/ko/integrations/context-targeting/targetings#타겟팅-삭제)(모든 옵션 함께 삭제) |
| `POST` | `/context-targeting/bulk/create` | `context-targeting:write` | [타겟팅 일괄 생성](/ko/integrations/context-targeting/targetings#타겟팅-일괄-생성)(요청당 최대 100개) |
| `POST` | `/context-targeting/bulk/update` | `context-targeting:write` | [타겟팅 이름 일괄 변경](/ko/integrations/context-targeting/targetings#타겟팅-이름-일괄-변경)(요청당 최대 100개) |
| `POST` | `/context-targeting/bulk/delete` | `context-targeting:write` | [타겟팅 일괄 삭제](/ko/integrations/context-targeting/targetings#타겟팅-일괄-삭제)(요청당 최대 100개) |
| `GET` | `/context-targeting/{targetingId}/categories` | `context-targeting:read` | 타겟팅의 [옵션 목록 조회](/ko/integrations/context-targeting/options#옵션-목록-조회)(페이지 단위) |
| `GET` | `/context-targeting/category/{categoryId}` | `context-targeting:read` | [옵션 조회](/ko/integrations/context-targeting/options#옵션-조회)(컨텍스트 ID 포함) |
| `POST` | `/context-targeting/{targetingId}/category` | `context-targeting:write` | 타겟팅에 [옵션 추가](/ko/integrations/context-targeting/options#옵션-추가) |
| `PATCH` | `/context-targeting/category/{categoryId}` | `context-targeting:write` | [옵션 수정](/ko/integrations/context-targeting/options#옵션-수정): 이름 변경, 컨텍스트 ID 변경, 이동, `exposeChildren` 설정 |
| `DELETE` | `/context-targeting/category/{categoryId}` | `context-targeting:write` | [옵션 삭제](/ko/integrations/context-targeting/options#옵션-삭제) |
| `POST` | `/context-targeting/category/bulk/create` | `context-targeting:write` | [옵션 일괄 추가](/ko/integrations/context-targeting/options#옵션-일괄-추가)(요청당 최대 5,000개) |
| `POST` | `/context-targeting/category/bulk/update` | `context-targeting:write` | [옵션 일괄 수정](/ko/integrations/context-targeting/options#옵션-일괄-수정)(요청당 최대 5,000개) |
| `POST` | `/context-targeting/category/bulk/delete` | `context-targeting:write` | [옵션 일괄 삭제](/ko/integrations/context-targeting/options#옵션-일괄-삭제)(요청당 최대 5,000개) |
일괄 작업 엔드포인트는 항목별 결과를 반환합니다. [일괄 작업 응답](/ko/integrations/context-targeting/errors#일괄-작업-응답)을 참고하세요.
***
## 빠른 시작
이 예시에서는 "News Sections" 타겟팅을 만들고, 옵션 하나의 컨텍스트 ID를 바꾼 뒤, 변경 사항이 로드됐는지 확인합니다.
요청 한 번으로 타겟팅과 옵션을 함께 만듭니다.
```bash theme={null}
curl -X POST https://lake.adrop.io/context-targeting \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "News Sections",
"categories": [
{ "name": "Sports", "contexts": ["sport", "baseball", "soccer"] },
{ "name": "Tech", "contexts": ["tech", "ai", "mobile"] }
]
}'
```
`201` 응답으로 새 타겟팅이 반환됩니다. 타겟팅과 각 옵션의 `_id`를 저장해 두세요. 나중에 타겟팅을 변경할 때 필요합니다.
```json theme={null}
{
"_id": "01JAB3XK5Q8V7M2N4P6R9T0W1Y",
"name": "News Sections",
"categories": [
{
"_id": "01JAB3XK5RA1B2C3D4E5F6G7H8",
"name": "Sports",
"type": "atomic",
"contextCount": 3,
"createdAt": "2026-10-13T01:23:45.000Z",
"updatedAt": "2026-10-13T01:23:45.000Z"
},
{
"_id": "01JAB3XK5RA1B2C3D4E5F6G7H9",
"name": "Tech",
"type": "atomic",
"contextCount": 3,
"createdAt": "2026-10-13T01:23:45.000Z",
"updatedAt": "2026-10-13T01:23:45.000Z"
}
],
"categoryCount": 2,
"createdAt": "2026-10-13T01:23:45.000Z",
"updatedAt": "2026-10-13T01:23:45.000Z"
}
```
생성 요청은 멱등(idempotent)하지 않습니다. 요청이 타임아웃되어 다시 보내야 한다면 먼저 [재시도와 중복 요청](/ko/integrations/context-targeting/errors#재시도와-중복-요청)을 확인하세요.
섹션이 바뀌면 옵션의 컨텍스트 ID를 갱신합니다. `add`와 `remove`는 요청에 적은 ID만 바꿉니다.
```bash theme={null}
curl -X PATCH https://lake.adrop.io/context-targeting/category/01JAB3XK5RA1B2C3D4E5F6G7H8 \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contexts": {
"add": ["basketball", "golf"],
"remove": ["soccer"]
}
}'
```
`200` 응답으로 수정된 옵션이 반환됩니다.
```json theme={null}
{
"_id": "01JAB3XK5RA1B2C3D4E5F6G7H8",
"name": "Sports",
"type": "atomic",
"contextCount": 4,
"createdAt": "2026-10-13T01:23:45.000Z",
"updatedAt": "2026-10-13T01:30:00.000Z"
}
```
옵션의 컨텍스트 ID 전체를 한 번에 교체하려면 [컨텍스트 ID 갱신 방법](/ko/integrations/context-targeting/options#컨텍스트-id-갱신-방법)을 참고하세요.
타겟팅을 조회해 `syncedAt`을 수정 요청이 성공한 시각과 비교합니다.
```bash theme={null}
curl "https://lake.adrop.io/context-targeting/01JAB3XK5Q8V7M2N4P6R9T0W1Y?includeCategories=false" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json"
```
```json theme={null}
{
"_id": "01JAB3XK5Q8V7M2N4P6R9T0W1Y",
"name": "News Sections",
"categoryCount": 2,
"syncedAt": 1791855005000,
"createdAt": "2026-10-13T01:23:45.000Z",
"updatedAt": "2026-10-13T01:30:06.000Z"
}
```
이전 단계의 수정은 2026-10-13T01:30:00.000Z(`1791855000000`)에 성공했습니다. `syncedAt`이 이보다 늦으므로 변경 사항은 로드됐고, 이후 몇 분 안에 광고 송출에 반영됩니다. `syncedAt`이 없거나 이보다 이르면 잠시 후 타겟팅을 다시 조회하세요. 자세한 내용은 [변경 반영 시점](#변경-반영-시점)을 참고하세요.
광고를 요청할 때 사용자가 보고 있는 페이지의 컨텍스트 ID를 `contextId`로 보냅니다. 변경 사항이 반영되면 `contextId`가 `basketball`인 광고 요청은 "Sports" 옵션에 매칭됩니다.
광고 요청에서 컨텍스트 ID가 어떻게 쓰이는지는 [문맥 타겟팅 만들기](/ko/targeting/context)를 참고하세요.
***
## 변경 반영 시점
성공한 쓰기 요청은 즉시 저장됩니다. 이어서 Adrop이 프로젝트의 문맥 타겟팅을 광고 송출용으로 로드하며, 변경 사항은 보통 몇 분 안에 광고 송출에 반영됩니다.
변경 사항이 로드됐는지는 타겟팅의 `syncedAt` 필드(epoch 밀리초)로 확인합니다.
* `syncedAt`은 해당 타겟팅의 가장 최근 로드가 시작된 시각입니다. `syncedAt`과 같거나 그 이전에 성공한 변경은 로드된 것이며, 이후 몇 분 안에 광고 송출에 반영됩니다.
* 새로 만든 타겟팅에는 `syncedAt`이 없습니다. 컨텍스트 ID를 변경(`add`, `remove`, `set`)하거나, 옵션을 추가하거나, 옵션을 이동·분리한 뒤에도 빠집니다. 보통 다음 로드가 끝나면 다시 나타납니다.
* 변경 시점에 이미 진행 중이던 로드는 `syncedAt`을 자신의 시작 시각, 즉 변경보다 이른 시각으로 설정할 수 있습니다. 그 로드에는 변경 사항이 포함되지 않았을 수 있지만, 이후 로드에는 포함됩니다.
* 이름 변경이나 삭제로는 `syncedAt`이 지워지지 않습니다.
따라서 `syncedAt`이 있는지 없는지로 판단하지 마세요. 요청이 성공한 시각을 기록해 두었다가, [타겟팅 조회](/ko/integrations/context-targeting/targetings#타겟팅-조회)에 `includeCategories=false`를 붙이는 식으로 변경 사항이 포함된 타겟팅을 조회하세요. `syncedAt`이 기록한 시각과 같거나 그보다 늦으면 변경 사항이 로드된 것입니다. `syncedAt`은 Adrop 서버 시각을 기준으로 하므로, 사용하는 서버의 시각과 차이가 날 수 있다면 여유를 두고 비교하세요.
변경 사항이 반영되기 전까지 광고 요청은 이전 컨텍스트 ID를 기준으로 매칭됩니다. 새 컨텍스트 ID는 앱이나 웹사이트가 광고 요청에 그 ID를 보내기 시작하기 전에 미리 추가하세요.
***
## 관련 문서
타겟팅 조회, 생성, 이름 변경, 삭제
옵션을 추가하고 컨텍스트 ID를 최신 상태로 유지하는 방법
옵션을 옵션 그룹의 하위 옵션으로 묶는 방법
오류 코드, 한도, 재시도 방법
API 키 발급과 관리
문맥 타겟팅과 컨텍스트 ID의 동작 방식
타겟팅을 광고 상품에 연결해 광고주에게 판매하는 방법
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.