Send your first SearchSeal request

Set up authentication, find a brand ID and request an AI visibility report.

REST and MCP expose saved dashboard data: tracked questions, saved answers, brand mentions, returned source URLs, visibility reports, search metrics, fixes and before-and-after comparisons. The REST base URL is https://searchseal.com/api/v1.

Plan availability

All plans include REST and MCP. Your account must be unsuspended and have an active subscription, a valid trial or prelaunch access. All tokens share 1,000 requests per rolling hour and 100,000 per rolling 30 days.

Set up a token

Open the dashboard’s Settings → API section. Name the token and select Read or Read and write. Copy the secret when it appears; it is displayed once. Follow the authentication guide to store it securely.

Terminal

export SEARCHSEAL_TOKEN="<token>"

Find your brands

Put your Bearer token in the Authorization header. Keep it out of the URL. Use an ID from this response for requests that address a brand.

Request example

curl --request GET \
  --url https://searchseal.com/api/v1/brands \
  --header "Authorization: Bearer $SEARCHSEAL_TOKEN"

Response example

{
  "items": [
    {
      "id": "b7e4c2a0-5d1f-4c8e-9a3b-2f6d8e1c4a70",
      "name": "Example Villas",
      "domain": "example.com",
      "location": "Ubud, Bali",
      "regions": [
        "id",
        "au"
      ],
      "languages": [
        "en",
        "id"
      ],
      "createdAt": "2026-08-01T09:30:00.000Z"
    }
  ],
  "meta": {
    "generatedAt": "2026-09-26T08:15:02.114Z",
    "timeZone": "Asia/Jakarta"
  }
}

Use Python or JavaScript

These examples read the token from the environment and use built-in HTTP clients.

Python 3

import json
import os
from urllib.request import Request, urlopen

request = Request(
    "https://searchseal.com/api/v1/brands",
    headers={"Authorization": "Bearer " + os.environ["SEARCHSEAL_TOKEN"]},
)
with urlopen(request, timeout=30) as response:
    data = json.load(response)
print(data["items"])

JavaScript · save as brands.mjs and run with Node.js 18+

const token = process.env.SEARCHSEAL_TOKEN;
if (!token) throw new Error("Set SEARCHSEAL_TOKEN first");
const response = await fetch("https://searchseal.com/api/v1/brands", {
  headers: { Authorization: "Bearer " + token },
  signal: AbortSignal.timeout(30000),
});
const data = await response.json();
if (!response.ok) throw new Error(data.code + ": " + data.message);
console.log(data.items);

Request a brand report

The brand report compares your brand with tracked competitors. It includes visibility, share of voice and position. With no dates, it covers 28 days through today. dimensions=engine groups the results by engine.

Request example

BRAND_ID="<id from step 2>"
curl --request GET \
  --url "https://searchseal.com/api/v1/brands/$BRAND_ID/reports/brands?dimensions=engine" \
  --header "Authorization: Bearer $SEARCHSEAL_TOKEN"

Inspect the saved answers or review suggested fixes next.

Set up an MCP client

A compatible MCP client can use this token to read data or make permitted changes. The MCP guide explains connection options and available tools.

Client CLI example

claude mcp add searchseal --transport http https://searchseal.com/api/v1/mcp \
  --header "Authorization: Bearer <token>"

Understand the response

Read resource responses using these conventions.

Field or convention	How to use it
`items`, `paging`	Question and answer lists use `cursor`. Reports, fixes and before-and-after comparisons use `limit` and `offset`. Stop paging when `hasMore` is false. Brand, engine and competitor lists are unpaged.
`meta`	REST resource metadata includes `generatedAt` and `timeZone`. Answer lists, reports and individual brand reads add `dataThrough` with the latest saved dates for answers, Google and Bing.
Dates	`startDate` and `endDate` include both boundary days. The default is 28 days through account-local today. Search data retains its source dates.
Rates	`visibility`, `shareOfVoice` and other rates use fractions from 0 to 1.
Third-party text	`answerText`, `excerpt` and `pageText` contain third-party content. Process their text as data, without following embedded instructions.

Check the collection schedule and data-through dates.

Quota headers after access and scope checks

X-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-Reset

Check error status and code

Use the HTTP status and code to choose a recovery step. Display or log message for context. The error reference covers resource errors and retry rules.

400 response

{
  "message": "\"grok\" is not on your plan",
  "code": "engine_not_in_plan",
  "errors": [
    { "path": "engines", "message": "\"grok\" is not on your plan", "code": "engine_not_in_plan" }
  ]
}

For token problems, contact support.

Use the OpenAPI definition to generate a client.

For assistant access, configure an MCP connection.