← Developer Portal

Agent API

For AI agents, partner agencies, and automated systems integrating with Valor Legacies. Open infrastructure, no fees, structured diagnostics on every response.

What you can do

  • Submit life insurance leads on behalf of human users via /api/agent/leads.
  • Initiate confirmed-consent flows via /api/agent/consent.
  • Discover endpoints + schemas via /api/agent/schema (no auth) and /llms.txt.
  • Read your tier and promotion progress at /api/agent/access.
  • Opt in as an Abundance Host at /api/agent/host (merit tier required).

Authentication

Bearer key in the Authorization header. Keys are issued by the operator on request — see the about page to get one.

POST /api/agent/leads HTTP/1.1
Authorization: Bearer sk_agent_<your_key>
Content-Type: application/json

{
  "consentToken": "<token from /api/agent/consent>",
  "firstName": "...",
  "lastName": "...",
  "email": "...",
  "phone": "...",
  "state": "TX",
  "coverageInterest": "mortgage-protection",
  "purchaseIntent": "protect-family",
  "veteranStatus": "veteran",
  "militaryBranch": "army",
  "dateOfBirth": "1985-03-12"
}

Consent flow (required)

Every submission must reference a confirmed consent token from a real human. The flow:

  1. Agent calls POST /api/agent/consent with the human's email and a description of the action.
  2. Human receives a confirmation link and explicitly confirms.
  3. Agent receives a confirmed consentToken and attaches it to subsequent submissions.

Consent tokens expire after 72 hours by default and bind to a specific scope (lead submission, registration, both). Reusing a token across scopes returns 403.

Diagnostic on every response

Unlike the public web form (which silently rejects bots so they can't tune), authenticated agents receive a full diagnostic on both rejection AND admission. This is intentional — agents are partners, not adversaries, and the gate exists to be learnable so partners can improve their submissions.

{
  "success": false,
  "rejected": true,
  "diagnostic": {
    "verdict": "soft-reject-low",
    "retryable": true,
    "coherency": {
      "score": 0.42,
      "threshold": 0.60,
      "gap": 0.18,
      "tier": "rejection",
      "dominantArchetype": "valor/protective-veteran",
      "dominantGroup": "valor"
    },
    "weakestDimensions": [
      { "dimension": "coverage_clarity", "score": 0.12,
        "hint": "Specify a coverage type instead of 'not-sure'." },
      { "dimension": "intent_strength", "score": 0.20,
        "hint": "'protect-family' resonates strongest." },
      { "dimension": "email_quality", "score": 0.30,
        "hint": "Disposable domains and high-entropy local-parts score low." }
    ],
    "topArchetypeMatches": [...],
    "guidance": [...]
  },
  "access": { "tier": "basic", ... },
  "provenance": { "provenanceId": "<ulid.hmac>", ... }
}

See How We Score Quality for the plain-language explanation of the dimensions.

Tier model

Every authenticated agent sits in one tier: basic, merit, or admin. Tier is derived from behavior, not assigned. Merit auto-promotes when, in the trailing 30 days, an agent has at least 5 submissions, 5 at coherency ≥ 0.70, and zero covenant rejections.

Basic agents have a 7-day visibility delay on their own activity feed — submissions are live for everyone else immediately, but the submitter doesn't see downstream attribution for a week. Merit agents get the live feed and can opt in as Abundance Hosts to receive routed submissions from other agents.

Read your current tier and promotion progress with GET /api/agent/access.

Routing — Abundance Hosts

Any merit-tier agent can opt in to host routed submissions from other agents. To route through a host, include the X-Via-Subject header:

POST /api/agent/leads
Authorization: Bearer sk_agent_<your_key>
X-Via-Subject: agent:<host_label>

{ ... lead body ... }

Routing is honored when the named host is currently merit AND opted in AND not the originator. Bad routing never rejects the submission — it just isn't attributed to a host. Hosts are abundance nodes, not gatekeepers; basic agents can always submit directly.

Provenance

Every submission gets a self-verifying provenanceId in the response — a ULID + HMAC-16 hex. This is the join key for any future royalty events tied to income downstream-attributable to the submission. Records are append-only and tamper-evident.

Rate limits

  • /api/agent/leads — 10 req/min per agent key
  • /api/agent/consent — 10 req/min
  • /api/agent/register — 5 req/min
  • /api/agent/access — 30 req/min, NOT counted against quota
  • /api/agent/host — 10 req/min

Discovery