Hermai Agent-Native API API

{"components":{"schemas":{"BrandApplicationTheme":{"properties":{"colors":{"anyOf":[{"description":"Present only when a usable accent was observed.","properties":{"action":{"type":"string"},"border":{"type":"string"},"data_primary":{"type":"string"},"focus":{"type":"string"},"on_action":{"type":"string"},"on_tint":{"type":"string"},"text_accent":{"type":"string"},"tint":{"type":"string"}},"type":"object"},{"type":"null"}]},"fallback":{"anyOf":[{"properties":{"reason":{"type":"string"},"strategy":{"type":"string"}},"type":"object"},{"type":"null"}]},"identity":{"properties":{"compact":{"properties":{"asset":{"anyOf":[{"$ref":"#/components/schemas/BrandLogoAsset"},{"type":"null"}]},"fallback":{"type":"string"},"show_company_name":{"type":"boolean"}},"type":"object"},"on_dark":{"properties":{"asset":{"anyOf":[{"$ref":"#/components/schemas/BrandLogoAsset"},{"type":"null"}]},"fallback":{"type":"string"},"show_company_name":{"type":"boolean"}},"type":"object"},"standard":{"properties":{"asset":{"anyOf":[{"$ref":"#/components/schemas/BrandLogoAsset"},{"type":"null"}]},"fallback":{"type":"string"},"show_company_name":{"type":"boolean"}},"type":"object"}},"type":"object"},"mode":{"type":"string"},"version":{"type":"string"}},"type":"object"},"BrandColorEntry":{"properties":{"brightness":{"description":"WCAG relative luminance, 0 to 1.","type":"number"},"derivation":{"description":"declared: found explicitly on the page (theme-color, manifest). derived: computed from an asset (for example quantized from a logo).","enum":["declared","derived"],"type":"string"},"hex":{"type":"string"},"observed_at":{"format":"date-time","type":"string"},"origin":{"enum":["observed","inferred","synthesized","corrected"],"type":"string"},"role":{"enum":["accent","background","text","neutral"],"type":"string"},"source":{"properties":{"signal":{"description":"The extraction signal that produced this value.","enum":["bimi","json_ld","manifest","apple_touch_icon","link_icon","header_dom","meta_og","meta_theme_color","css_var","render_computed","llm_classified","manual_correction","page_title","registrable_domain","logo_derived","meta_description"],"type":"string"},"url":{"description":"The page or record this value was observed on.","type":"string"}},"type":"object"}},"type":"object"},"BrandDemoPending":{"properties":{"domain":{"type":"string"},"poll_after_ms":{"description":"Repost the same domain after this many milliseconds.","type":"integer"},"status":{"enum":["pending"],"type":"string"}},"type":"object"},"BrandDemoRequest":{"properties":{"domain":{"description":"Company domain to resolve. Emails are not accepted on this endpoint.","type":"string"}},"required":["domain"],"type":"object"},"BrandDemoResponse":{"properties":{"brand":{"properties":{"colors":{"items":{"$ref":"#/components/schemas/BrandColorEntry"},"type":"array"},"description":{"$ref":"#/components/schemas/BrandNullableStringField"},"logos":{"items":{"$ref":"#/components/schemas/BrandLogoAsset"},"type":"array"},"name":{"$ref":"#/components/schemas/BrandNullableStringField"}},"type":"object"},"domain":{"type":"string"},"status":{"enum":["ok","partial","not_found","fetch_failed"],"type":"string"}},"type":"object"},"BrandEnvelope":{"description":"The full POST /v1/brand/retrieve response. status=pending carries an empty brand object plus a poll token in pending.token; repost the token to POST /v1/brand/poll.","properties":{"application_theme":{"$ref":"#/components/schemas/BrandApplicationTheme"},"assembled_at":{"format":"date-time","type":"string"},"brand":{"$ref":"#/components/schemas/BrandObject"},"pending":{"anyOf":[{"properties":{"poll_after_ms":{"type":"integer"},"token":{"type":"string"}},"type":"object"},{"type":"null"}]},"refresh":{"properties":{"clamped":{"type":"boolean"},"state":{"enum":["fresh","refreshing","stale"],"type":"string"}},"type":"object"},"requested":{"properties":{"domain":{"type":"string"},"input_type":{"enum":["domain","email"],"type":"string"}},"type":"object"},"resolved":{"properties":{"ambiguity":{"anyOf":[{"enum":["parked","multi_brand","unresolved"],"type":"string"},{"type":"null"}]},"canonical_domain":{"type":"string"},"redirect_terminal":{"type":"string"}},"type":"object"},"status":{"description":"ok: full profile. partial: some fields missing. pending: still running, poll with the returned token. personal_email/disposable_email: the input email was rejected before lookup. not_found: the domain does not resolve to a live site. fetch_failed: the site could not be fetched.","enum":["ok","partial","pending","personal_email","disposable_email","not_found","fetch_failed"],"type":"string"},"usage":{"$ref":"#/components/schemas/BrandUsage"}},"type":"object"},"BrandErrorResponse":{"properties":{"error":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"retry_after":{"description":"Seconds to wait before retrying. Present on rate limited responses.","type":"integer"},"retryable":{"type":"boolean"}},"type":"object"},"success":{"enum":[false],"type":"boolean"}},"type":"object"},"BrandFont":{"properties":{"name":{"type":"string"},"observed_at":{"format":"date-time","type":"string"},"origin":{"enum":["observed","inferred","synthesized","corrected"],"type":"string"},"source":{"properties":{"signal":{"description":"The extraction signal that produced this value.","enum":["bimi","json_ld","manifest","apple_touch_icon","link_icon","header_dom","meta_og","meta_theme_color","css_var","render_computed","llm_classified","manual_correction","page_title","registrable_domain","logo_derived","meta_description"],"type":"string"},"url":{"description":"The page or record this value was observed on.","type":"string"}},"type":"object"}},"type":"object"},"BrandLinks":{"properties":{"blog":{"$ref":"#/components/schemas/BrandNullableStringField"},"careers":{"$ref":"#/components/schemas/BrandNullableStringField"},"contact":{"$ref":"#/components/schemas/BrandNullableStringField"},"pricing":{"$ref":"#/components/schemas/BrandNullableStringField"},"privacy":{"$ref":"#/components/schemas/BrandNullableStringField"},"terms":{"$ref":"#/components/schemas/BrandNullableStringField"}},"type":"object"},"BrandLogoAsset":{"properties":{"asset_version":{"type":"string"},"format":{"enum":["svg","png","webp","jpeg"],"type":"string"},"height":{"type":"integer"},"kind":{"enum":["icon","wordmark","symbol","unknown"],"type":"string"},"observed_at":{"format":"date-time","type":"string"},"origin":{"enum":["observed","inferred","synthesized","corrected"],"type":"string"},"source":{"properties":{"signal":{"description":"The extraction signal that produced this value.","enum":["bimi","json_ld","manifest","apple_touch_icon","link_icon","header_dom","meta_og","meta_theme_color","css_var","render_computed","llm_classified","manual_correction","page_title","registrable_domain","logo_derived","meta_description"],"type":"string"},"url":{"description":"The page or record this value was observed on.","type":"string"}},"type":"object"},"theme":{"anyOf":[{"enum":["light","dark","universal"],"type":"string"},{"type":"null"}],"description":"null when theme classification is uncertain, never a guess."},"url":{"type":"string"},"width":{"type":"integer"}},"type":"object"},"BrandNullableStringField":{"anyOf":[{"properties":{"observed_at":{"format":"date-time","type":"string"},"origin":{"enum":["observed","inferred","synthesized","corrected"],"type":"string"},"source":{"properties":{"signal":{"description":"The extraction signal that produced this value.","enum":["bimi","json_ld","manifest","apple_touch_icon","link_icon","header_dom","meta_og","meta_theme_color","css_var","render_computed","llm_classified","manual_correction","page_title","registrable_domain","logo_derived","meta_description"],"type":"string"},"url":{"description":"The page or record this value was observed on.","type":"string"}},"type":"object"},"value":{"type":"string"}},"type":"object"},{"type":"null"}]},"BrandObject":{"properties":{"colors":{"items":{"$ref":"#/components/schemas/BrandColorEntry"},"type":"array"},"description":{"$ref":"#/components/schemas/BrandNullableStringField"},"favicon":{"anyOf":[{"$ref":"#/components/schemas/BrandLogoAsset"},{"type":"null"}]},"fonts":{"items":{"$ref":"#/components/schemas/BrandFont"},"type":"array"},"links":{"$ref":"#/components/schemas/BrandLinks"},"logos":{"items":{"$ref":"#/components/schemas/BrandLogoAsset"},"type":"array"},"name":{"$ref":"#/components/schemas/BrandNullableStringField"},"socials":{"items":{"$ref":"#/components/schemas/BrandSocial"},"type":"array"}},"type":"object"},"BrandRetrieveRequest":{"properties":{"domain":{"description":"Company domain to resolve. Exactly one of domain or email is required.","type":"string"},"email":{"description":"Resolve the domain owning this email address instead. Exactly one of domain or email is required; a mailbox provider domain (gmail.com and similar) is rejected.","type":"string"},"force_refresh":{"description":"Bypass the cache and force a fresh lookup. Requires a caller entitlement; rejected otherwise.","type":"boolean"},"include_synthesized":{"description":"Include synthesized (best guess, non observed) fields in the response.","type":"boolean"},"max_age_s":{"description":"Serve a cached result up to this many seconds old. Clamped to a plan dependent floor.","type":"integer"},"wait_ms":{"description":"How long to wait synchronously for a cold lookup before returning a pending status.","type":["integer","null"]}},"type":"object"},"BrandSocial":{"properties":{"observed_at":{"format":"date-time","type":"string"},"origin":{"enum":["observed","inferred","synthesized","corrected"],"type":"string"},"source":{"properties":{"signal":{"description":"The extraction signal that produced this value.","enum":["bimi","json_ld","manifest","apple_touch_icon","link_icon","header_dom","meta_og","meta_theme_color","css_var","render_computed","llm_classified","manual_correction","page_title","registrable_domain","logo_derived","meta_description"],"type":"string"},"url":{"description":"The page or record this value was observed on.","type":"string"}},"type":"object"},"type":{"enum":["twitter","facebook","instagram","linkedin","youtube","tiktok","github","discord","pinterest","threads","mastodon","other"],"type":"string"},"url":{"type":"string"}},"type":"object"},"BrandUsage":{"properties":{"credits_consumed":{"type":"integer"},"credits_remaining":{"type":"integer"}},"type":"object"}},"securitySchemes":{"apiKey":{"description":"Hermai API key passed as a Bearer token.","scheme":"bearer","type":"http"}}},"info":{"description":"Public schema registry lookup and schema request intake for agent workflows.","title":"Hermai Agent-Native API","version":"dev"},"openapi":"3.1.0","paths":{"/v1/brand/demo":{"post":{"description":"Unauthenticated preview of a domain's brand identity, projected down to a small public card (status, domain, name, description, logos, colors). No API key and no credits; bounded by per IP and global daily limits, so a busy caller should read X-RateLimit-Remaining and back off before it hits zero.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandDemoRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandDemoResponse"}}},"description":"Brand card resolved for the domain (status ok, partial, not_found, or fetch_failed).","headers":{"X-RateLimit-Limit":{"description":"The per IP hourly request cap for this endpoint.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the caller's current hourly window.","schema":{"type":"integer"}}}},"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandDemoPending"}}},"description":"The domain has no cached record yet; extraction was started (or is already running). Repost the same domain after poll_after_ms."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandErrorResponse"}}},"description":"BRAND_INVALID_REQUEST: domain is missing, malformed, or an email address (the demo accepts domains only)."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandErrorResponse"}}},"description":"DOMAIN_IS_MAILBOX_PROVIDER: the domain is a mailbox provider (for example gmail.com), not a company."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandErrorResponse"}}},"description":"DEMO_RATE_LIMITED (per IP total), DEMO_COLD_RATE_LIMITED (per IP new domain lookups), or DEMO_BUDGET_EXHAUSTED (the shared daily budget for new domains). Previously seen domains keep working under DEMO_BUDGET_EXHAUSTED. retry_after seconds until the limiting window resets.","headers":{"Retry-After":{"description":"Seconds until the limiting window resets.","schema":{"type":"integer"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandErrorResponse"}}},"description":"BRAND_RESPONSE_INVALID or an internal error."},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandErrorResponse"}}},"description":"BRAND_DISABLED: the brand service is temporarily unavailable."}},"summary":"Anonymous public demo lookup for a domain's brand card"}},"/v1/brand/retrieve":{"post":{"description":"Resolve a company's name, description, logos, colors, fonts, socials, and links from its domain (or the domain of an email address), plus a ready to apply application_theme. Requires a Hermai API key. A completed profile (any content found) costs one credit; a pending or empty result costs nothing.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandRetrieveRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandEnvelope"}}},"description":"Brand lookup completed (status ok, partial, personal_email, disposable_email, not_found, or fetch_failed) or a prior lookup is still running (status pending; poll with POST /v1/brand/poll)."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandErrorResponse"}}},"description":"Invalid request: BRAND_INVALID_REQUEST (malformed body, or neither/both of domain and email were set)."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandErrorResponse"}}},"description":"UNAUTHORIZED: a valid Hermai API key is required."},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandErrorResponse"}}},"description":"INSUFFICIENT_CREDITS: the caller has no credits available to spend on a new lookup."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandErrorResponse"}}},"description":"BRAND_FORCE_REFRESH_FORBIDDEN: force_refresh was set but the caller has no entitlement to force a refresh."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandErrorResponse"}}},"description":"DOMAIN_IS_MAILBOX_PROVIDER: the resolved domain is a mailbox provider (for example gmail.com), not a company."},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandErrorResponse"}}},"description":"RATE_LIMITED or BRAND_RATE_LIMITED: the caller's request rate or brand specific rate limit was exceeded."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandErrorResponse"}}},"description":"BRAND_RESPONSE_INVALID or an internal error."},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandErrorResponse"}}},"description":"BRAND_DISABLED or CREDIT_UNAVAILABLE: the brand service or credit ledger is temporarily unavailable."}},"security":[{"apiKey":[]}],"summary":"Look up a company's brand identity for a domain or email"}},"/v1/fetch":{"post":{"description":"Run a registered site and endpoint through Hermai Cloud. Requires a Hermai API key and consumes credits.","requestBody":{"required":true},"responses":{"200":{"description":"OK"}},"security":[{"apiKey":[]}],"summary":"Execute a registered schema and return live data"}},"/v1/schema-requests":{"post":{"requestBody":{"required":true},"responses":{"201":{"description":"Schema request created"}},"summary":"Submit schema demand for a brittle browser workflow"}},"/v1/schema-requests/{request_id}":{"get":{"parameters":[{"in":"path","name":"request_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}},"summary":"Check schema request status"}},"/v1/schemas":{"get":{"parameters":[{"in":"query","name":"q","schema":{"type":"string"}},{"in":"query","name":"category","schema":{"type":"string"}},{"in":"query","name":"verified","schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK"}},"summary":"List and search public schema cards"}},"/v1/schemas/{site}":{"get":{"parameters":[{"in":"path","name":"site","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}},"summary":"Get the public card for a site's latest schema"}}},"servers":[{"url":"https://api.hermai.ai"}]}