레퍼런스
이 레퍼런스는 모델 우선입니다: 리소스와 규칙에서 출발하면 엔드포인트가 예측됩니다. 엔드포인트 단위 전체 레퍼런스(~260개 엔드포인트의 요청/응답 형태)는 SSOT 결정 대기 중입니다 — 끝의 노트 참고.
핵심 리소스와 상호 관계
섹션 제목: “핵심 리소스와 상호 관계”| 리소스 | 무엇인가 |
|---|---|
| Account user | Pulsy가 아는 당신 — 당신이 누구이고 무엇에 속하는지의 정규 레코드. |
| Team | 당신이 활동하는 워크스페이스. 단일 계층 멤버십; 정확히 하나가 현재 팀. |
| Country | 팀과 짝지어 현재 범위를 형성. 데이터는 팀 + country 쌍 안에서 읽힘. |
| Account / account group | 프로필이 매달리는 Amazon 광고 계정 그룹. |
| Profile | Amazon 광고 프로필 — 광고 데이터를 당기는 단위. 허용 집합과 한 번에 하나의 활성 프로필. |
| Advertiser | DSP(프로그래매틱) 광고주 정체성, DSP·AMC 데이터에 사용. |
| AMC context | Amazon Marketing Cloud 쿼리에 필요한 해석된 brand + instance + advertiser + marketplace. |
| Chat session | 대화. 일반 챗은 답하고, action 챗은 변경도 제안 가능. |
| Action request | 캠페인에 대한 제안된 변경 — 보류로 기록, 승인 카드로 표시, 승인 후에만 적용. 모든 쓰기의 단위. |
| Report | 생성된 분석 — 사전정의 또는 커스텀 AI 리포트. |
대부분의 데이터 호출이 걷는 사슬: 당신 → 팀 + country → account/group → 허용 프로필 → 활성 프로필 → AMC context. 한 고리가 빠지면 호출은 범위를 해석할 수 없습니다.
범위, 테넌시, 그리고 예측 가능한 규칙
섹션 제목: “범위, 테넌시, 그리고 예측 가능한 규칙”- 현재 범위 = 팀 + country, 매 요청마다 계정에서 해석 — 당신이 넘기는 헤더에서 읽지 않음. 팀·country 전환은 자체 액션.
- 허용 vs. 활성 프로필. 요청은 정확히 하나의 활성 프로필 기준으로 실행(허용되면 선호 프로필, 아니면 계정 메인, 아니면 안정적 폴백). 새 세션은 숫자 반환 전에 하나를 고르라고 할 수 있음.
- 미해석 범위는 닫힌 쪽으로 실패. 팀 미해석 →
400 TEAM_CONTEXT_REQUIRED; 팀은 있으나 필요한 country 누락 →409 CURRENT_SCOPE_INCOMPLETE. 빈 결과는 종종 “데이터 없음”이 아니라 “범위 미해석”. - 404는 존재를 숨김. 당신 것이 아닌 것을 읽으면 403이 아니라 404 — Pulsy는 그것이 존재하는지조차 확인해주지 않음. (일부 레거시 표면은 여전히 403.)
- 교차 범위는 의도적으로 불가. 한 요청은 한 범위 안에서 답함; 다른 숫자를 원하면 범위를 바꿈.
인증 스킴
섹션 제목: “인증 스킴”셋이 공존합니다(무엇이 파트너 대면이 될지는 미뤄진 결정):
- Auth0 Bearer — 사용자 요청;
/userinfo로 검증하며 짧은 캐시. X-API-Key/ADMIN_API_KEY— 관리자, 크롤링, 메모리, MCP 마운트.X-Dashboard-Key— 내부 Prefect 대시보드.
엔드포인트 맵 (그룹)
섹션 제목: “엔드포인트 맵 (그룹)”~50개 라우터에 걸친 ~260개 엔드포인트, 그룹별:
- Identity / teams / connect —
me,teams, 채널, 초대, Amazon·Shopify account-connect(OAuth). - Chat —
/pulsy/action-chats(라이브 SSE 표면);/pulsy/chats(레거시 PSM); 채팅룸, 프리셋, 즐겨찾기. - Agent / campaigns — agent-campaigns, optimize-cycle, diagnose-runs, action-requests/apply, AMC.
- Reports — 주간, 커스텀 AI 리포트, 복합 리포트, 템플릿/스케줄.
- Home / inbox / notifications / support.
- Memory — 관리자 API(
X-API-Key). - Crawling, vendor-sale-report, admin/events/Auth0 webhook, Prefect dashboard, MCP 마운트 — 내부/ops 표면.
엔드포인트 단위 레퍼런스
섹션 제목: “엔드포인트 단위 레퍼런스”오늘 ai-api에는 정적 OpenAPI export가 없습니다(스펙은 런타임에 생성되며 HTTP Basic 뒤).
그래서 전체 요청/응답 레퍼런스는 SSOT 결정 대기 중 보류입니다 — 실행 중 인스턴스에서
openapi.json을 export하거나, FastAPI 라우터에서 직접 작성. _internal/needs-johnny.md에서
추적. 정해지면 위 그룹대로 이 섹션이 채워지며, placeholder만 쓰는 예시(흔한 경우 + 사람들이 걸리는
엣지 케이스 하나)를 포함합니다.