{
  "name": "Uniqueness Engine",
  "version": "2026-07-25",
  "commercial_contract": "hard-paid-v1",
  "base_url": "https://uniquenessengine.com",
  "llms_url": "https://uniquenessengine.com/llms.txt",
  "openapi_url": "https://uniquenessengine.com/openapi.json",
  "documentation_home_url": "https://uniquenessengine.com/documentation",
  "agent_setup_url": "https://uniquenessengine.com/agents",
  "notes": [
    "A brief usually takes 45-90s (up to ~2-3 min), so the PRIMARY flow is asynchronous: POST /api/enrich returns 202 {job_id, status:'queued'} (or 200 {status:'done', brief} on a cache hit), then poll GET /api/jobs/:id every ~5s until status is done, refused, or failed. When done, the brief is at result; cache-hit submit responses put it at top-level brief. The deprecated /api/brief compatibility alias follows the same async paid-admission contract; prefer /api/enrich for new integrations.",
    "Jordan Ellis is a fictional static synthetic fixture (mode:'synthetic_fixture', not_a_real_person:true, billing.charged:false) and the only free product experience. Never begin a real enrichment before the human has verified email and paid credit is available.",
    "Signup returns transaction_id and polling_token for a named email-verification transaction. Retain both only in the trusted caller, poll GET /api/signup/verification/:transaction_id with X-Verification-Token, and call /claim exactly once only after status is approved. The claimed key is named for client_name. The polling token and one-time key are credentials: never email, log, or relay them to an agent transcript. If signup returns 503 verification_delivery_failed, no usable polling secret or key was issued; honor Retry-After and begin a fresh transaction.",
    "Every surfaced Claim row includes a source URL and evidence quote that passed normalized grounding; directional aggregates and derived personality guidance are labeled as inferences. status: needs_review is not an error -- it means the engine could not verify enough to say anything, and that never charges a credit. On the async path this surfaces as a job status of refused.",
    "Response detail defaults to full in production. Pass ?detail=compact explicitly for identity, top-ranked safe_to_reference signals, one personality.how_to_communicate recommendation, compliance labels, and a `capabilities` block; pass ?detail=full explicitly for every claim array, sub-scores, and evidence[]. An invalid detail value returns 400 invalid_detail. Async /api/enrich responses include a poll_url that carries the resolved detail. Brief-body schemas and examples in GET /openapi.json are derived from the response serializer; endpoint envelopes, errors, and descriptive text are maintained separately. GET /api/examples/kitchen-sink returns a free synthetic sample brief. The product verifies and LABELS facts (sensitivity/attribution/confidence); it does not tell you what is safe to send -- the removed `safe_to_use_in_outreach` stamp, and the decommissioned `outreach_angles` / `gift_hook`, are declared in `capabilities` and never returned.",
    "Profiles and public social posts are read from multiple independent public-data providers with automatic fallback, so a single provider outage doesn't drop coverage.",
    "When fewer than 3 personal facts verify, additional verified public-source lanes engage automatically before any paid source. All candidates pass the same extraction, identity, grounding, and verification gates.",
    "New discovery hard-denies FEC, court-record, obituary, wedding, and people-search URLs, strips addresses at ingestion, and drops fetched pages that never name the target.",
    "Some verified public claims carry special_category: true (health, recovery, religion, politics, protected attributes). They are still surfaced -- the flag lets the caller decide how to use them. Home location and private contact info are never surfaced.",
    "Billing is provenance-aware: paid admission reserves credit, delivery settles the exact allocation, and refusal, wrong-person, no-result, or failure releases it. One credit always runs the full-quality written enrichment; no customer Lite/Deep choice exists.",
    "The repeatable 5-Pack is five permanent credits for a $5 USD tax-exclusive subtotal plus applicable tax. Larger permanent packs are 20/$7.40, 50/$18.50, and 100/$37. Existing subscriptions remain unchanged. Auto-recharge is separately consented and off by default. On canonical 402 payment_required, only recommended_offer.checkout_url (the offered pack) and billing_url (pack selector) are purchase actions, and only after explicit human consent; agents must never enable auto-recharge, save a method, subscribe, or purchase by inference.",
    "If a key is ever compromised and still available, POST /api/account/rotate-key revokes it immediately and returns a fresh one. If it is lost, sign in by email through /account and rotate all account keys.",
    "You can rate any brief 👍/👎 via POST /api/feedback (or the submit_feedback MCP tool / `uniqueness feedback` CLI) to improve the engine — this never touches billing. Return credit is a self-service credit remedy for a delivered poor brief; cash refunds are support-controlled exceptions, not an agent action."
  ],
  "status_model": {
    "terminal_success": ["ok"],
    "terminal_refusal": ["needs_review"],
    "async_job_status": {
      "pending": ["queued", "running"],
      "terminal_success": ["done"],
      "terminal_refusal": ["refused"],
      "terminal_error": ["failed"]
    }
  },
  "mcp": {
    "type": "local_package",
    "package": "uniqueness-mcp",
    "install": "npx -y uniqueness-mcp",
    "quickstart_url": "https://uniquenessengine.com/documentation/mcp/quickstart",
    "supported_tools": [
      "begin_programmatic_signup",
      "complete_programmatic_signup",
      "get_connection_brief",
      "resume_connection_brief",
      "get_billing_status",
      "preflight_connection_briefs",
      "submit_feedback"
    ],
    "optional_env": ["UNIQUENESS_API_KEY (durable preconfigured MCP key)"],
    "requires_key_for": [
      "get_connection_brief",
      "resume_connection_brief",
      "get_billing_status",
      "preflight_connection_briefs",
      "submit_feedback"
    ],
    "in_process_signup": "Without UNIQUENESS_API_KEY, begin_programmatic_signup then complete_programmatic_signup can configure only the currently running MCP process after human email approval. They never expose the key; a human uses /account for durable named-key setup.",
    "billing_safety": "MCP exposes no purchase, payment-method, auto-recharge, or subscription tool and stores no unpaid target. On human_action_required checkout, present payment_required.recommended_offer.checkout_url or payment_required.billing_url only after explicit human consent. To resume, the host must resupply the original target, payment_required.retry.idempotency_key, and payment_required.credits.available."
  },
  "cli": {
    "package": "uniqueness",
    "install": "npm install -g uniqueness",
    "npm_url": "https://www.npmjs.com/package/uniqueness",
    "billing_commands": [
      "uniqueness billing status",
      "uniqueness billing packs",
      "uniqueness billing subscriptions",
      "uniqueness billing portal",
      "uniqueness billing auto-recharge enable|disable|retry"
    ],
    "billing_safety": "Pack and subscription commands display exact terms and require a signed-in browser plus explicit human confirmation before opening a purchase surface. JSON and non-interactive use never opens a browser or starts a purchase. Auto-recharge is a separate explicit consent action."
  },
  "routing": [
    {
      "task": "Get personal + professional + personality (DISC) signal for one LinkedIn profile (primary, async)",
      "use": "POST /api/enrich, then poll GET /api/jobs/:id"
    },
    {
      "task": "Legacy single-profile alias (same paid async contract)",
      "use": "POST /api/brief, then poll its job_id when uncached; prefer POST /api/enrich"
    },
    {
      "task": "Start email verification for a new revocable API key",
      "use": "POST /api/signup with email + client_name + device_name; on 503 verification_delivery_failed honor Retry-After and start again, otherwise retain transaction_id + polling_token, poll GET /api/signup/verification/:transaction_id with X-Verification-Token, then claim exactly once after approved"
    },
    {
      "task": "Check credit balance and billing status",
      "use": "GET /api/account"
    },
    {
      "task": "Recover from a leaked or compromised API key",
      "use": "POST /api/account/rotate-key"
    },
    {
      "task": "Recover from canonical insufficient-credit response",
      "use": "Only after explicit human consent, present payment_required.recommended_offer.checkout_url for the offered pack or payment_required.billing_url to choose a pack; never use a payment-method setup route as a purchase"
    },
    {
      "task": "Review paid credit packs and explicit auto-recharge settings",
      "use": "GET /api/billing/catalog for read-only terms; Account billing after human authorization"
    },
    {
      "task": "Manage or cancel billing, update card, view invoices",
      "use": "POST /api/billing/portal"
    },
    {
      "task": "Rate a brief 👍/👎 so the engine improves (pass identity.canonical_id)",
      "use": "POST /api/feedback"
    },
    {
      "task": "Check service status",
      "use": "GET /api/health"
    }
  ],
  "endpoints": [
    {
      "id": "signup",
      "category": "auth",
      "path": "/api/signup",
      "method": "POST",
      "async": false,
      "auth": "none",
      "purpose": "Start named email verification. Retain both transaction_id and polling_token from the 202 response; approval enables exactly one client_name-named key claim and signup grants no live credit. A 503 verification_delivery_failed response contains no usable polling secret or key; honor Retry-After and start a fresh transaction.",
      "required_inputs": ["email"],
      "optional_inputs": ["client_name", "device_name"],
      "result_path": "$.transaction_id and $.polling_token",
      "docs_url": "https://uniquenessengine.com/documentation#signup"
    },
    {
      "id": "signup_verification",
      "category": "auth",
      "path": "/api/signup/verification/:transaction_id",
      "method": "GET",
      "async": false,
      "auth": "X-Verification-Token header",
      "purpose": "Poll a named verification request. Retain the original polling_token and send it as X-Verification-Token. Only status approved permits a claim; pending, denied, expired, and already_claimed do not disclose a key.",
      "required_inputs": ["transaction_id", "X-Verification-Token (the retained polling_token)"],
      "result_path": "$.status",
      "docs_url": "https://uniquenessengine.com/openapi.json"
    },
    {
      "id": "signup_claim",
      "category": "auth",
      "path": "/api/signup/verification/:transaction_id/claim",
      "method": "POST",
      "async": false,
      "auth": "X-Verification-Token header",
      "purpose": "After and only after approved, claim the newly minted key exactly once. Store it in a trusted secret manager or server environment; do not log or relay it through an agent.",
      "required_inputs": ["transaction_id", "X-Verification-Token (the retained polling_token)"],
      "result_path": "$.api_key (first approved claim only)",
      "docs_url": "https://uniquenessengine.com/openapi.json"
    },
    {
      "id": "enrich",
      "category": "core",
      "path": "/api/enrich",
      "method": "POST",
      "async": true,
      "auth": "bearer",
      "purpose": "PRIMARY. Submit one person for a fact-checked Connection Brief (personal signal, professional context, DISC personality read). Returns 202 {job_id, status:'queued'}, or 200 {status:'done', brief} on a cache hit. If callback_url is provided, returns 202 {status:'accepted', delivery:'callback'} and posts the terminal envelope to that URL. An exact provenance allocation is reserved on submit and released on refusal, wrong-person, no-result, or failure. Underfunded admission returns canonical 402 payment_required; only its recommended_offer.checkout_url or billing_url may be presented after explicit human consent.",
      "required_inputs": ["linkedin_url (or name + company)"],
      "optional_inputs": ["callback_url (https webhook URL for no-code tools)"],
      "result_path": "$.job_id",
      "poll_with": "GET /api/jobs/:id",
      "docs_url": "https://uniquenessengine.com/documentation#enrich"
    },
    {
      "id": "enrich_batch",
      "category": "core",
      "path": "/api/enrich/batch",
      "method": "POST",
      "async": true,
      "auth": "bearer",
      "purpose": "Submit up to 100 people at once. Pass {estimate_only:true} for a read-only estimate. A real submission normalizes and deterministically deduplicates inputs, then atomically reserves the full exact maximum and starts every chargeable row or starts none. Underfunded preflight returns canonical 402 payment_required and never triggers auto-recharge. Poll each returned job via GET /api/jobs/:id, or pass callback_url.",
      "required_inputs": ["profiles: [{linkedin_url} | {name, company}, ...]"],
      "optional_inputs": [
        "callback_url (https webhook URL applied to every queued profile)"
      ],
      "result_path": "$.enqueued[*].job_id",
      "poll_with": "GET /api/jobs/:id",
      "docs_url": "https://uniquenessengine.com/documentation#enrich"
    },
    {
      "id": "jobs",
      "category": "core",
      "path": "/api/jobs/:id",
      "method": "GET",
      "async": false,
      "auth": "bearer",
      "purpose": "Poll a job submitted via /api/enrich. Poll every ~5s. When status is 'done', the brief is at $.result. 'refused' means a needs_review brief (no charge); 'failed' means an error (no charge).",
      "required_inputs": ["id (job_id from /api/enrich)"],
      "result_path": "$.result",
      "docs_url": "https://uniquenessengine.com/documentation#jobs"
    },
    {
      "id": "brief",
      "category": "core",
      "path": "/api/brief",
      "method": "POST",
      "async": true,
      "auth": "bearer",
      "purpose": "Deprecated compatibility alias for the same paid async admission contract as /api/enrich. A cache hit returns 200 {status:'done',brief}; uncached work returns 202 {job_id,status:'queued',poll_url}. Prefer /api/enrich for new integrations. Refuses (needs_review) rather than guessing.",
      "required_inputs": ["linkedin_url (or name + company)"],
      "result_path": "$.brief on a cache hit, otherwise $.job_id",
      "poll_with": "GET /api/jobs/:id",
      "docs_url": "https://uniquenessengine.com/documentation#brief"
    },
    {
      "id": "account",
      "category": "account",
      "path": "/api/account",
      "method": "GET",
      "async": false,
      "auth": "bearer",
      "purpose": "Current credit balance and billing status.",
      "required_inputs": [],
      "result_path": "$.credits_remaining",
      "docs_url": "https://uniquenessengine.com/documentation#account"
    },
    {
      "id": "rotate_key",
      "category": "account",
      "path": "/api/account/rotate-key",
      "method": "POST",
      "async": false,
      "auth": "bearer",
      "purpose": "Revoke the calling key immediately and mint a fresh one. If the key is lost, sign in by email through /account and rotate all account keys.",
      "required_inputs": [],
      "result_path": "$.api_key",
      "docs_url": "https://uniquenessengine.com/documentation#rotate-key"
    },
    {
      "id": "billing_catalog",
      "category": "billing",
      "path": "/api/billing/catalog",
      "method": "GET",
      "async": false,
      "auth": "none",
      "purpose": "Canonical read-only permanent-pack and subscription terms plus the passwordless Account destination. Contains no account identity, target, credential, signed Checkout action, payment method operation, or purchase.",
      "required_inputs": [],
      "result_path": "$.packs and $.subscriptions",
      "docs_url": "https://uniquenessengine.com/openapi.json"
    },
    {
      "id": "billing_portal",
      "category": "billing",
      "path": "/api/billing/portal",
      "method": "POST",
      "async": false,
      "auth": "bearer",
      "purpose": "Stripe Customer Portal link -- cancel, update card, view invoices.",
      "required_inputs": [],
      "result_path": "$.portal_url",
      "docs_url": "https://uniquenessengine.com/documentation#billing"
    },
    {
      "id": "feedback",
      "category": "meta",
      "path": "/api/feedback",
      "method": "POST",
      "async": false,
      "auth": "bearer",
      "purpose": "Rate a brief 👍/👎 so the engine improves. Pass rating ('up'|'down') plus the brief's identity.canonical_id (or the job_id) and an optional note. It never changes billing; Return credit is the self-service credit remedy and cash refunds are support controlled.",
      "required_inputs": ["rating", "canonical_id (or job_id)"],
      "optional_inputs": ["note"],
      "result_path": "$.ok",
      "docs_url": "https://uniquenessengine.com/documentation#feedback"
    },
    {
      "id": "health",
      "category": "meta",
      "path": "/api/health",
      "method": "GET",
      "async": false,
      "auth": "none",
      "purpose": "Service status.",
      "required_inputs": [],
      "result_path": "$.ok",
      "docs_url": "https://uniquenessengine.com/documentation"
    },
    {
      "id": "example_fixture",
      "category": "meta",
      "path": "/api/examples/kitchen-sink",
      "method": "GET",
      "async": false,
      "auth": "none",
      "purpose": "Free, no-key, instant synthetic showcase brief ('Jordan Ellis'). Returns the full response shape marked mode:'synthetic_fixture', not_a_real_person:true, billing.charged:false. Defaults to the full shape; ?detail=compact for the compact shape. Use to see the contract without spending a credit or depending on a real person.",
      "required_inputs": [],
      "result_path": "$.safe_to_reference",
      "docs_url": "https://uniquenessengine.com/documentation"
    },
    {
      "id": "openapi",
      "category": "meta",
      "path": "/openapi.json",
      "method": "GET",
      "async": false,
      "auth": "none",
      "purpose": "Machine-readable OpenAPI 3.1 contract. Brief-body schemas and examples are derived from the response serializer; endpoint envelopes, errors, and descriptive text are maintained separately.",
      "required_inputs": [],
      "result_path": "$.openapi",
      "docs_url": "https://uniquenessengine.com/documentation"
    }
  ]
}