API: the two locked contracts

API

Two contracts are locked and safe to build against.

Locked contracts

POST /api/ingestwhat the tracker posts

POST /mcpwhat your agent queries

Ingest

POST /api/ingest

What the tracker posts on every page view. The shape never changes.

POST /api/ingest
Content-Type: application/json

This is what bowtie.js posts on every page view, click and error. You almost never call it directly: install the tracker once and it handles the envelope, batching and retries. See the tracking reference for the install snippet and the full event catalog.

To post a server-side conversion from your backend, the same request shape applies: see server-side sessions. Authorization is a domain allow list only: the domain field must already be a registered site.

MCP

POST /mcp

The endpoint your agent queries, JSON-RPC.

POST /mcp
Authorization: Bearer <token>
Content-Type: application/json

This is the read side: a JSON-RPC 2.0 endpoint your AI agent talks to directly, covering traffic, conversions, errors and search performance over one connection for your account, scoped per token to the sites you choose. A GET on /mcp returns a live setup and schema summary. For the walkthrough, see connect your site to Claude.

Auth is a bearer token minted from your dashboard, scoped to the domains you choose when you create it.

Everything else is internal

Every other path under /api/, including all of /api/app/, is how the askbowtie app talks to its own backend. It carries no compatibility guarantee and can change or disappear between deploys. Build against ingest and MCP.

Questions about either contract? Contact us.

Get your token

Start free