Developer reference · The Optimly Index

Build with public brand data

Find a brand, fetch its structured profile, and use it in a source-attributed answer. No account, no API key, and no claim. The whole path is five HTTP calls or fewer.

The five-minute path

This walkthrough uses Stripe as a known brand. Replace stripe.com with the company you are researching.

1. Search by name or domain

Send a bare company name or domain. The endpoint matches a brand's display name, or an exact canonical URL or domain.

curl -sS 'https://optimly.ai/brands/search?q=stripe.com'

Example response (trimmed):

{
  "items": [
    {
      "slug": "stripe",
      "name": "Stripe",
      "domain": "stripe.com",
      "is_claimed": false,
      "category": "fintech-financial-services"
    },
    {
      "slug": "stripe-capital",
      "name": "Stripe-capital",
      "domain": "stripe.com",
      "is_claimed": false,
      "category": "lending-credit"
    }
  ]
}

Pass a bare domain or company name, not a full URL. A full URL can produce unrelated trigram matches because the word "https" itself is matched.

EndpointGET /brands/search?q=<name-or-domain>
AuthenticationNone
Minimum query2 characters after trimming
Maximum results10
MatchingDisplay-name trigram similarity ≥ 0.3, or exact canonical URL/domain. Aliases are shown in the profile but are not a separate search key.
Rate limit60 requests per minute per IP at the origin. Back off on 429.
Empty or short query200 with {"items": []}

2. Select the right entity

The search returns candidates, not a decision. Choose the row whose domain and name match the company you mean, and do not assume the first row is the one you want.

  • Prefer an exact domain match over a name-similarity match.
  • More than one row can share a domain: a parent company, a product, and a subsidiary are separate records. Read name and category, then fetch the profile and confirm its sections.
  • If the slug is shared by several brands, the bare slug redirects to a disambiguation record. Follow the redirect and choose from entries.

A collided slug answers 301 to the disambiguation JSON. That response has no profile, only the candidates:

curl -sSL 'https://optimly.ai/brand/halo_(disambiguation).json'
{
  "core": "halo",
  "entries": [
    {
      "name": "Halo",
      "category": "gaming",
      "domain": "halowaypoint.com",
      "url": "https://optimly.ai/brand/halo_(gaming)",
      "description": "..."
    },
    {
      "name": "Halo",
      "category": "collaboration-productivity",
      "domain": "halo.science",
      "url": "https://optimly.ai/brand/halo_(collaboration-productivity)",
      "description": "..."
    }
  ]
}

The entries carry a canonical url; use it directly. If you build a URL from a slug with parentheses, percent-encode it.

3. Fetch the structured profile

curl -sS 'https://optimly.ai/brand/stripe.json'

Example response (trimmed):

{
  "name": "Stripe",
  "domain": "stripe.com",
  "url": "https://optimly.ai/brand/stripe",
  "is_claimed": false,
  "categories": ["fintech-financial-services"],
  "headers": [
    {
      "header": "Overview",
      "sections": [
        {
          "key": "short_description",
          "label": "Tagline",
          "shape": "text",
          "content": "Stripe offers the most unified and developer-centric financial stack...",
          "source_type": "1p_website",
          "source_label": "Brand's website",
          "source_url": "https://stripe.com",
          "updated_at": "2026-10-04T00:05:21.265000+00:00"
        }
      ]
    }
  ],
  "last_refreshed_at": "2026-10-04T00:05:21.265000+00:00",
  "last_changed_at": "2026-10-17T23:44:05.680453+00:00",
  "claim_url": "https://app.optimly.ai/sign-up?claim=..."
}

The same record is available in three forms:

SurfaceURLUse it for
HTML/brand/{slug}A human-readable page; no JavaScript required
JSON/brand/{slug}.jsonStructured sections, sources, and dates
Markdown/brand/{slug}/llms.txtPlain-text retrieval; the same content, laid out for an agent

Aliases, alternate domains, and "not to be confused with" are ordinary sections (aliases, alternate_domains, not_to_be_confused_with) under the Overview header when the record has them.

