# Prompt Monitor Integration

## When to use

Use this skill when you need to create or look up a Prompt Monitor project for an organization, or when you need to report on how a brand is showing up across LLM (large language model) answers — visibility/mention scores, individual prompt run results, or citation sources pulled from Prompt Monitor. Reach for it whenever a task asks about brand visibility, AI search presence, prompt run history, or citation tracking for a project tracked in Prompt Monitor.

## Tools

- `http-get` — read visibility scores, prompt runs, and citations
- `http-post` — create (or find-and-return) a project
- `http-request` — reserved for update/delete calls (PUT/PATCH/DELETE) if a future task requires modifying or removing project data
- `write-file` — stage large result sets (prompt run lists, citation lists) before summarizing or handing off
- `send-message` — escalate to a human when authentication fails or the integration is missing

## Playbook

1. Confirm the target organization has a Prompt Monitor project. If you don't already have a project id, create one with `http-post` against `/api/v1/projects`, sending `project[name, domain, locale, country_code, brand_keywords[]]` plus `organization[name, slug]` and `user[email, password, first_name, last_name]`. This call requires write scope and will auto-create the organization and owner user if they don't exist yet, or return the existing project if one already matches.
2. Once you have the project id, set the `X-Organization-Id` header for all subsequent reads — visibility, prompt run, and citation endpoints all require it.
3. To answer "how visible is this brand in LLM answers", call `http-get` on `/api/v1/projects/:id/visibility`, optionally passing `?days=` (default 30, max 365) to widen or narrow the trailing window. Report the overall average alongside the per-prompt breakdown.
4. To inspect the underlying evidence behind a visibility score, call `http-get` on `/api/v1/projects/:id/prompt_runs` to fetch up to 200 recent runs (LLM provider, whether the brand was mentioned, mention rank, sentiment, run time).
5. To trace which sources LLMs are citing, call `http-get` on `/api/v1/projects/:id/citations` to fetch up to 200 recent citations (URL, domain, source run).
6. If a result set is large or will be reused across steps, `write-file` it to a staging location before summarizing, rather than re-fetching or pasting the raw payload inline.
7. If a downstream task requires modifying or removing project data (not currently exposed as a documented read/create endpoint), use `http-request` with the appropriate method and confirm the response before reporting success.

## Failure modes

- A 401 or 403 response means the bearer token failed Auth Center verification or the app lacks access — stop immediately and use `send-message` to escalate to a human, naming Prompt Monitor and stating that a valid write-scoped or read-scoped token is needed.
- A missing Integration row for Prompt Monitor means no base URL/credentials are configured — do not guess a URL or invent credentials; use `send-message` to ask a human to configure the Prompt Monitor integration for the organization.
- A write action (project creation) failing with a scope error means the token lacks the "write" scope — escalate via `send-message` rather than retrying with different data.
- Never fabricate visibility scores, prompt run results, or citations when an endpoint returns an error or empty result — report the gap instead of filling it in.

## Done when

The requested visibility score, prompt run list, or citation list has been retrieved and reported (or staged via `write-file` for a large set), or a project has been created/confirmed and its id captured, with any authentication or integration failure escalated via `send-message` rather than silently worked around.