# 어딧지 (auditG) — AI 에이전트 운영 안내

> 이 문서는 AI 에이전트가 읽는 문서입니다. 사용자가 "auditg.ai 연결해서 봐봐", "우리 사이트 점검 결과 보여줘" 같이 말하면 아래 순서대로 스스로 진행하세요. 사람에게 되묻는 것은 "어느 사이트(도메인)인지"와 "API 토큰" 두 가지뿐입니다.

## 0. 30초 요약
- 어딧지는 웹사이트가 **네이버·구글 검색**과 **AI 답변(ChatGPT·Perplexity·Gemini·Claude)** 에서 어떻게 보이는지 점검하고 고칠 순서를 주는 서비스입니다.
- 로그인 없이 되는 것: **회사 공개 보고서**(도메인만 있으면 SEO·AEO·GEO 점수·경쟁사·FAQ) — 아래 1단계.
- 토큰이 있으면 되는 것: 그 조직의 프로젝트 전체(점검 요약·이슈·검색어 순위·경쟁사·AI 노출·콘텐츠 운영(통합 글감·원고·배포처)·링크·판정·과제·방문 분석) — 아래 2단계. 조회는 **저장된 결과만** 읽고 새 수집을 하지 않습니다. 쓰기 토큰이면 [write] 도구 9개가 더 됩니다 — 메모·확정·제목 수준 5개 + 원고 만들기/고치기 + **연결된 채널 배포**(앱의 [올리기]와 같은 길, 아래 2-1 규칙).

## 1. 토큰 없이 — 공개 회사 보고서 (인증 없음)
1) 사용자가 준 도메인으로 바로 조회: `GET https://auditg.ai/api/public/company/{domain}`
   - 응답: `{domain, name, scores:{seo,aeo,geo,…}, industry, region, competitors, siteFaq, keywords, extras, locked:[…]}`. `redirectTo` 가 오면 그 도메인으로 다시 조회.
   - 404 = 아직 기록 없음 → 2) 로.
2) 없으면 만들기(무료 구조 진단, 1분 안팎): `POST https://auditg.ai/api/public/company/lookup` body `{"q":"example.co.kr"}` → `{domain, created}` 또는 회사명이면 `{matches:[…]}`. 그 뒤 1) 을 다시 호출.
   - 한도: IP 당 분당 4회·하루 40회. 회사명만 알면 `GET https://auditg.ai/api/public/company-search?q=회사명` 로 후보를 찾으세요.
3) 사람에게 보여 줄 링크: `https://auditg.ai/company/{domain}` (웹 보고서) · `https://auditg.ai/company/{domain}/report` (문서형).
4) 문의 남기기(사용자가 원할 때만, 보내기 전에 내용 확인받기): `POST https://auditg.ai/api/public/contact` `{name, email, phone?, company?, message, domain?}` → `{id, receiptUrl}`.

## 2. 토큰이 있을 때 — 조직 프로젝트 조회 (write 토큰은 원고·배포까지 — 2-1 규칙)
- 토큰 발급 위치(사용자에게 안내): 앱 로그인 → 더보기 › **API·MCP** → 토큰 만들기 (형식 `ss_…`). 토큰을 코드·문서에 남기지 마세요.
- **MCP 서버(권장)**: `https://auditg.ai/mcp` — Streamable HTTP, 헤더 `Authorization: Bearer ss_…`. 도구 96개(조회 87 + [write] 9 — 링크 만들기 8탭·검색어 상세·화면 통로·배포 창구까지, 목록은 `GET https://auditg.ai/mcp/tools`) + 리소스(프로젝트 요약) + 프롬프트(`weekly_review`, `fix_first_three`, `ai_visibility_gap`, `content_plan_week`, `link_outreach_batch`).
- **REST v1(대안)**: 기본 주소 `https://auditg.ai/api/v1`, 문서 `https://auditg.ai/api/v1/openapi.json` (Swagger `https://auditg.ai/api/v1/docs`). 조회는 GET(+ 읽기 성격 POST `/keyword-intent`), [write] 9개는 PATCH/PUT/POST. 토큰당 분당 60회.
- 첫 호출 순서: `GET /api/v1/projects` → 사용자가 말한 도메인과 맞는 `pid` 고르기 → `GET /api/v1/projects/{pid}`(7축 점수·KPI) → 질문에 따라 아래 도구.

