Developers
Searchiz API and MCP
Create a workspace API key in the signed-in application. Send it as Authorization: Bearer searchiz_live_…. A key acts for the workspace only while its owner is still a member; leaving the workspace revokes it. Mutating REST requests also require an Idempotency-Key of at most 200 bytes. Repeating a request with the same key in the same workspace returns the original brand, scan, prompt, action, or approval link instead of creating another.
REST
| Method | Path | Purpose |
|---|---|---|
GET | /api/v1/brands | List brands in the key's workspace |
POST | /api/v1/brands | Create and profile a brand from input (website, Google Maps link, @Instagram, TikTok, Facebook page, WhatsApp number, link-in-bio, marketplace listing), a chosen candidate, or manual answers |
GET | /api/v1/brands/:id | Read its profile and confirmed facts |
POST | /api/v1/scans | Start a visibility scan of a website, listing, or profile URL (a report of the same business from the last day is returned instead) |
GET | /api/v1/scans/:token | Read scan progress and report |
GET | /api/v1/brands/:id/visibility | Read occurrences, valid sample size, rate, and Wilson interval |
GET | /api/v1/brands/:id/findings | List prioritized findings |
POST | /api/v1/brands/:id/actions | Prepare an action from confirmed facts |
GET | /api/v1/actions/:id | Read the current rendered version and digest |
POST | /api/v1/brands/:id/prompts | Add a monitored question; optional engine (default chatgpt) |
POST | /api/v1/actions/:id/approve | Request a person's approval of the exact version_digest; answers 202 with an approval_url |
POST | /api/v1/actions/:id/approval_link | Human approval link for a client |
POST | /api/v1/publications | Publish a version a person approved through an active publishing connection of the same brand |
An action response contains version_id, rendered, version_digest, approved, and facts_current. An API key may be used by an agent, so it never approves: approve binds the request to the exact digest and returns a single-use link that the owner or client opens to approve or request changes. Once a person approved, approve answers 200 with approved: true, and publications may release that version. A different version has a different digest. Publication fails unless that exact digest is approved, every brand fact it was written from is still confirmed with the same value, and the connection is active. A client's request for changes withdraws the approval. Approving the same digest again returns the existing approval.
Visibility counts only successful observations of discovery questions (which never name the brand), and only the engine's answer and the sources it cited. Failed, blocked, and unsupported collections are reported as such and never count as absence. Scans are limited to five per key per hour and three per business per day.
MCP
Send MCP Streamable HTTP JSON-RPC requests to POST /mcp with the same bearer key. The server implements initialize, ping, tools/list, and tools/call, and accepts notifications with 202 Accepted. It exposes brand listing, visibility, prompts, findings, results, scans (start_scan, get_scan, with the same reuse and limits as REST), grounded action preparation, reading an action (get_action), and human approval links (request_approval). Publication is deliberately not an MCP tool. Invalid arguments return a JSON-RPC error with code -32602. An agent can never approve: approval always happens on the link a person opens, and publication requires that human approval.
MCP clients that cannot send a custom header (Claude and ChatGPT connectors) sign in with OAuth 2.1 instead of an API key. An unauthenticated /mcp request answers 401 with WWW-Authenticate: Bearer resource_metadata=".../.well-known/oauth-protected-resource/mcp". The authorization server metadata is at /.well-known/oauth-authorization-server; clients register themselves at POST /oauth/register (public clients only, HTTPS or loopback redirect URIs), send the person to /oauth/authorize with PKCE S256, and exchange the code at POST /oauth/token. The person signs in, chooses one workspace and allows or denies the client. Access tokens last one hour and act only on /mcp, never on the REST API; refresh tokens last 30 days and rotate on every use, and a replayed code revokes the grant. Each grant appears as one key named MCP · <client> in the workspace's API keys, where revoking it disconnects the client.
Businesses without a website
input may be a business name and city ("Northside Plumbing, Austin"). The API then answers 409 Conflict with candidates (OpenStreetMap first, Google Places when configured); send one back as candidate with its kind, locator, and name. Nothing is read or created until a candidate is chosen, and similar names are never merged. manual accepts name, what, who, where, price, proof, phone, and catalog for a business with no online presence.
A scan whose sources do not say what the business does stops before collecting and answers status: "choosing" with report.unreadable: true, so no generic question is asked on its behalf. Start a new scan with manual answers for that business.
GET /api/v1/brands/:id lists each source with its state: fetched, failed, unsupported (no provider configured), or needs_owner (only readable through the owner's own connection). None of them counts as the business being absent.
A brand without a website can publish a hosted page (hosted_page action) built only from confirmed facts, approved as an exact version, and served at /b/:slug or on the owner's domain. Visits from AI crawlers to that page are recorded as bot hits with source hosted and verified against the crawler's published IP ranges or reverse DNS. Results report bot_hits (verified only) and unverified_bot_hits (user agent only, such as events sent from a customer site) separately.
Connections
Connections created in the application use the customer's own credential. A connection may name its own base_url, which must be a public HTTP(S) address; requests stay on that host and are sent to the address that was validated. Platform credentials are used only by server-provisioned official connections.
Measurement
POST /measurement-events accepts bot_hit, ai_referral, lead and order events with the brand's X-Searchiz-Key, including cross-origin requests from the customer's site. A lead with an event_id is recorded once. Issue the key from the brand page; it is shown once.
CLI
The npm package searchiz (npx searchiz, source in packages/searchiz-agent-npm) is the supported CLI; it adds scan-status and action to brands, scan, visibility, findings, prepare, approve, and publish. The Ruby gem source in packages/searchiz-agent-ruby covers the original commands and is not published. Both use SEARCHIZ_URL and SEARCHIZ_API_KEY.
An order event records a purchase whose visit came from an AI shopping card. Send order_id, amount, currency and the utm_source kept from the landing URL; only chatgpt.com, copilot.com, perplexity.ai and gemini.google.com are recorded, once per order, without customer data. Other orders are accepted and discarded.