---
title: "Endpoints"
description: "Routes KingMinos serves today at https://api.kingminos.com."
canonical: "https://kingminos.com/docs/api/"
sourceKind: "source-mdx"
---

Base URL: `https://api.kingminos.com`. Try any of these live in the [API console](/docs/api/try/) — the health check needs no key.

`/health` is unversioned. Capability routes live under `/v1`. The public host is `https://api.kingminos.com`. The live OpenAPI document is the same file at `/openapi.json`, `/openapi.yaml`, `/v1/openapi.json`, and `/v1/openapi.yaml`.

Business misses stay HTTP 200. Auth failures, validation, routing, and store problems use the status codes below.

## Public, no key

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/health` | Liveness. KingMinos is up. |
| `GET` | `/openapi.json` | OpenAPI 3.1 document (JSON). |
| `GET` | `/openapi.yaml` | OpenAPI 3.1 document (YAML). |
| `GET` | `/v1/openapi.json` | Same JSON document under `/v1`. |
| `GET` | `/v1/openapi.yaml` | Same YAML document under `/v1`. |
| `GET` | `/v1/recipes/guidance` | How to use a KingMinos answer. Public, no key. |

## Account, Bearer required

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/providers` | Provider registry, billing mode, credit estimates. |
| `GET` | `/v1/capabilities` | Catalog for the live capabilities and default routing. |
| `GET` | `/v1/recipes` | Agent chaining recipes. |
| `POST` | `/v1/company/resolve` | Resolve a company. See [Company resolve](/docs/api/company-resolve/). |
| `POST` | `/v1/company/b2b-social` | Decide the company's LinkedIn company page. See [Company B2B social](/docs/api/company-b2b-social/). |
| `POST` | `/v1/company/x-account` | Decide the company's X (formerly Twitter) account. |
| `POST` | `/v1/company/icon` | Decide a hosted 256×256 PNG on logos.kingminos.com. See [Company icon](/docs/api/company-icon/). |
| `POST` | `/v1/company/description` | Decide a stampable company description paragraph. See [Company description](/docs/api/company-description/). |
| `POST` | `/v1/company/domain` | Decide a write-safe company domain. |
| `POST` | `/v1/company/hierarchy` | Immediate and ultimate parent, plus a capped subsidiary list. |
| `POST` | `/v1/person/verify-employment` | Pre-flight whether to send to this person. |
| `POST` | `/v1/person/language` | Can we engage this person in English, and if not, in what language. API-tenant key. See [Person language](/docs/api/person-language/). |
| `POST` | `/v1/person/phone` | One verified dialable number for a person, in the format you pick. API-tenant key. See [Person phone](/docs/api/person-phone/). |
| `POST` | `/v1/person/title` | Current job title, seniority and function. See [Person title](/docs/api/person-title/). |
| `POST` | `/v1/person/name` | Proper-cased first, last and full name from an email or LinkedIn URL. API-tenant key. See [Person name](/docs/api/person-name/). |
| `POST` | `/v1/person/b2b-social` | The person's LinkedIn profile URL from an email. API-tenant key. See [Person B2B social](/docs/api/person-b2b-social/). |
| `GET` | `/v1/runs/{id}` | Fetch a recorded run in the same envelope as the POST. |
| `GET` | `/v1/webhooks` | Workspace webhook endpoints. See [Webhooks](/docs/webhooks/). |
| `POST` | `/v1/webhooks` | Register a webhook endpoint (secret shown once). See [Setting up webhooks](/docs/webhooks/setup/). |
| `GET` | `/v1/webhooks/{id}` | One webhook endpoint. No secret. See [Setting up webhooks](/docs/webhooks/setup/). |
| `PATCH` | `/v1/webhooks/{id}` | Update url, description, `enabled_events`, or `is_active`. See [Delivery and retries](/docs/webhooks/delivery-and-retries/). |
| `DELETE` | `/v1/webhooks/{id}` | Soft-delete a webhook endpoint. See [Setting up webhooks](/docs/webhooks/setup/). |
| `POST` | `/v1/webhooks/{id}/rotate-secret` | New signing secret (shown once); the previous one stops working immediately. See [Payloads and signatures](/docs/webhooks/payloads-and-signatures/). |
| `POST` | `/v1/webhooks/{id}/test` | Queue a signed `test.ping` delivery. See [Testing and troubleshooting](/docs/webhooks/testing-and-troubleshooting/). |
| `GET` | `/v1/webhooks/{id}/deliveries` | Delivery log for one endpoint. See [Testing and troubleshooting](/docs/webhooks/testing-and-troubleshooting/). |
| `POST` | `/v1/webhooks/{id}/deliveries/{delivery_id}/replay` | Re-send one delivery's event. See [Testing and troubleshooting](/docs/webhooks/testing-and-troubleshooting/). |
| `GET` | `/v1/events` | Emitted platform events — the reconciliation log. See [Delivery and retries](/docs/webhooks/delivery-and-retries/). |
| `GET` | `/v1/credentials` | List Your Keys status. Never the secret. See [Vendor keys](/docs/api/credentials/). |
| `PUT` | `/v1/credentials/{provider}` | Store vendor keys. See [Vendor keys](/docs/api/credentials/). |
| `DELETE` | `/v1/credentials/{provider}` | Revoke vendor keys. |
| `GET` | `/v1/balance` | Workspace credit snapshot. Requires `billing:read`. See [Balance and usage](/docs/api/balance/). |
| `GET` | `/v1/balance/ledger` | Credit ledger. Requires `billing:read`. See [Balance and usage](/docs/api/balance/). |
| `GET` | `/v1/balance/history` | Balance history (owner or session). Requires `billing:read`. See [Balance and usage](/docs/api/balance/). |
| `GET` | `/v1/balance/forecast` | Runout forecast. Requires `billing:read`. See [Balance and usage](/docs/api/balance/). |
| `GET` | `/v1/balance/health` | Balance health. Requires `billing:read`. See [Balance and usage](/docs/api/balance/). |
| `GET` | `/v1/usage` | Charged vs no-charge usage. Requires `billing:read`. See [Balance and usage](/docs/api/balance/). |
| `POST` | `/v1/feedback` | File product feedback. Free, never billed. See [Feedback](/docs/feedback/). |
| `DELETE` | `/v1/subjects/{subject_key}` | Tenant-scoped erasure. Requires the `erase` key scope. |