| 사용자가 묻는 것 | REST v1 | MCP 도구 |
|---|---|---|
| 지금 상태·점수 | `/projects/{pid}` | `get_summary` |
| 뭘 먼저 고치나 | `/projects/{pid}/issues`, `/projects/{pid}/actions` | `get_issues`, `get_action_plan` · 프롬프트 `fix_first_three` |
| 검색어 순위·변화 | `/projects/{pid}/keywords`, `/projects/{pid}/positions?engine=google|naver` | `get_keywords`, `get_positions` |
| 경쟁사 | `/projects/{pid}/competitors` | `get_competitors` |
| AI 답변에 우리가 나오나 | `/projects/{pid}/ai-visibility` | `get_ai_visibility` · 프롬프트 `ai_visibility_gap` |
| 평판·뉴스 | `/projects/{pid}/reputation`, `/projects/{pid}/news` | `get_reputation`, `get_news` |
| 무슨 글을 쓸까(글감) | `/projects/{pid}/ideas?verdict=new`, `/ideas/stats` | `list_ideas`, `ideas_stats` · 프롬프트 `content_plan_week` |
| 원고 상태·성과 | `/projects/{pid}/drafts`, `/drafts/{did}/funnel`, `/content/{did}` | `list_drafts`, `get_draft_funnel`, `get_draft` |
| 어디에 뿌리나(배포처) | `/projects/{pid}/targets?status=pending`, `/newsjack`, `/reporter-queries` | `list_targets`, `get_newsjack`, `get_reporter_queries` |
| 링크 | `/projects/{pid}/link-opportunities`, `/link-targets`, `/anchor-recipe?topic=`, `/backlink-health`, `/entity-presence` | `get_link_opportunities`, `get_link_targets`, `get_anchor_recipe`, `get_backlink_health`, `get_entity_presence` · 프롬프트 `link_outreach_batch` |
| AI 가 우리를 추천하나 | `/projects/{pid}/geo/tiers`, `/geo/platform-gap`, `/fanout` | `get_geo_tiers`, `get_ai_platform_gap`, `get_fanout_coverage` |
| 검색어의 의도·채널 | `POST /projects/{pid}/keyword-intent`, `/keyword-candidates` | `keyword_intent`, `get_keyword_candidates` |
| 어느 시장에서 경쟁할지(메인 키워드) | `/projects/{pid}/market-position` | `get_market_position` |
| 연결된 채널·올릴 수 있는지 | `/projects/{pid}/publish/channels` | `list_publish_channels` |
| 원고 배포(예약·승인 요청) | `POST /projects/{pid}/drafts/{did}/publish`, `/publish/status`, `POST /publish/items/{itemId}/cancel` | [write] `publish_draft`, `get_publish_status`, [write] `cancel_scheduled` |
| 원고 만들기·고치기 | `POST /projects/{pid}/drafts`, `PUT /drafts/{did}` | [write] `create_draft`, `update_draft` |
| 사람이 봐야 할 판정 | `/projects/{pid}/decisions` | `get_decisions` · 확정은 [write] `record_decision_outcome` |
| 방문·히트맵·세션 | `/projects/{pid}/analytics`, `/heatmap`, `/sessions` | `get_analytics`, `get_heatmap`, `list_sessions` |
| 점검이 도는 중인지 | `/projects/{pid}/run-status` | `run_status` |
| 검색 여정·브랜드 검색량 | — | `search_sequence`, `brand_search` |
| 주간 리뷰 한 번에 | — | 프롬프트 `weekly_review` |
| 위 표에 없는 앱 화면(도메인 개요·AI 노출 히트맵·추적할 질문 등 120여 개) | `/projects/{pid}/screens` → `/screens/{view}`, `/screen-data?route=` | `list_screens` → `get_screen_data` (앱 화면과 같은 데이터, 읽기 전용·저장본만) |

