shop.agents

List this shop's AI agents, which are on and how they send

Read-onlyRead budget

REST

Shipping

POST /api/v1/shop/agents

MCP tool

Live

shop.agents

Exposed on: REST API · Shop MCP server · Claude connector · Dash (in-app copilot) · Zapier. Part of the Shop domain.

Operating contract

The AI agents this product ships, with whether this shop has each one switched on and — for the ones that message people — whether it sends on its own or queues a draft.

mode IS THE FIELD THAT MATTERS AND IT IS OFTEN MISREAD. autopilot means the agent SENDS TO CUSTOMERS WITHOUT ANYBODY LOOKING. draft_first means it writes and waits for a person to approve. An agent described as 'on' without saying which of those it is has been described misleadingly.

agents_paused: true IS A SHOP-WIDE STOP and it overrides everything below it: no agent sends, whatever its own switch says. Read it first, exactly as automations.list's master switch is read first.

enabled: false on an agent that needs messaging or voice may mean the shop wants it and has not finished the setup, rather than that it decided against it. This read says which agents are on, not why one is off.

READ ONLY. Enabling an agent, or moving one from draft-first to autopilot, hands a machine the shop's voice with its customers. That is the decision this whole registry is most careful about, and it is not one a machine makes for a shop.

This is the product's own agent roster crossed with this shop's settings, returned whole, so nothing is truncated.

Who may call it

Permission: shop.manageThe caller must hold shop.manage at the ACT level. A read-only dashboard grant on the same section is refused.
Plan: Every planNo plan gate. Available on every Service VIN plan.
Retries: naturalNaturally idempotent — running it twice leaves the same world as running it once. A retrying integration needs no key.
Rate class: readCounted against the read budget — the widest of the four.

Input

Field	Type	Description
enabled_only	boolean	True returns only agents this shop has switched on.

Output

Field	Type	Description
agents_paused	boolean	—
items	object[]	—
items[].key	string	—
items[].name	string	—
items[].tagline	string	—
items[].trigger	string	—
items[].channel	string	—
items[].enabled	boolean	—
items[].mode	string	—
items[].needs_messaging	boolean	—
items[].needs_voice	boolean	—
items[].beta	boolean	—
enabled_count	number	—
autopilot_count	number	—

Examples

Built from this capability's own schema — required fields and the ones carrying a default, and nothing invented. Paste one and it validates.

curl

export SERVICEVIN_API_KEY=svk_live_…

curl -X POST https://www.servicevin.com/api/v1/shop/agents \
  -H "Authorization: Bearer $SERVICEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

TypeScript (fetch)

const res = await fetch("https://www.servicevin.com/api/v1/shop/agents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SERVICEVIN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});

// Success and failure are both envelopes. Switch on error.code, never
// on error.message — the codes are stable, the messages are for people.
const payload = await res.json();
if (!res.ok) throw new Error(payload.error.code);
const data = payload.data;

Python (requests)

import os, requests

res = requests.post(
    "https://www.servicevin.com/api/v1/shop/agents",
    headers={"Authorization": f"Bearer {os.environ['SERVICEVIN_API_KEY']}"},
    json={},
    timeout=30,
)
payload = res.json()
if not res.ok:
    raise RuntimeError(payload["error"]["code"])
data = payload["data"]

MCP tools/call — https://www.servicevin.com/api/mcp

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "shop.agents",
    "arguments": {}
  }
}

Refusals

The four gates run in this order on every surface, and the order is not arbitrary — see Authentication.

Status	Code	When
404	`not_found`	The id is unknown, or the feature is not enabled for this account. Deliberately the same answer for both.
403	`forbidden`	This login does not hold shop.manage.
422	`validation_error`	An argument was wrong. The message names the field.
429	`rate_limited`	Too many read calls. Back off and retry.
500	`internal_error`	Something failed on our side. Nothing was changed.

Operating contract#

Who may call it#

Input#

Output#

Examples#