4. Use it with source attribution

Keep the section's source and date attached to the sentence it supports. A good answer names the record, the section source, and the date:

Stripe describes itself as "the most unified and developer-centric financial stack" for businesses scaling on a single set of APIs. Source: Stripe's website (https://stripe.com), checked 2026-10-04, via the Optimly Index: https://optimly.ai/brand/stripe.

Attribution rules that keep the answer honest:

  • Cite the canonical url from the profile, not the search URL or a redirect.
  • Name the section source (source_label) and its date (updated_at). If source_url is present, include it.
  • Do not merge sections from different sources into one unattributed claim.
  • An unclaimed record is publicly sourced. Say so, rather than presenting it as the company's own statement.
  • A claimed record is owner-attributable, not independently verified. See the contract below.

A complete, copy-paste Python example — search, select an exact domain, fetch the profile, and print attributed sections:

import json
import urllib.parse
import urllib.request

BASE = "https://optimly.ai"

def get_json(path):
    request = urllib.request.Request(
        BASE + path,
        headers={"User-Agent": "your-app/1.0 (you@example.com)"},
    )
    with urllib.request.urlopen(request, timeout=20) as response:
        return json.load(response)

query = "stripe.com"  # a brand name or a bare domain
items = get_json("/brands/search?q=" + urllib.parse.quote(query))["items"]

normalized = query.strip().lower()
domain_match = next((i for i in items if i["domain"].lower() == normalized), None)
name_matches = [i for i in items if i["name"].lower() == normalized]
# Prefer an exact domain; accept an exact name only when it is unambiguous.
match = domain_match or (name_matches[0] if len(name_matches) == 1 else None)
if match is None:
    raise SystemExit(f"No unambiguous exact match. Candidates: {items}")

slug = urllib.parse.quote(match["slug"], safe="")
profile = get_json(f"/brand/{slug}.json")
if "entries" in profile:  # a shared bare slug
    raise SystemExit(f"Ambiguous slug; choose an entry: {profile['entries']}")

print(f"{profile['name']} — {profile['url']} (claimed: {profile['is_claimed']})")
for group in profile["headers"]:
    for section in group["sections"]:
        print(f"- {section['label']}: {section['content']}")
        source = section["source_label"]
        if section["source_url"]:
            source += f" ({section['source_url']})"
        if section["updated_at"]:
            source += f", updated {section['updated_at'][:10]}"
        print(f"  Source: {source}")

Send a descriptive User-Agent. A library's default agent can be rejected by the edge even though the same request works with curl; the example sets one explicitly.

The selection prefers an exact domain, accepts an exact display name only when it is unambiguous, and otherwise prints the candidates. That is deliberate: more than one record can share a name, and the first row is not automatically the right entity.

5. Handle the cases the search cannot resolve

CaseResponseWhat to do
Nothing matched 200 with {"items": []} Try the company's bare domain, then its display name. The public index contains published records only.
Unknown brand 404 with {"error": "not_found", "slug": "..."} Do not invent a profile. The brand may not be published; adding it happens in the signed-in application.
Shared slug 301 to ..._(disambiguation).json, then 200 with entries Choose by domain and category; use the entry's url.
Too many searches 429 with {"error": {"code": "rate_limited", ...}} Read details.retry_after, back off, and cache the result you already have.
Unknown category 404 with {"error": "not_found", "category": "..."} Fetch the category from a profile's categories list rather than guessing a slug.

The public data contract

Identity and aliases

name, domain, and url identify the record. domain is the canonical registrable domain; url is the canonical page. Alternate names and domains are content, not identity keys: read the aliases and alternate_domains sections when you need them. Slug aliases redirect with 301; follow the redirect and cite the final url.

Fields and missing data

A section that has no content is omitted, not returned as null or an empty string. A record whose profile is still being assembled returns an empty headers list. Do not read an omitted section as a negative fact about the company — it means Optimly has no published value for that section, not that the company has no answer.

