api & mcp server

Authorization: Bearer hyv_live_<your-key>

curl https://holdyourvoice.com/v1/usage \
  -H "Authorization: Bearer hyv_live_<your-key>"

{
  "error": "Profile query 'Growth' is ambiguous — matched 2 profiles...",
  "error_code": "profile_ambiguous",
  "query": "Growth",
  "candidates": [
    { "id": "...", "name": "Growth Inc",  "business": "Growth Inc", "slug": "growth-a" },
    { "id": "...", "name": "Growth Labs", "business": "Growth Labs", "slug": "growth-b" }
  ]
}

curl -X POST https://holdyourvoice.com/v1/analyze \
  -H "Authorization: Bearer hyv_live_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "our platform leverages best-in-class ai to deliver robust synergies",
    "brand": "Acme Co"
  }'

{
  "highlights": [
    { "text": "leverages best-in-class ai", "signal": "corporate_filler", "severity": "high", "suggestion": "try: uses ai" },
    { "text": "robust synergies",          "signal": "buzzword_stacking", "severity": "high", "suggestion": "try: real results" }
  ],
  "signal_score_delta":   { "corporate_filler": -28, "buzzword_stacking": -30 },
  "trust_tools_present":  [],
  "trust_tools_missing":  [ "specific_numbers", "attributed_quote" ],
  "profile_id": "550e8400-e29b-41d4-a716-446655440000",
  "remaining": { "documents": 47, "rewrites": null },
  "cost": {
    "paid_by": "hyv_platform",
    "model": "claude-haiku-4-5-20251001",
    "input_tokens": 420,
    "output_tokens": 180
  }
}

curl -X POST https://holdyourvoice.com/v1/rewrite \
  -H "Authorization: Bearer hyv_live_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "leverages best-in-class ai to deliver robust synergies",
    "issue": "corporate_filler",
    "brand": "acme-co"
  }'

{
  "rewritten": "uses ai to get real results",
  "original":  "leverages best-in-class ai to deliver robust synergies",
  "profile_id": "550e8400-e29b-41d4-a716-446655440000",
  "remaining": { "documents": 47, "rewrites": null },
  "cost": {
    "paid_by": "hyv_platform",
    "model": "claude-haiku-4-5-20251001",
    "input_tokens": 180,
    "output_tokens": 95
  }
}

curl https://holdyourvoice.com/v1/profiles \
  -H "Authorization: Bearer hyv_live_<your-key>"

{
  "profiles": [
    {
      "id":          "550e8400-...",
      "name":        "Acme Co",
      "business":    "Acme Corporation",
      "slug":        "acme-co",
      "industry":    "saas",
      "voice_keywords":    [ "direct", "specific", "first-person" ],
      "voice_descriptions": { "direct": "...", "specific": "..." },
      "is_default":  true,
      "ownership":   "own",
      "team_id":     null,
      "created_at":  "2026-02-10T12:00:00Z",
      "updated_at":  "2026-04-18T09:14:22Z"
    },
    {
      "id":         "6ba7b810-...",
      "name":       "Shared Brand",
      "business":   "Shared Brand LLC",
      "slug":       "shared-brand",
      "ownership":  "team",
      "team_id":    "team-acme-0000",
      "is_default": false
      /* ... */
    }
  ]
}

{
  "plan":          "team",
  "plan_active":   true,
  "is_byok":       false,
  "token_billing": "hyv_platform",
  "period":        "2026-04",
  "documents_used": 12,
  "rewrites_used":  0,
  "remaining":     { "documents": 288, "rewrites": null },
  "limits": {
    "documents": 300,
    "rewrites":  null,
    "rpm":       60
  },
  "quota_model": {
    "document_create": "counted_monthly",
    "analyze":         "unmetered",
    "rewrite":         "unmetered_monthly_legacy"
  },
  "by_brand_30d": [
    { "profile_id": "550e...", "name": "Acme Co",       "slug": "acme-co",       "scope": "own",          "analyses": 47, "rewrites": 18, "input_tokens": 32100, "output_tokens": 9200 },
    { "profile_id": "6ba7...", "name": "Shared Brand",  "slug": "shared-brand",  "scope": "team",         "analyses": 22, "rewrites":  5, "input_tokens": 14500, "output_tokens": 3400 },
    { "profile_id": null,      "name": null,            "slug": null,            "scope": "unattributed", "analyses":  3, "rewrites":  0, "input_tokens":  1900, "output_tokens":  400 }
  ]
}

