Does AlleyPulse have an API and MCP server for AI agents?

What can an AI assistant do with AlleyPulse?

It reads the same weekly issue you get by email, so you can ask your assistant instead of opening the inbox. It cannot change anything, and it only sees your own shops.

Version

v1, read only, included with every shop subscription

REST base address

https://api.alleypulse.com/v1

MCP server

https://api.alleypulse.com/mcp over streamable HTTP

Sign in

Bearer API key, read only. OAuth for MCP clients is not part of v1.

Rate limit

60 requests per minute per key

Data

The same weekly issues as the email. Weekly, not real time.

Machine readable

An OpenAPI 3.1 file at /v1/openapi.json and a llms.txt file.

How do I make the first request?

Create a read only key on the API and MCP screen in the app, then send it as a bearer token. These examples use the example key ap_live_EXAMPLE, and example shop and issue ids.

# Example only. The key is a placeholder: use your own key.
curl https://api.alleypulse.com/v1/shops/shp_EXAMPLE01/issues/latest \
  -H "Authorization: Bearer ap_live_EXAMPLE"

// Example only. The key is a placeholder: use your own key.
const res = await fetch(
  "https://api.alleypulse.com/v1/shops/shp_EXAMPLE01/issues/latest?tier=A",
  { headers: { Authorization: "Bearer ap_live_EXAMPLE" } }
);
if (!res.ok) throw new Error((await res.json()).error.message);
const issue = await res.json();
for (const item of issue.items) {
  console.log(item.tier, item.distance_m + " m", item.headline);
}

claude mcp add --transport http alleypulse https://api.alleypulse.com/mcp --header "Authorization: Bearer ap_live_EXAMPLE"

{
  "id": "iss_EXAMPLE06",
  "shop_id": "shp_EXAMPLE01",
  "number": 6,
  "published_at": "2026-10-26T07:00:00Z",
  "is_baseline": false,
  "scan": {
    "radius_m": 1000,
    "listings_scanned": 137,
    "scanned_on": "2026-10-25",
    "compared_with": "2026-10-18"
  },
  "tier_counts": { "A": 3, "B": 4, "C": 3 },
  "summary": "A nearby café started a morning promo aimed at your commuters, Saturday's street market will bring extra people past your door, and a bakery's rating dipped after complaints about waiting.",
  "items_url": "https://api.alleypulse.com/v1/issues/iss_EXAMPLE06/items",
  "items": [
    { "id": "itm_EXAMPLE01", "tier": "A", "headline": "A café 200 m away is offering two for one flat whites before 9am" }
  ]
}

The example issue has 10 items; the response above shows one. Fetch the rest from items_url.

Which REST endpoints are there?

Every data endpoint is a GET, so it is safe to retry. The two POST endpoints do not change your shop data. Responses are JSON, and the version is in the path.

Lists use cursor pagination: pass next_cursor from one response as cursor in the next request, and stop when has_more is false.

{
  "data": [ { "id": "iss_EXAMPLE06", "number": 6, "published_at": "2026-10-26T07:00:00Z" } ],
  "next_cursor": "cur_EXAMPLE",
  "has_more": true
}

Address check example. The address is sent in the body so it never appears in a URL or an access log.

curl https://api.alleypulse.com/v1/coverage-check \
  -H "Authorization: Bearer ap_live_EXAMPLE" \
  -H "Content-Type: application/json" \
  -d '{"address": "12 Sample Street, Sampletown", "radius_m": 1000}'

What does an item contain?

Every item answers the same five questions as the email: what changed, where, why it matters, what to do this week, and the source. There is no field for review text or for the names of nearby businesses.

{
  "id": "itm_EXAMPLE01",
  "issue_id": "iss_EXAMPLE06",
  "issue_number": 6,
  "tier": "A",
  "category": "competitor_promo",
  "headline": "A café 200 m away is offering two for one flat whites before 9am",
  "what_changed": "New post on its Google Maps listing, valid weekdays until Friday 6 November.",
  "distance_m": 200,
  "why_it_matters": "It targets the same commuters as your busiest window, 7 to 9am.",
  "what_to_do": "Do not match the price. Put your loyalty card or a coffee and pastry pairing in the window, and compare 7 to 9am sales with last week.",
  "source_url": "https://source.alleypulse.example/itm_EXAMPLE01",
  "source_type": "google_maps_post",
  "first_seen": "2026-10-24"
}

How do keys and sign in work?

