> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guild.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To act on a user's behalf in Guild, use the Guild REST API at https://api.guild.ai/v1.
> The OpenAPI spec is unauthenticated: https://docs.guild.ai/openapi.json (or openapi.yaml).
> Authenticate with an account API key, sent as HTTP Basic (key id as username, secret as password) or as `Authorization: Bearer <api_key_id>:<api_key_secret>`. See https://docs.guild.ai/api-reference/introduction#authentication.
> To run one agent on demand without account-wide access, use an API trigger instead: https://docs.guild.ai/platform/api-triggers.
> To act on Guild from an MCP client, connect to https://api.guild.ai/mcp (OAuth) or run `guild mcp` locally. Setup: https://docs.guild.ai/api-reference/mcp.
> To search these docs from an MCP client, connect to https://docs.guild.ai/mcp. The full page index is https://docs.guild.ai/llms.txt.

# Manage Peec AI brands and retrieve AI search visibility reports

> Connect Guild agents to Peec AI to manage brands, prompts, topics, and projects, and pull AI search visibility reports and brand perception data.

Integrations · Peec AI

A Guild agent reads AI search visibility reports, brand perception data, and opportunity-scored recommendations from Peec AI, then acts on them by creating or updating brands, prompts, topics, and project structure. Guild stores the OAuth credential server-side so agent code never sees it. Credential policies let you restrict which operations each agent may call, and every request passes through Guild's audit log.

