Vinespire API

Read-only HTTP API for your Vinespire data. Available on the Agency plan.

Authentication

Every request must include an API key in the Authorization header. Generate keys in Settings → API.

Authorization: Bearer vsk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Base URL

https://vinespire.com/api/public/v1

GET /brands

List the brands you have access to.

curl https://vinespire.com/api/public/v1/brands \
  -H "Authorization: Bearer vsk_live_..."

{
  "data": [
    { "id": "uuid", "name": "Acme", "domain": "acme.com", "industry": "B2B SaaS", "is_self": true }
  ]
}

GET /score?brand_id=...

Latest Brand Authority score snapshot for a brand.

curl "https://vinespire.com/api/public/v1/score?brand_id=BRAND_UUID" \
  -H "Authorization: Bearer vsk_live_..."

GET /opportunities

Optimization opportunities sorted by score. Query params: brand_id, status, limit (max 200).

curl "https://vinespire.com/api/public/v1/opportunities?limit=20" \
  -H "Authorization: Bearer vsk_live_..."

GET /competitors

List the competitors you're tracking.

curl https://vinespire.com/api/public/v1/competitors \
  -H "Authorization: Bearer vsk_live_..."

GET /citations

Aggregate cited URLs from multi-sample AI visibility answers across your prompt set. Groups by page and domain, ranks by frequency, and returns concentration: these N pages account for X% of citations in your category. Query params: brand_id, engine (default gemini), top_n (default 5), lookback_days (default 28).

curl "https://vinespire.com/api/public/v1/citations?top_n=5" \
  -H "Authorization: Bearer vsk_live_..."

{
  "data": {
    "summary": { "total_citations": 42, "unique_pages": 18, "unique_domains": 9 },
    "concentration": {
      "pages": {
        "top_n": 5,
        "share_percent": 62,
        "label": "These 5 pages account for 62% of citations in your category"
      }
    },
    "pages": [{ "url": "https://g2.com/...", "citation_count": 12, "share_percent": 29 }],
    "domains": [{ "domain": "g2.com", "citation_count": 15, "share_percent": 36 }]
  }
}

GET /citation-comparison

Compare citation intelligence for your brand vs each tracked competitor (citation-count deltas). When a gap exceeds the threshold (default 3, or gap_threshold), automatically enqueues Competitor Reverse Engineering for that rival's top 10 cited pages. Query: auto_trigger (default true), brand_id, engine, top_n, gap_threshold.

curl "https://vinespire.com/api/public/v1/citation-comparison?auto_trigger=true" \
  -H "Authorization: Bearer vsk_live_..."

GET /uncontested-prompts

Prompts where no brand in the competitive set exceeds a recommendation threshold (default 15%). Ranked by free demand: Google Trends interest when available, else Source Mining mention frequency. Query: threshold, min_samples, engine, skip_trends.

curl "https://vinespire.com/api/public/v1/uncontested-prompts?threshold=15" \
  -H "Authorization: Bearer vsk_live_..."

GET /action-synthesis

Ranked GEO action list for the current (or recent) report cycle. Synthesizes Citation Gap, Competitor Reverse Engineering, uncontested prompts, and the customer's Crawlability Audit via a single Gemini generation per customer per ISO week. Query: limit (default 1).

curl "https://vinespire.com/api/public/v1/action-synthesis?limit=1" \
  -H "Authorization: Bearer vsk_live_..."

Errors

JSON envelope { "error": "..." } with appropriate HTTP status:

401: missing, malformed, revoked, or unknown key
403: key owner is no longer on the Agency plan
404: resource not found or not owned by you
500: internal error

Webhooks

Outbound webhooks are configured in Settings → Integrations. Events are signed with HMAC-SHA256 over the raw JSON body, sent in the X-Vinespire-Signature header.

X-Vinespire-Signature: sha256=<hex>
X-Vinespire-Event: opportunity.high_score