• Send Authorization: Bearer ap_live_... on every request. Keys never go in a URL.
• A key is shown once when you create it and stored only as a hash. If you lose it, create a new one.
• One scope in v1, read. A key can read all your shops or only the shops you choose.
• Revoke a key in the app at any time. Requests with it fail straight away.
• Keep keys out of browser code and public repositories. OAuth sign in for MCP clients is not part of v1.

What are the limits, versions and errors?

The limit is 60 requests per minute per key. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a 429 response adds Retry-After. Within v1 we may add fields and enum values without notice, so ignore what you do not recognize. Breaking changes ship as v2, with the old version kept running for at least 6 months.

{
  "error": {
    "code": "rate_limited",
    "message": "The limit is 60 requests per minute for this key. Retry after 12 seconds.",
    "request_id": "req_EXAMPLE"
  }
}

How do webhooks work?

There is one event, issue.published, sent when the weekly issue for one of your shops is ready. The payload holds only ids, so fetch the items with the API. It is a weekly event, not a stream of live changes.

{
  "id": "evt_EXAMPLE01",
  "type": "issue.published",
  "created_at": "2026-10-26T07:00:12Z",
  "data": {
    "shop_id": "shp_EXAMPLE01",
    "issue_id": "iss_EXAMPLE06",
    "issue_number": 6,
    "is_baseline": false
  }
}

Each delivery is signed. The header holds a timestamp and an HMAC SHA256 of t + "." + raw body, keyed with the endpoint secret you receive once when you subscribe. Reject deliveries whose timestamp is older than five minutes. Failed deliveries are retried up to 5 times over a day.

AlleyPulse-Signature: t=1793000412,v1=EXAMPLE_HEX_DIGEST

// Example only. The secret is a placeholder.
import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const signed = parts.t + "." + rawBody;
  const expected = createHmac("sha256", secret).update(signed).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 ?? "");
  return a.length === b.length && timingSafeEqual(a, b);
}

Which MCP tools are there?

A remote MCP server over streamable HTTP, signed in with the same read only API key. Every tool is read only and safe to repeat. No tool sends email, edits a shop or posts anywhere.

https://api.alleypulse.com/mcp

One resource is available: alleypulse://shops/{id}/issues/latest, the latest issue of a shop, so a client can attach it to a conversation.

How do I connect a client?

Copy a snippet, replace the placeholder key with your own, and restart the client. Client configuration formats differ and change, so treat these as examples and check your client's current documentation.

claude mcp add --transport http alleypulse https://api.alleypulse.com/mcp --header "Authorization: Bearer ap_live_EXAMPLE"

{
  "mcpServers": {
    "alleypulse": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://api.alleypulse.com/mcp",
        "--header", "Authorization: Bearer ${AP_API_KEY}"
      ],
      "env": { "AP_API_KEY": "ap_live_EXAMPLE" }
    }
  }
}

{
  "mcpServers": {
    "alleypulse": {
      "url": "https://api.alleypulse.com/mcp",
      "headers": { "Authorization": "Bearer ap_live_EXAMPLE" }
    }
  }
}

{
  "mcpServers": {
    "alleypulse": {
      "type": "http",
      "url": "https://api.alleypulse.com/mcp",
      "headers": { "Authorization": "Bearer ap_live_EXAMPLE" }
    }
  }
}

What does a conversation look like?

An owner asks an assistant that has the MCP server connected. Here is an example. The assistant calls one tool and answers from the issue.

What are the data rules?

• No raw review text. Items give counts, rating changes and short summarized themes, never quoted reviews or reviewer names.
• Anonymized peers. Nearby businesses appear as a café 200 m away, not by name.
• Sources linked. Every item has a source link, a source type and the day we first saw it.
• Weekly, not real time. Data is a weekly snapshot and can be hours to days old when you read it.
• The first issue is a baseline. It is flagged is_baseline: true and shows what is around you, not what changed. New and closed items begin in issue 2 and are reliable from about week 3 to 4.
• New on Google Maps is not an opening. A closed item means marked closed on Google at scan time.
• Same coverage as the email. Wherever Google Maps has business listings, except Russia and Belarus. See coverage.
• For your own use. Use items in your own tools and assistants. The terms cover reuse and resale.

How do I get access, and what does it cost?

Every shop subscription includes read only API and MCP access to the same data as the email, at 60 requests per minute per key and up to 5 active keys per account. The address check is free for everyone at a lower limit. There is no extra charge for the API. The $39 per month per shop on the pricing page is a placeholder price, and we are not charging yet.

API and MCP questions