KnobaseKnobase Ads API 레퍼런스
UI를 강제하지 않는 정책 인식 후원 오퍼 결정 및 추적 링크 서비스입니다.
Knobase Ads는 서버 결정 API입니다. 표기된 추적 오퍼 또는 성공적인 no-fill을 반환합니다. 퍼블리셔의 유기적 AI 답변을 만들거나 바꾸거나 덧붙이지 않습니다.
제품 불변 조건
- Knobase는 UI 중립입니다. 컴팩트 카드, 답변 아래 카드, 패널, 사이드바, 빈 슬롯, 새 채팅 UI를 요구하지 않습니다.
- 퍼블리셔는 이미 있는 별도 클릭 가능 네이티브 표면에만 적격 오퍼를 쓸 수 있습니다.
- 렌더하는 모든 오퍼는 후원 표기, 광고주 신원, Knobase 추적 링크를 보여야 합니다.
- 그런 표면이 없으면 no-render가 정답입니다. 유기적 답변에 원본 URL이나 상업 문구를 붙이지 마세요.
- KNOBASE_API_KEY는 서버 전용이며, 폐기/교체 전까지 장기 유효하고 앱·환경에 묶입니다.
- V1 오퍼 결정 엔드포인트는 POST /v1/offers/decide뿐입니다.
- 전체 대화 기록은 받지 않습니다. 현재 메시지는 일시 처리되며 저장되지 않습니다.
- no-fill은 성공 결과입니다. no-fill, 타임아웃, 오류에서도 유기적 답변은 남아야 합니다.
구현된 V1 엔드포인트
| 메서드 | 경로 | 인증 | 용도 |
|---|---|---|---|
| POST | /v1/offers/decide | Bearer serving key | 표기된 오퍼 반환 여부 결정 |
| GET | /r/{token} | 없음 (브라우저) | 추적 클릭 리다이렉트 |
| POST | /v1/events/rendered | Bearer serving key | offer_rendered 기록 |
| POST | /v1/events/qualified-impression | Bearer serving key | qualified_impression 기록 |
| POST | /v1/events/impression | Bearer serving key | 이전 클라이언트용 별칭 |
| POST | /v1/events/conversion | Bearer serving key | 서명된 전환 기록 |
GET /v1/decisions/{id}는 같은 serving key로 결정 메타데이터를 읽을 수 있습니다. OpenAPI에 있으며 필수 연동 단계는 아닙니다.
OpenAPI와 LLM 계약
기계 판독용 OpenAPI JSON을 받거나, 코딩 에이전트용 Markdown 계약을 복사하세요. Copy for LLM은 /docs/llms.txt와 같은 텍스트입니다.