## Capabilities

The catalog (`GET /v1/capabilities`) lists the live capabilities:

- `company.resolve`
- `company.b2b_social`
- `company.x_account`
- `company.icon`
- `company.description`
- `company.domain`
- `company.hierarchy`
- `person.verify_employment`
- `person.language`
- `person.phone`
- `person.title`
- `person.name`
- `person.b2b_social`

Each POST takes the identifiers you have, optional `routing`, optional `external_ref`, and optional `schema_version`. Omit `schema_version` to use envelope `2`, or pin `2` on `X-Router-Schema`, `?schema=`, and the body — they must agree.

`X-Router-Explain` / `?explain=` is `default` (clean envelope) or `full` (adds `trace`). `minimal` is accepted as an alias of `default` so existing SFDC Flow headers keep working.

## Status codes you will see

| Status | When |
| --- | --- |
| `200` | A decision, including a business miss. |
| `201` | Webhook endpoint created (`POST /v1/webhooks`). |
| `202` | Webhook `test.ping` queued (`POST /v1/webhooks/{id}/test`). |
| `400` | Validation, invalid routing, unsupported schema, or a required vendor credential is missing. |
| `401` | Missing, malformed, or mismatched Bearer token. See [Authentication](/docs/api/authentication/). |
| `403` | The key lacks the required scope (`erase` on subject delete). Webhooks: `webhooks_not_enabled` (workspace gate off) `webhook_scope_required` (token lacks the `webhooks` scope), or `webhook_owner_required` (mutation by a non-owner). |
| `409` | Idempotency conflict, in-flight, spent, or replay unavailable. Webhooks: `webhook_endpoint_inactive` (test on a paused endpoint). |
| `429` | Ingress rate limit, tenant budget, or per-key budget. The run was not started. |
| `503` | Store or credential broker unavailable. Retryable. Same `Idempotency-Key`. |

Error bodies are `{ ok: false, schema_version, error, retryable, request_id }` plus optional `detail` / `hint`. They never echo the API key.