Peec AI MCP Server
for AI Agents

Record work the customer decided to do themselves as actions, in the same shape as the ones Peec generates, so they sort, filter and move through the same statuses. The kind picked decides an action's type and group. The linked topic and prompts are resolved against the project, and an item naming one it does not hold lands in `rejected` on its own — the batch never fails as a whole.

The project's actions, the ones Peec generated and the ones the customer wrote themselves alike: what to do, on which page or site, and how much impact it is expected to have if it is done. `created_by` says which of the two an action is, and only a customer's own can be deleted or reshaped. Filters combine with AND, except `targets`, `groups`, `archetypes` and `platforms`, which combine with OR across the four. The action detail endpoint carries a single action's steps, brief, evidence and impacted prompts.

One action in full: what to do, the fields the customer owns on it — notes, priority, assignee, due date, tags and repeat — the steps to work through, the content brief when there is one with its sections, the competitor demand behind it, the prompts it affects and the terms competitors use on the topic. A site audit action carries no brief and no opportunity, and its description and steps are the whole fix. An id this project has no published action for is a 404, whether it belongs to another project, to an action type this API does not publish for the project, or to nothing at all. A content optimisation's article, suggestions and score are not returned here, and the Customer API publishes no endpoint that returns them.

Rewrite the fields a customer owns, on actions they wrote or ones Peec generated. An edit is stored beside the generated wording rather than in it, so a regeneration cannot discard it. Only a customer's own action can change shape: the type and group of a generated one say what Peec found, and an item trying to move them lands in `rejected`. A field the item leaves out keeps what it held; `null` clears the ones that can be cleared, and an item naming no field at all is rejected rather than recorded as an edit. Ids the project publishes no action under are returned in `skipped` — the batch never fails as a whole. A content optimisation is reachable only on a project with content optimisation enabled; elsewhere its id is returned in `skipped`.

Remove actions the customer wrote themselves. A generated action reads here exactly as a missing one does and lands in `skipped`: those are declined or dismissed through the status endpoint instead, so the list keeps a record of what Peec suggested and the customer turned down.

Create a new brand within a project

List the brands of a project

Update a brand within a project. Changes to name, regex, or aliases trigger a background recalculation of metrics. While recalculation is in progress, further updates to these fields are blocked (409 Conflict) until it completes.

Delete a brand within a project.

List the social channels configured for a project, optionally filtered to one brand.

Replace the complete list of social channels configured for a brand. Pass an empty list to remove them all.

Create product categories. Each item takes a `name` and an optional `parent_id` (omit or null for a top-level category). Items apply in order. Returns per-item results { created, rejected } — the batch never fails as a whole. Rejection reasons: parent_not_found, name_conflict (a sibling already has that name).

List a project's product categories. Each row carries its full `path` and its `parent_id`, so the flat list reconstructs the category tree. Use the returned `id` as a `category_id` when creating, updating, or assigning products.

Rename and/or reparent categories by id. Each item sets `name` (rename), `parent_id` (move; null = promote to top level), or both — at least one is required. A combined edit is applied move-then-rename. Returns per-item results { updated, rejected } — the batch never fails as a whole. Rejection reasons: not_found, name_conflict, invalid_move (would nest a category inside itself).

Delete categories by id. Each one's child categories and products move up to its parent, then it is removed. Returns per-item results { deleted, rejected } — the batch never fails as a whole. Rejection reasons: not_found, name_conflict (a child moving up would clash with an existing sibling name).

Create products. Each item is independent: valid products are created and per-item failures are returned in `rejected`, so the batch never fails as a whole. Optional `category_ids` assigns the product to categories.

List a project's products with headline metrics (mention_count, win_count, avg_position, avg_rating, visibility, share_of_voice) over the date range, filterable by category, merchant, brand, country, model channel, topic, and tag. Paginated.

Get one product's detail over a date range: headline metrics (visibility, win_rate, avg_position, avg_rating, mention_count) plus a delta for each against the immediately preceding equal-length period, the catalog metadata (brand, description, image, source, first-seen date), the effective price range with any overrides, and the median AI-mention price. Visibility is divided by the product's relevant-prompt chats, not all shopping chats. avg_rating is the mean 0–5 star rating across the product's AI mentions (null when none carried a rating). Returns data: null when the product is not in the project.

Update products (name, description, image, price overrides, categories). Each item is independent: items with nothing to apply (not found, no changes, duplicate id) are reported in `skipped`, and unsatisfiable changes (name conflict, unknown category) in `rejected`, so the batch never fails as a whole.

Delete products. Ids that don't exist in the project are returned in `skipped`.