curl -X POST https://holdyourvoice.com/v1/documents \
  -H "Authorization: Bearer hyv_live_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "title":   "q2 product announcement",
    "content": "your draft text here...",
    "brand":   "Acme Co"
  }'

curl -X PUT https://holdyourvoice.com/v1/documents/doc_abc123 \
  -H "Authorization: Bearer hyv_live_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{ "content": "updated draft..." }'

set up hold your voice mcp in this local agent environment.

context:
- hold your voice api and mcp access require an active paid plan. this key was created from a paid account.
- the public setup contract is https://holdyourvoice.com/.well-known/agent-onboarding
- the mcp server card is https://holdyourvoice.com/.well-known/mcp/server-card.json

requirements:
1. use this api key as HYV_API_KEY: <paste-your-api-key-here>
2. do not print the key back to me, commit it, or store it in a shared project file.
3. download https://holdyourvoice.com/mcp_server.py or reuse an existing local copy if it is already present.
4. configure an mcp server named hyv with command "python3" and args pointing at the local mcp_server.py file.
5. set HYV_BASE_URL to https://holdyourvoice.com unless i explicitly gave you another endpoint.
6. install /hyv-status from https://holdyourvoice.com/.well-known/agent-commands/hyv-status.md if your agent supports custom slash commands.
7. verify the setup by calling hyv_get_context, hyv_get_usage, and hyv_list_profiles.
8. after verification, use /hyv-status for account context, use hyv_analyze before hyv_rewrite, use brand names or slugs when a brand is mentioned, and ask before overwriting documents.

expected result:
- tell me where you placed the mcp server file.
- tell me which mcp config you updated.
- confirm the usage and profile tools worked.
- do not include the raw api key in your final response.

curl -O https://holdyourvoice.com/mcp_server.py

{
  "mcpServers": {
    "hyv": {
      "command": "python3",
      "args": ["/path/to/mcp_server.py"],
      "env": {
        "HYV_API_KEY": "hyv_live_..."
      }
    }
  }
}

/hyv-status

source: https://holdyourvoice.com/.well-known/agent-commands/hyv-status.md

what it does:
- calls hyv_get_context
- shows plan, byok billing, quota, profiles, and recent documents
- shows per-user rollups for team and byok accounts
- keeps raw api keys and secrets out of the response

user:   analyze this draft against our acme voice and fix anything off-brand

claude: → hyv_resolve_brand(brand="acme")
        ← { "matched": { "name": "Acme Co", "slug": "acme-co", "id": "550e..." }, "via": "partial" }

claude: → hyv_analyze(text="...", brand="acme-co")
        ← { "highlights": [...], "cost": { "paid_by": "hyv_platform", "input_tokens": 420, ... } }

claude: → hyv_rewrite(text="leverages best-in-class ai", issue="corporate_filler", brand="acme-co")
        ← { "rewritten": "uses ai", "cost": { ... } }

claude: here's your draft with 3 fixes for the acme voice: ...

# your agent in python, n8n, or any tool that supports http

import requests

key = "hyv_live_..."
headers = {"Authorization": f"Bearer {key}"}
base = "https://holdyourvoice.com"

# 1. agent writes a draft
draft = llm.generate(brief)

# 2. create the document, tagged with the right brand
doc = requests.post(f"{base}/v1/documents",
  headers=headers,
  json={"title": "q2 announcement", "content": draft, "brand": "Acme Co"}
).json()

# 3. analyze against the same brand
result = requests.post(f"{base}/v1/analyze",
  headers=headers,
  json={"text": draft, "brand": "Acme Co"}
).json()

print(f"tokens used: {result['cost']['input_tokens']} in / "
      f"{result['cost']['output_tokens']} out — paid by {result['cost']['paid_by']}")

# 4. rewrite any high-severity flags against the same brand
for flag in result["highlights"]:
  if flag["severity"] == "high":
    fix = requests.post(f"{base}/v1/rewrite",
      headers=headers,
      json={"text": flag["text"], "issue": flag["signal"], "brand": "Acme Co"}
    ).json()
    draft = draft.replace(flag["text"], fix["rewritten"])

# 5. update document with clean version
requests.put(f"{base}/v1/documents/{doc['id']}",
  headers=headers,
  json={"content": draft}
)

# 6. check per-brand spend at end of run
usage = requests.get(f"{base}/v1/usage", headers=headers).json()
for brand in usage["by_brand_30d"]:
  print(f"{brand['name'] or 'unattributed'}: "
        f"{brand['analyses']} analyses + {brand['rewrites']} rewrites "
        f"({brand['input_tokens']}+{brand['output_tokens']} tokens)")