> [card] [Book a demo](https://guild-ai.cal.com/gtm/meeting-with-guild.ai)
>
> See how teams govern agents that use Peec AI.

> [card] [Talk to sales](https://guild.ai/talk-to-sales)
>
> Get access to Guild, then connect Peec AI to your first agent.

## What the Peec AI integration exposes

The tools cover brand and competitor management, prompt and topic lifecycle, product catalog entries, and project configuration including teams, tags, categories, and saved views. Reporting tools return brand visibility, win rate, sentiment, shopping metrics, domain and URL citations, AI referral traffic, and agent readiness audits. Additional tools manage facts for claim checking, content optimisation actions, and the brand-perception attribute taxonomy. Tools use the prefix peec\_ai\_ and are imported from the guildai\~peec-ai package.

## How it works

**1. Open Credentials and connect**

In Guild, go to Access & setup > Credentials, click Connect, and select peec-ai. Guild sends you to Peec AI to authorize access and returns you when done.

**2. Scope the credential**

Guild supports account, workspace, member, and agent-scoped credentials. See [Credentials](https://docs.guild.ai/platform/credentials.md) to pick the scope that fits your team.

**3. Import tools into your agent**

Import PeecAiTools from the guildai\~peec-ai package and spread it into your agent's tools object. Use pick() as described in [Tool sets](https://docs.guild.ai/sdk/tools.md) to include only the tools your agent needs.

## Why Peec AI access needs governing

Peec AI projects hold competitive intelligence, brand perception data, and opportunity-scored recommendations that inform strategic decisions. A misconfigured agent could create or delete brands, archive prompts, modify the brand-perception attribute taxonomy, or invite project members at scale. Guild's credential proxy enforces ALLOW and DENY rules from [credential policies](https://docs.guild.ai/platform/credential-policies.md) before any request leaves Guild, so you can limit an agent to read-only report tools or restrict it to a single project's operations.

Credentials are injected server-side; agent code, prompts, and containers never see the OAuth token. You can scope a credential to one workspace, one member, or a single installed agent, so the Peec AI connection used by a reporting agent never serves an agent that writes to projects. Every call passes through the audit log regardless of which scope is in use.

## About the Peec AI integration

Agents can create and manage brands, competitors, products, prompts, and topics within Peec AI projects. They can retrieve AI search visibility reports, brand perception data, shopping metrics, and opportunity-scored action recommendations. Agents can also configure project structure including teams, tags, categories, and saved views. The integration is `guildai~peec-ai`.

## Authentication

* **Type:** OAuth

### Setup

**1. Connect Peec AI**

In Guild, go to **Access & setup > Credentials**, click **Connect**, select **peec-ai**, and sign in to Peec AI to authorize Guild.

See [Credentials](https://docs.guild.ai/platform/credentials.md) for workspace, member, and agent-scoped credentials.

### OAuth scopes

Scopes Guild requests in the latest published version of `guildai~peec-ai`:

| Scope |
| - |
| `default` |

## Usage

```typescript theme={null}
import { PeecAiTools } from "@guildai-services/guildai~peec-ai"
import { llmAgent } from "@guildai/agents-sdk"

export default llmAgent({
  systemPrompt: "You work with Peec AI.",
  tools: { ...PeecAiTools },
})
```

### Selecting specific tools

Tools are named with the `peec_ai_` prefix. Use [`pick()`](https://docs.guild.ai/sdk/tools#selecting-specific-tools) to include only what your agent needs.

## Tools

Tools in the latest published version of `guildai~peec-ai`:

> [accordion] All 130 tools
>
> | Tool | What it does |
> | - | - |
> | `peec_ai_add_team_members` | Put people in teams of the project's company, up to 50 team and person pairs per call. |
> | `peec_ai_archive_prompts` | Archive up to 50 prompts (sets is\_archived = true) so they stop running while keeping their chats and history intact. |
> | `peec_ai_assign_domain_classification` | Assign a built-in classification (Corporate, Competitor, Editorial, Institutional, Other, Reference, UGC, You, Related) or the name of a custom domain classification to a domain. |
> | `peec_ai_assign_url_classification` | Assign a built-in classification (Homepage, Category Page, Product Page, Listicle, Comparison, Profile, Alternative, Discussion, How-To Guide, Article, Review, Other) or the name of a custom URL… |
> | `peec_ai_copy_views` | Copy up to 50 saved views from one project into another, for example to give every client project of an agency the same dashboard. |
> | `peec_ai_create_actions` | Write up to 50 actions of the customer's own in one call, so work Peec did not suggest is tracked beside the work it did — same list, same statuses, same filters. |
> | `peec_ai_create_brand_perception_attribute_clusters` | Add custom attributes to the brand-perception Market view — the same edit the Add attribute button next to Manage attributes makes. |
> | `peec_ai_create_brands` | Create up to 50 brands (competitors or own) in a project in one call. |
> | `peec_ai_create_categories` | Create product categories. |
> | `peec_ai_create_domain_classification` | Define a new custom domain classification on a project. |
> | `peec_ai_create_facts` | Add up to 50 manual facts for a project in one call. |
> | `peec_ai_create_global_brand` | Create a brand and return its global\_brand\_id. |
> | `peec_ai_create_products` | Create catalog products (source=CATALOG) in a project — the brand's own claimed/uploaded products, as opposed to LLM products that Peec auto-detects in shopping answers. |
> | `peec_ai_create_projects` | Create up to 50 projects in one call in the company that owns project\_id, under the same plan limits and credit pool as creating them in the app. |
> | `peec_ai_create_prompts` | Create up to 50 prompts in a project in one call. |
> | `peec_ai_create_source_tags` | Create up to 50 tags for URLs and domains (source tags) in one call. |
> | `peec_ai_create_tags` | Create up to 50 tags in a project in one call. |
> | `peec_ai_create_teams` | Add up to 50 teams to the project's company. |
> | `peec_ai_create_topics` | Create up to 50 topics in a project in one call. |
> | `peec_ai_create_url_classification` | Define a new custom URL classification on a project. |
> | `peec_ai_delete_actions` | Remove up to 50 actions the customer wrote themselves. |
> | `peec_ai_delete_brands` | Delete up to 50 brands in a project. |
> | `peec_ai_delete_categories` | Delete categories by id (use list\_categories to resolve ids). |
> | `peec_ai_delete_domain_classification` | Permanently delete a custom domain classification entity. |
> | `peec_ai_delete_facts` | Soft-delete up to 50 facts in one call. |
> | `peec_ai_delete_products` | Delete products by id (use list\_products to resolve ids). |
> | `peec_ai_delete_prompts` | Delete up to 50 prompts in a project. |
> | `peec_ai_delete_source_tags` | Delete up to 50 source tags. |
> | `peec_ai_delete_tag_groups` | Delete up to 50 user-defined tag groups. |
> | `peec_ai_delete_tags` | Delete up to 50 tags in a project. |
> | `peec_ai_delete_teams` | Delete up to 50 teams the project's company created. |
> | `peec_ai_delete_topics` | Delete up to 50 topics in a project. |
> | `peec_ai_delete_url_classification` | Permanently delete a custom URL classification entity. |
> | `peec_ai_edit_brand_perception_attribute_clusters` | Rename and delete brand-perception attributes, move terms between attributes and unassign terms from theirs — the same edits the Manage attributes screen makes. |
> | `peec_ai_edit_optimize_content` | Rewrite passages of the article behind a content-optimisation or PDP action, up to 50 in one call (target 40 or fewer). |
> | `peec_ai_finalize_prompt_suggestions` | Resolve prompt suggestions listed by list\_prompt\_suggestions, in one pass over a reviewed set: ids in accepted\_ids become tracked prompts and promote their topics into the project, ids in… |
> | `peec_ai_generate_prompt_suggestions` | Generate prompt suggestions for a project — the same generation Prompt discovery runs in the app. |
> | `peec_ai_generate_topics` | Compose candidate topics for the project from its brand profile — the same composition Prompt discovery runs in the app. |
> | `peec_ai_get_action` | Read one action by an id from list\_actions: what to do, the content brief when there is one, and the competitor demand behind it. |
> | `peec_ai_get_actions` | Get Peec's opportunity-scored action recommendations for improving brand visibility in AI search engines. |
> | `peec_ai_get_agent_readiness` | How ready every own brand domain and every competitor brand domain of the project are for AI agents, from Peec's agent readiness audit of each domain. |
> | `peec_ai_get_agent_visits` | Aggregate AI agent visit counts from access logs over a date range. |
> | `peec_ai_get_ai_referrals` | People who arrived on the project's own website from an AI assistant, measured by the project's connected Google Analytics property. |
> | `peec_ai_get_brand_perception_attribute_history` | How one brand's prominence on each brand-perception attribute has moved over time — the series the Market view's history chart plots. |
> | `peec_ai_get_brand_perception_attribute_rankings` | How the project's own brand ranks against competitors for each brand-perception attribute. ranking is the own brand's position among every brand scored for the attribute, ordered by average… |
> | `peec_ai_get_brand_perception_attribute_sources` | The sources feeding one brand-perception attribute: the URLs AI answers cited when describing the brand with this attribute. |
> | `peec_ai_get_brand_perception_brand_attributes` | How AI models describe the project's own brand: attributes (e.g. "Luxury", "Racing Heritage") with a prominence score. score is 0-100 — the attribute's average prominence per AI answer; higher means… |
> | `peec_ai_get_brand_perception_claim_sources` | The pages behind one fact-checked claim, each with the role it earned. |
> | `peec_ai_get_brand_perception_competitive_breakdown` | The full competitive breakdown matrix: for every brand-perception attribute, the average prominence of each brand (the project's own brand and its competitors) across AI answers. score is 0-100 —… |
> | `peec_ai_get_brand_perception_fact_checking_verdicts` | The claims AI models make about the project's brand, each judged against one of the project's facts. |
> | `peec_ai_get_brand_perception_objections` | The recurring arguments AI models make against the project's brand when a buyer is deciding. score is average prominence per AI answer from 0 to 100; display it as-is. members contains the raw… |
> | `peec_ai_get_brand_perception_objection_sources` | The sources AI answers cited when asked about one objection. |
> | `peec_ai_get_brand_report` | Get a report on brand visibility, win rate, sentiment, and position across AI search engines. |
> | `peec_ai_get_chat` | Deprecated: use get\_chats, which reads up to 100 chats per call and returns the same fields for each. |
> | `peec_ai_get_chats` | Get the full content of chats by ID (a chat is one AI engine's response to one prompt on one date). |
> | `peec_ai_get_chats_report` | Aggregate counts and rich-answer-feature shares over a project's chats for a date range. |
> | `peec_ai_get_domain_report` | Get a report on source domain visibility and citations across AI search engines. |
> | `peec_ai_get_links_report` | Get a report on the domains AI answers linked to in their own text. |
> | `peec_ai_get_optimize_content` | Read the article behind a content-optimisation or PDP action, as the user sees it on the Optimize content screen: the current text and the suggestions listed beside it. |
> | `peec_ai_get_product` | Get one product's detailed metrics over a date range — the drill-down companion to list\_products, which returns a thin row per product. |
> | `peec_ai_get_project_profile` | Read a project's brand profile — the description, industry, brand-identity adjectives, target markets, audience distribution, and product/service list that Peec uses to generate prompt suggestions. |
> | `peec_ai_get_prompt_suggestion_generation` | Read the authoritative status of a run returned by generate\_prompt\_suggestions. |
> | `peec_ai_get_shopping_attributes` | Compare the qualitative characteristics and features that AI engines associate with a product (or the whole catalog) against competitors. |
> | `peec_ai_get_shopping_summary` | Return catalog-wide shopping metrics over a date range — avg\_visibility, avg\_win\_rate, and avg\_position, each with a period-over-period delta — as a single aggregated row across the filtered scope. |
> | `peec_ai_get_shopping_trend` | Return a per-bucket shopping time series (visibility, win\_rate, avg\_position, sov) for specific products or global brands over a date range. |
> | `peec_ai_get_url_content` | Returns content Peec previously extracted from a URL for downstream analysis. |
> | `peec_ai_get_url_content_diff` | Returns a unified diff between two stored snapshots of a URL's content. |
> | `peec_ai_get_url_report` | Get a report on source URL visibility and citations across AI search engines. |
> | `peec_ai_get_view` | Read one saved view: its KPI metrics, its filters, and its rows of widgets, top to bottom and left to right, with the settings saved on each chart. |
> | `peec_ai_import_url_tags` | Tag a list of up to 5000 URLs in one call, such as a campaign's pages from a spreadsheet, and optionally set each URL's classification. |
> | `peec_ai_invite_project_members` | Invite up to 50 people to the project by email in one call. |
> | `peec_ai_join_teams` | Put the user making this call in teams of the project's company, up to 50 teams per call. |
> | `peec_ai_leave_teams` | Take the user making this call out of teams of the project's company, up to 50 teams per call. |
> | `peec_ai_list_action_platforms` | The external sites a project has actions on, alphabetically — the values `list_actions` accepts in its `platforms` filter. |
> | `peec_ai_list_actions` | List a project's actions — the same set the Actions page shows. |
> | `peec_ai_list_bots` | List all known AI crawler/agent bots that visit the site (e.g. |
> | `peec_ai_list_brand_perception_attribute_clusters` | The editable taxonomy behind the brand-perception Market view: every attribute with its cluster\_id, its name and the terms grouped under it. |
> | `peec_ai_list_brands` | List brands tracked in a project — includes the user's own brand and competitors. |
> | `peec_ai_list_brand_social_channels` | List the social channels configured for a project's own brand and competitors. |
> | `peec_ai_list_categories` | List a project's product categories. |
> | `peec_ai_list_chats` | List chats (individual AI responses) for a project over a date range. |
> | `peec_ai_list_domain_classifications` | List the custom domain classifications defined for a project. |
> | `peec_ai_list_facts` | List the facts a project uses to check claims found in AI answers. |
> | `peec_ai_list_global_brands` | Search Peec's global brand catalog — the shared registry of real-world brands (e.g. |
> | `peec_ai_list_merchants` | List the merchants (sellers, e.g. |
> | `peec_ai_list_model_channels` | List the AI engine channels tracked by Peec. |
> | `peec_ai_list_models` | Deprecated — prefer list\_model\_channels, which returns stable channel IDs that survive model upgrades. |
> | `peec_ai_list_products` | List a project's products with headline metrics over a date range, filtered by the shopping filter pack. |
> | `peec_ai_list_project_members` | List the people who can open the project, sorted by name. |
> | `peec_ai_list_projects` | List active projects the authenticated user has access to. |
> | `peec_ai_list_prompts` | List prompts (conversational questions tracked daily across AI engines) in a project. |
> | `peec_ai_list_prompt_suggestions` | List a project's prompt suggestions — prompts generated by Prompt discovery and awaiting review, which are not tracked and produce no data until accepted. |
> | `peec_ai_list_referral_sources` | Every AI assistant Peec can attribute referral traffic to, whether or not a project has seen traffic from it. |
> | `peec_ai_list_search_queries` | List the general web-search queries an AI engine fanned out to while answering prompts in a project over a date range — the text sub-queries it sent to a search index, NOT product/shopping lookups… |
> | `peec_ai_list_shopping_demand` | Rank the query terms that drive shopping demand by how many distinct chats they appear in, with a trend vs a comparison window. |
> | `peec_ai_list_shopping_performance` | List products or categories (via entity\_type) ranked by shopping performance over a date range. |
> | `peec_ai_list_shopping_queries` | List the product/shopping queries an AI engine fanned out to while answering prompts in a project over a date range. |
> | `peec_ai_list_source_tags` | List the tags a project puts on URLs and domains (source tags), e.g. affiliate, partner or a campaign name. |
> | `peec_ai_list_tag_groups` | List the user-defined tag groups in a project, each with its shared color and tag count. |
> | `peec_ai_list_tags` | List tags in a project. |
> | `peec_ai_list_teams` | List the function teams of the project's company, such as SEO, PR or Content, with their members. |
> | `peec_ai_list_topics` | List topics in a project. |
> | `peec_ai_list_url_classifications` | List the custom URL classifications defined for a project. |
> | `peec_ai_list_url_content_versions` | Lists the stored snapshots of a URL's content, newest first, for any URL Peec has scraped. |
> | `peec_ai_list_views` | List the saved views (custom dashboards of widgets) in a project that the user can open: their own, and those shared with the project. |
> | `peec_ai_read_doc` | Read the full markdown content of a single Peec documentation page. |
> | `peec_ai_remove_team_members` | Take people out of teams of the project's company, up to 50 team and person pairs per call. |
> | `peec_ai_request_agent_readiness_audits` | Queue Peec's agent readiness audit for up to 50 of the project's own brand domains, so get\_agent\_readiness reflects the site as it is now. |
> | `peec_ai_resolve_optimize_content_suggestions` | Apply or dismiss the suggestions on a content-optimisation or PDP action, up to 50 in one call. |
> | `peec_ai_search_docs` | Search the Peec docs ([https://docs.peec.ai](https://docs.peec.ai)) and return the most relevant pages. |
> | `peec_ai_set_brand_social_channels` | Replace the complete social-channel list for up to 50 brands. |
> | `peec_ai_set_project_profile` | Update the project's own brand-identity profile — its industry, target audience, tone, and similar descriptive fields. |
> | `peec_ai_unarchive_prompts` | Unarchive up to 50 prompts (sets is\_archived = false), reactivating them so they resume running. |
> | `peec_ai_unassign_domain_classification` | Clear the classification override on a whole domain (operates on a domain, e.g. "example.com" — for a single URL use unassign\_url\_classification), restoring the heuristic classification. |
> | `peec_ai_unassign_url_classification` | Clear the classification override on a single URL (operates on one full URL — for a whole domain use unassign\_domain\_classification), restoring the heuristic classification. |
> | `peec_ai_update_actions` | Rewrite the fields a customer owns on up to 50 actions — the title, the description, the notes, the steps, who it is on and when it is due. |
> | `peec_ai_update_actions_status` | Move up to 50 actions to a status, the same ones the Actions page writes: `ACCEPTED` to take one on, `REJECTED` to decline it, `COMPLETED` to record that the work is done, `PENDING` to put a resolved… |
> | `peec_ai_update_action_steps` | Record which of an action's steps are done, across up to 50 actions in one call. |
> | `peec_ai_update_brands` | Update up to 50 brands in one call (name, regex, aliases, domains, color per item). |
> | `peec_ai_update_categories` | Rename and/or move categories by id (use list\_categories to resolve ids). |
> | `peec_ai_update_facts` | Update the wording or active state of up to 50 facts in one call. |
> | `peec_ai_update_products` | Update up to 1000 products by id in one call (use list\_products to resolve ids). |
> | `peec_ai_update_prompts` | Update the topic, tags, location and/or fact-checking selection of up to 50 prompts in one call. |
> | `peec_ai_update_prompt_suggestions` | Edit up to 50 pending prompt suggestions from list\_prompt\_suggestions before finalizing: rewrite the text and/or replace the tag set per item. |
> | `peec_ai_update_source_tag_assignments` | Add and remove source tags on up to 50 URLs and 50 domains in one call. |
> | `peec_ai_update_source_tags` | Rename or recolor up to 50 source tags (the tags on URLs and domains). |
> | `peec_ai_update_tag_groups` | Rename and/or recolor up to 50 user-defined tag groups in one call. |
> | `peec_ai_update_tags` | Update up to 50 tags in one call (name, color, and/or group per item). |
> | `peec_ai_update_teams` | Rename up to 50 teams the project's company created. |
> | `peec_ai_update_topics` | Rename up to 50 topics in one call. |

## Frequently asked questions

> [accordion] Does the integration use API keys or OAuth to connect Peec AI?
>
> It uses OAuth. During setup you sign in to Peec AI to authorize Guild, and Guild stores the resulting credential server-side. The catalog entry records the auth type as OAuth.

> [accordion] Can I stop an agent from deleting brands or prompts while still letting it read reports?
>
> Yes. Write a DENY rule in a [credential policy](https://docs.guild.ai/platform/credential-policies.md) that targets operations such as peec\_ai\_delete\_brands and peec\_ai\_delete\_prompts, then add an ALLOW rule for the reporting operations you want to permit. The proxy enforces DENY before ALLOW, so the deletions are blocked even if a broader ALLOW rule also matches.

> [accordion] Can an agent react to Peec AI webhook events?
>
> Not yet. The catalog entry for guildai\~peec-ai lists no webhook events, so event-driven triggers from Peec AI are not available through this integration.

> [accordion] How do I give one agent its own Peec AI credential without affecting other agents?
>
> Connect a dedicated credential from the installed agent's page or from the workspace Credentials page under the dedicated option. Guild stores it under the account that owns the workspace and never offers it to other agents or workspaces, as described in [Credentials](https://docs.guild.ai/platform/credentials.md).

## Put a governed agent on Peec AI this week

> [card] [Book a demo](https://guild-ai.cal.com/gtm/meeting-with-guild.ai)
>
> See how teams govern agents that use Peec AI.

> [card] [Talk to sales](https://guild.ai/talk-to-sales)
>
> Get access to Guild, then connect Peec AI to your first agent.

## Related

**Also runs on Guild:** [AWS CloudWatch](https://docs.guild.ai/integrations/aws-cloudwatch.md) · [Datadog](https://docs.guild.ai/integrations/datadog.md) · [Google Logging](https://docs.guild.ai/integrations/google-logging.md) · [New Relic](https://docs.guild.ai/integrations/newrelic.md)

**Read:** Docs: [Credential policies](https://docs.guild.ai/platform/credential-policies.md) · [Credentials](https://docs.guild.ai/platform/credentials.md) · [Tools in agents](https://docs.guild.ai/sdk/tools.md)