## 2-1. 배포 규칙 (publish_draft) — 앱과 같은 관문
- 먼저 `list_publish_channels` 로 채널을 보세요. `state: ready` 인 채널만 API 로 올릴 수 있고, `approvalMode` 가 그 채널의 관문입니다.
- `approvalMode: auto` = 사용자가 앱의 자동 배포 탭에서 그 채널을 **자동 게시로 직접 켠** 경우 — 예약 시각(`at`, 비우면 몇 분 안)에 자동 게시 주기가 보냅니다(`scheduled`).
- 그 밖(승인 뒤 게시·기본값·자동 게시 꺼짐·운영 정책) = `approve` — 운영실 **승인 대기**에만 들어가고(`queued_for_approval`), 사람이 앱에서 승인해야 나갑니다. API 로는 승인·승인 방식 변경·채널 연결을 할 수 없습니다.
- 네이버 블로그·유튜브·이메일·보도자료는 사람이 직접 올리는 채널(`rejected` + `manual` 복사·묶음 안내), 위키·커뮤니티·Q&A(지식iN·카페·레딧 등)는 어떤 경우에도 자동으로 올리지 않습니다.
- 재시도할 때는 같은 `idempotencyKey` 를 쓰세요(같은 원고·채널·시각은 키가 없어도 한 번만 들어갑니다). 결과·주소는 `get_publish_status`(jobId 또는 draftId), 아직 안 나간 것은 `cancel_scheduled`.
- 배포는 사용자가 "올려/예약해"라고 말했을 때만, 부르기 전에 원고·채널·시각을 한 줄로 확인받으세요.

## 3. 결과를 사람에게 말할 때의 규칙
- 점수는 0~100, 축은 SEO(검색 기본기)·AEO(AI 가 답으로 뽑을 수 있는 형태)·GEO(실제 AI 답변 노출 실측)·UX·네이버·구글·브랜드. "좋다/나쁘다" 대신 숫자·순위·근거 페이지를 그대로 전하세요.
- 이슈는 심각도(critical/major/minor) 와 축이 붙어 있습니다. 먼저 고칠 3가지는 심각도 → 영향 페이지 수 순.
- 수치를 지어내지 마세요. 응답에 없는 값은 "확인 불가"로 말하세요. 공급사·수집 방식은 응답에 없으니 추측해서 말하지 마세요.
- 점검 실행·승인·설정·채널 연결은 이 API 로 할 수 없습니다 — 앱에서 사람이 합니다. 배포는 위 2-1 규칙대로만 나갑니다. write 토큰의 [write] 도구(원고 만들기 `create_draft` · 고치기 `update_draft` · 배포 `publish_draft` · 취소 `cancel_scheduled` · 글감 메모 `set_idea_note` · 선별 확정 `override_idea_triage` · 판정 결과 `record_decision_outcome` · 초안 제목/메타 `patch_draft` · 내부 링크 숨기기 `dismiss_internal_link`)도 사용자가 그렇게 하라고 말했을 때만 부르고, 부르기 전에 무엇을 바꾸는지 한 줄로 확인받으세요. 사용자가 원하면 앱 화면 주소를 알려 주세요: `https://auditg.ai/p/{pid}/{view}` (view 예: dashboard, checklist, positions, competitors, ai-overview, ideas, drafts, targets, link-building).

## 4. 자주 쓰는 한 줄 예시
- "auditg.ai 연결해서 uxi.co.kr 봐봐" → 1단계: `GET /api/public/company/uxi.co.kr` → 점수 3개·업계 순위·경쟁사 5곳·FAQ 를 요약, 링크 `/company/uxi.co.kr` 첨부.
- "우리 프로젝트에서 이번 주 고칠 것" → 2단계: `/api/v1/projects` → pid → `/issues` 상위 3개 + `/actions`.
- "AI 검색에 우리가 왜 안 나와?" → `/ai-visibility` 의 질문별 언급·인용 출처를 보고, 인용된 경쟁사 페이지와 우리 페이지의 차이를 말하기. `/geo/platform-gap` 으로 우리가 없는 출처 플랫폼도.
- "이번 주 뭐 쓰지?" → 프롬프트 `content_plan_week` 또는 `/ideas?verdict=new` + `/drafts` 의 병목(funnel.stage) 을 합쳐 5개 고르기.

## 5. 기계용 진입점
- MCP 매니페스트: `https://auditg.ai/.well-known/mcp.json`
- OpenAPI: `https://auditg.ai/api/v1/openapi.json`
- 사이트 요약(llms.txt): `https://auditg.ai/llms.txt`
- 이 문서: `https://auditg.ai/agents.md`