agentprose Cloud docs

Hosted analytics and search for sites that use the open-source agentprose script.

1. Install

Create a site in the dashboard to get its public key (pk_…). Then add this script tag to every page (it replaces any agentprose tag you already have):

<script src="https://agentprose.cloud/v/0.1.0/agentprose.min.js" data-key="pk_…" defer></script>

That turns on both products. agentprose Cloud serves the open-source agentprose library itself, so your site doesn't depend on a public CDN, and the script knows where its Cloud is. https://agentprose.cloud/v/0.1.0/agentprose.min.js never changes (it is cached for a year); https://agentprose.cloud/agentprose.min.js always points at the current version.

With a strict Content-Security-Policy, allow https://agentprose.cloud in script-src (the script loads its search engine and adapters from the same folder) and in connect-src (beacons and hosted search).

Optional: load it from jsDelivr instead. The same library is on npm. From a public CDN the script can't know your Cloud, so data-cloud is required:

<script src="https://cdn.jsdelivr.net/npm/agentprose@0.1/dist/agentprose.min.js"
        data-cloud="https://agentprose.cloud" data-key="pk_…" defer></script>

Analytics only: use data-analytics="https://agentprose.cloud/v1/collect" with data-key. To keep search local: add data-cloud-search="false".

The public key is not a secret. It only works from the domains listed in the site's settings.

2. What the script sends

One small beacon per tool call (navigator.sendBeacon, no cookies):

{"v":2,"key":"pk_…","tool":"search_posts","ok":true,"ms":41,
 "page":"https://blog.example/posts/a/","query":"webmcp safari","n":0,"sid":"k3j9x0aa"}

query is only sent for search tools (max 200 characters) and can be turned off per site. n is the number of results, found the citation verdict, post the URL an agent asked for. Post content is never sent. We store the page path without its query string, the agent family derived from the User-Agent (not the string itself) and a daily-rotating hash for unique counts. Raw IP addresses are never stored.

3. Hosted search

GET https://agentprose.cloud/v1/search?key=pk_…&q=webmcp+security&limit=10
→ 200 {"query":"webmcp security","count":2,"mode":"bm25","items":[{"url":"…","title":"…","summary":"…","published":"…","tags":[…],"score":7.21}]}

Open CORS, cached for 60 seconds. Over the monthly quota it returns 429 and the agentprose script falls back to its own in-browser search.

Keeping the index fresh

• Crawl: we read agentprose.json (from npx agentprose build), else your RSS/Atom/JSON feed, else your sitemap and pages. Re-crawled daily and on demand.
• CMS webhook: point WordPress, Ghost, Sanity, Contentful, Strapi or Storyblok's "on publish" webhook at your site's hook URL (Site → Search index). Any POST queues a re-crawl.
• Upload: push the index from CI with a secret API key:

  npx agentprose build public --base-url https://blog.example/ --inline
  curl -X PUT https://agentprose.cloud/v1/sites/SITE_ID/index   -H "Authorization: Bearer sk_…" -H "Content-Type: application/json"   --data-binary @public/agentprose.json

4. CMS webhooks and re-crawls

Every site has a webhook URL (on its Search index page). Point your CMS at it and new or changed posts reach hosted search within seconds:

• Ghost: Settings → Integrations → custom integration → webhooks for Post published, Published post updated, Post unpublished, Post deleted. The post is indexed straight from the webhook; members-only posts are never indexed.
• WordPress: a WP Webhooks "Send Data" webhook on post create/update/trash, or a few lines on transition_post_status that post {"post_permalink": "...", "post_status": "publish"}. Published permalinks are re-fetched; any other status removes the post.
• Sanity: a GROQ-powered webhook with the projection {"url": "https://your.site/posts/" + slug.current + "/"}. Create/update re-fetches the page, delete removes it.
• Contentful: a webhook on Entry publish/unpublish/archive/delete. Entries carry no public URL, so each event queues one debounced re-crawl.
• Anything else: POST {"url": "https://your.site/post/"} (add "action": "delete" to remove), or an empty body to re-crawl everything.

Static sites can skip webhooks and upload agentprose.json from CI (next section). Each site is also re-crawled on a schedule you set in its settings (daily by default; down to every 6 hours on Pro and hourly on Team).

5. Management API

Authenticate with Authorization: Bearer sk_… (create keys under API keys; we store only a hash).

6. Privacy

agentprose Cloud is a processor for the analytics data of your site; a DPA is available. Retention follows your plan (30 days, 1 year, 2 years) and the data is deleted with your account. Read the privacy policy.