FieldMeaning
nameDisplay name of the record.
domainCanonical registrable domain, lowercase.
urlCanonical brand page; cite this.
is_claimedWhether an organization has claimed the record. Not a verification badge.
categoriesTaxonomy slugs; may be empty.
headers[].headerGrouping label: Overview, Identity, Offerings, Audience, Landscape.
sections[].keyStable registry key for the section (for example short_description).
sections[].shapetext, list, or links; content matches the shape.
sections[].source_typeWhere the section came from. See the source table below.
sections[].source_urlThe source link when one exists, otherwise null.
sections[].updated_atWhen that section was last written, otherwise null.
last_refreshed_atWhen Optimly last refreshed the record. May be null.
last_changed_atWhen the record's content last changed (the active index version). May be null.
claim_urlPresent only on an unclaimed record: the claim call to action.

Archived profiles are excluded from search, categories, and /brands.json. A known canonical URL may still resolve; the HTML and markdown surfaces mark it "Profile no longer managed". The JSON payload does not carry an archived flag.

Sources and freshness

source_typesource_labelWhat it means
brand_vaultBrand-providedPublished by the brand's owner in BrandVault. Owner-approved, not independently verified.
1p_websiteBrand's websiteExtracted by Optimly from the brand's own website. First-party, not owner-approved.
3p_websiteThird-partyReserved for third-party sources. No third-party ingestion currently produces this value.

last_refreshed_at tells you when Optimly last checked the record. last_changed_at tells you when its content last changed. A section's updated_at is the date to cite for that section. None of these timestamps is proof that a specific BrandVault version was approved on that date.

Claimed is not verified

is_claimed: true means an organization has attached itself to the record. It means the owner stands behind the record; it does not mean Optimly independently verified the statements, and it does not mean every section is owner-approved. A claimed record can still contain 1p_website sections. Read each section's source. There is no separate "independently verified" status.

Caching

Brand HTML, JSON, and markdown respond with Cache-Control: s-maxage=600, stale-while-revalidate=86400. The bulk /brands.json feed and the site-wide machine files use s-maxage=3600. The CDN may serve a stale copy after expiry while it revalidates, so use the timestamps in the payload when freshness matters rather than assuming the response is current.

Rate limits

Search is limited to 60 requests per minute per IP at the origin and answers 429 over the limit. Profile and bulk reads have no separate documented per-request quota, but /brands.json is a multi-megabyte response cached for an hour: fetch it once and keep it, rather than polling it. Caching responses in your own system is expected.

Errors

Search and profile reads use small, purpose-built error bodies rather than the authenticated API's error envelope:

# Unknown brand
{"error": "not_found", "slug": "not-a-real-brand"}

# Unknown category
{"error": "not_found", "category": "not-a-category"}

# Search rate limit (the shared error envelope)
{"error": {"code": "rate_limited", "message": "Too many searches — slow down", "details": {"retry_after": 12}}}

A per-brand llms.txt answers an unknown slug with 404 and the plain text not found.

Appropriate use

  • Read only. There is no public write credential, and no public add or claim.
  • Cite the canonical page and preserve per-section attribution.
  • Do not present a claimed record as independently verified, and do not present an unclaimed record as the company's own statement.
  • Use /brands.json for corpus ingestion instead of crawling every profile. Respect /robots.txt and the cache headers.
  • Do not use the public index as a substitute for private measurement data; it carries no measurement fields.

What is not available

  • No general product or intent search. /brands/search matches brand names and canonical URLs/domains. It is not a product catalogue search, and it does not search section text.
  • No public-index MCP server. The MCP connector is for authenticated BrandVault data. Public index reads are HTTP-only.
  • No SDK. Use any HTTP client.
  • No public write path. Adding, claiming, and updating a brand happen in the signed-in application.
  • No third-party source ingestion. 3p_website is reserved and not currently produced.

If you need any of these, say so explicitly rather than approximating it with the surfaces above.

Machine files

The index also publishes /llms.txt (the site contract), /brands.json (the bulk feed), and /sitemap.xml. The per-brand markdown twin carries the same attribution as the JSON.