Company description

POST https://api.kingminos.com/v1/company/description

Try it in the console→

Send a company subject: domain, website, or email (hygiene-normalized to the same registrable domain). Optional name is a hint for composed text; it is not returned. Name-only input (no domain, website, or email) is 400 name_only_unsupported.

curl 'https://api.kingminos.com/v1/company/description' \
  -H 'Authorization: Bearer <your-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "domain": "outboundsync.com",
    "name": "OutboundSync",
    "path": "balance",
    "external_ref": "account-demo-1"
  }'

What comes back

The envelope is schema version 2. Automations branch on these layers:

Layer	Fields	Use
Control	es_decision, answer.confidence	Whether to stamp.
Explain	answer.summary, answer.confidence, answer.identity, sources	Humans and logs.
Quality	result.flags	Quality flags on the returned text (see below).
Billing	usage.credits, usage.hops	What ran and what was billed.
Audit	trace when X-Router-Explain: full	Debug only.

answer.outcome on this capability is hit or no_decision. es_decision is hit, miss, ambiguous, error, noop, or reject.

result.description is the write field: an English, JSON-safe company description (max_chars 80–500, default 300), or null on a miss. There is no company_name in the result.

answer.confidence is high, medium, or low (null on a miss). answer.identity is { "method": "jev" | "name_domain" | "own_homepage", "score": number | null }: how the text passed the identity check. It is null when the hit was not identity-judged.

Stamp rule: write result.description when answer.confidence meets your acceptance floor (path defaults: speed / coverage allow low; balance requires medium+; accuracy requires high; override with min_confidence). On a billed hit, text must be non-blank and pass the identity gate (answer.identity non-null: Jev identity ≥ 0.85, a deterministic name/domain match, or the input domain’s own homepage). Below-floor answers return description: null; candidates stay in evidence. Even low is usable and close to production-grade. See GET /v1/recipes/guidance.

Flags

result.flags is an object of booleans on a hit (null on a miss). Flags are quality signals, not misses. The hit still returns. The object may gain new keys over time; clients should ignore unknown keys.

Flag	Meaning
hype	Jev hype > 0.7 or leftover superlatives.
first_person	Any We / Our / I sentence.
tagline	Slogan, all-caps headline, blog headline, or article summary.
same_as_speed	A ranked fallback that matches the speed winner.
truncated	Stamp trimmed to the last whole word. Forces confidence low.
cta	Marketing or imperative line (Join N+, trusted-by, exclamation, Get started). Forces confidence low.
grammar	Informational only; does not affect confidence.

Other result fields: source_kind (quoted | composed), language_note (filtered | translated | interpreted | null), company_domain, compose_echo, homepage_meta_only.

Business misses stay HTTP 200.

Routing

Omitting path (or routing.path) runs the balance ladder with a run credit cap of 6. Set path to balance explicitly when you want that ladder with cap 2. The four paths are distinct, nested ladders, not aliases. A more expensive path never misses where a cheaper path hit.

path	What it does	Credit cap
speed	Homepage meta / Open Graph description with deterministic gates, then house AI Ark. Lowest spend.	1
balance	When path is omitted, this ladder runs and the cap is 6. With an explicit balance, cap 2. Homepage extracts + meta/og + AI Ark, ranked with Jev; optional light neutral rewrite (0.5). May fall back to speed’s text with same_as_speed.	2 explicit · 6 if path omitted
accuracy	Neutral third-person xAI compose from homepage evidence with one Jev identity check (compose 2). Falls back to the cheaper hit.	3
coverage	Accuracy compose plus off-homepage evidence (house websearch, 0.1) and ZoomInfo BYOK when you store a key. Falls back to the accuracy winner, so it cannot miss where accuracy hit.	6

Legacy aliases (fast, value, name_only → speed; auto → balance) expand to the paths above.

AI Ark is the only firmographic vendor. LeadMagic, Findymail, Wiza, Brandfetch, Lemlist, and Snov.io are not used for company.description. ZoomInfo is BYOK only (never the house key). See Vendor keys.

Hard rejects

These never become a hit:

• Wrong company: Jev identity below 0.85, or vendor domain/website not matching the subject.
• Junk or PII: emails, phones, navigation/cookie/footer text, URLs, mid-word cuts, nameless fragments.
• Empty: no usable text after the gates.

Audience claims (… to independent and mid-sized companies) must appear in the evidence as the company’s own customers. Otherwise the clause is dropped or the text is rejected. Learn more / Read more tails are stripped.

Billing and time

Winner-only billing: you pay only for the hop that produced the returned text (usage.credits.by_provider). Rejected and lost hops cost 0. A miss costs 0.

Every path has a hard 10 s cap from request start.

Forcing a fresh result

company.description and company.domain cache results (description: 30 days in D1; domain: short TTL in-isolate). To skip the cache read and re-run the ladder (the fresh answer is still written), send header X-Router-Cache: bypass (any other value returns 400 invalid_cache), or Cache-Control: no-cache / no-store, or body skip_cache: true. skip_cache must be a boolean; non-boolean values return 400 invalid_cache, same as a bad X-Router-Cache value. Reusing an Idempotency-Key still returns the stored response even with bypass flags. company.resolve ignores X-Router-Cache: bypass and skip_cache, so it may return a cached answer.

Input

The body accepts domain, website, email, name, plus:

• path (or routing.path): speed | balance | accuracy | coverage.
• max_chars: integer 80–500, default 300. Trims at a sentence boundary.
• skip_cache: boolean; non-boolean → 400 invalid_cache.
• external_ref: client correlation key, echoed on the run.
• routing: order, only, max_provider_credits, allow_fallbacks.
• dry_run: no credit spend.

Example response (balance hit)

{
  "ok": true,
  "schema_version": "2",
  "run_id": "run_01h2example",
  "capability": "company.description",
  "es_decision": "hit",
  "answer": {
    "outcome": "hit",
    "reason_code": "exact_one",
    "es_decision": "hit",
    "confidence": "high",
    "summary": "Site probe search hit via homepage_extract",
    "identity": { "method": "jev", "score": 0.96 }
  },
  "result": {
    "description": "OutboundSync connects outbound sales engagement platforms to CRMs.",
    "source_kind": "quoted",
    "language_note": null,
    "company_domain": "outboundsync.com",
    "compose_echo": false,
    "homepage_meta_only": false,
    "flags": {
      "hype": false,
      "first_person": false,
      "tagline": false,
      "same_as_speed": false,
      "truncated": false,
      "cta": false,
      "grammar": false
    }
  },
  "usage": {
    "credits": { "cap": 2, "spent": 0, "by_provider": { "aiark": 0 } },
    "hops": [{ "provider": "aiark", "status": "lost", "credits": 0 }]
  }
}

Example response (miss)

{
  "ok": true,
  "schema_version": "2",
  "capability": "company.description",
  "es_decision": "miss",
  "answer": {
    "outcome": "no_decision",
    "reason_code": "no_match",
    "es_decision": "miss",
    "confidence": null,
    "summary": "No decision (no_match)",
    "identity": null
  },
  "result": {
    "description": null,
    "source_kind": null,
    "language_note": null,
    "company_domain": "example-invalid.test",
    "compose_echo": false,
    "homepage_meta_only": false,
    "flags": null
  },
  "usage": { "credits": { "cap": 2, "spent": 0, "by_provider": {} }, "hops": [] }
}

Explain

Prefer X-Router-Explain: minimal on CRM callouts; it is an alias of the clean envelope. Use full when you need trace.attempts.

Salesforce External Services import openapi.es.yaml (operationId: companyDescription), not the full OpenAPI file. The ES response schemas accept extra fields.