Vinespire API

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://www.vinespire.com/api/public/v1

GET /brands

List the brands you have access to.

curl https://www.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 GEO score snapshot for a brand.

curl "https://www.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://www.vinespire.com/api/public/v1/opportunities?limit=20" \
  -H "Authorization: Bearer vsk_live_..."

GET /competitors

List the competitors you're tracking.

curl https://www.vinespire.com/api/public/v1/competitors \
  -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