Quickstart - Vine API

Overview

Vine answers one question, live: what does this business run, and where does a customer act? Two calls:

Detect (POST /api/v1/detect): synchronous. Send a business URL; Vine renders the site, follows the booking/ordering CTAs, and returns the detected providers plus a detectionId. The service-side domain cache is disabled by default, so budget a minute or two for every call. When Vine explicitly enables it, an eligible recent domain can return in about a second and is flagged as cached.
Read the detection (GET /api/v1/detections/{id}): the resolved connections: per-provider actionType and actionUrl, the exact transaction surface an agent can act on.

Every request is authenticated with a Bearer API key. Signup includes 1,000 free credits, no card required (a live detect costs 12–26). Vine is in public beta. Detection is available today; structured data extraction from the providers it finds (schedules, menus, availability) is coming soon. Want it early? Email us.

Get an API key

Mint a key from the Vine console. The plaintext is returned once; store it immediately; it is never recoverable.

Response

{
  "key": {
    "id": "clz…",
    "name": "my-first-key",
    "keyPrefix": "vine_live_Ab",
    "plaintext": "vine_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "scopes": ["detect", "extractions:read"],
    "rateTier": "beta",
    "createdAt": "2026-07-06T18:00:00.000Z"
  }
}

Keys look like vine_live_…. Attach yours as a Bearer token on every request:

Authorization: Bearer vine_live_xxxxxxxxxxxxxxxx

Keep keys server-side. Never ship them to a browser or mobile client.

Detect providers (synchronous)

Send the business URL. detect blocks while Vine renders the site live and resolves the providers, typically 1–2 minutes, no polling.

curl -X POST https://vine.getcourtyard.ai/api/v1/detect \
  -H "Authorization: Bearer $VINE_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{ "url": "https://www.mindbodyonline.com/explore/locations/thesharpbarber" }'

const res = await fetch('https://vine.getcourtyard.ai/api/v1/detect', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.VINE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://www.mindbodyonline.com/explore/locations/thesharpbarber',
  }),
});

const { detectionId, providers, discoveredProviders } = await res.json();

A 200 OK returns the detected providers and a detectionId for the run:

{
  "schemaVersion": "extraction.v1",
  "detectionId": "det_01JX4MQTCPB9NZ7KXHVF3A2R8",
  "url": "https://www.mindbodyonline.com/explore/locations/thesharpbarber",
  "providers": ["mindbody"],
  "discoveredProviders": [],
  "durationMs": 68412,
  "creditsUsed": 14,
  "creditBreakdown": {
    "total": 14,
    "lines": [
      { "label": "detectBase", "credits": 10 },
      { "label": "pageScans", "credits": 4 }
    ]
  }
}

A slow site that hits the deadline returns { "status": "detection_incomplete" } (retryable, billed at the base rate only). Resubmit the same URL rather than a 5xx or a hang. Every billable response also carries vine-credits-used and vine-credits-remaining headers.

Fetch the resolved connections

The detectionId is your handle to the agent-ready payload: one connection per detected provider, with the resolved actionUrl: the exact page where a customer books, orders, or schedules.

cURL

curl https://vine.getcourtyard.ai/api/v1/detections/det_01JX4MQTCPB9NZ7KXHVF3A2R8 \
  -H "Authorization: Bearer $VINE_API_KEY"

Response

{
  "schemaVersion": "extraction.v1",
  "detectionId": "det_01JX4MQTCPB9NZ7KXHVF3A2R8",
  "url": "https://www.mindbodyonline.com/explore/locations/thesharpbarber",
  "fetchedUrl": "https://www.mindbodyonline.com/explore/locations/thesharpbarber",
  "providers": ["mindbody"],
  "discoveredProviders": [],
  "createdAt": "2026-07-06T18:01:12.000Z",
  "connections": [
    {
      "provider": "mindbody",
      "actionType": "book",
      "actionUrl": "https://widgets.mindbodyonline.com/widgets/appointments/…",
      "status": "active",
      "userConfirmed": null,
      "lastRefreshedAt": null,
      "hasParams": true
    }
  ]
}

That actionUrl is the point: instead of scraping a marketing site hunting for a “Book Now” button, your agent lands on the transaction surface in one call. (Raw provider params stay server-side; hasParams tells you they exist.)

Handling errors

Every error follows the same envelope:

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry shortly."
  }
}

HTTP	Meaning	Retryable
`401`	Missing, invalid, or revoked key	No. Check your key
`402`	Out of free-trial credits	No. Email us for a top-up
`404`	Detection not found, or not owned by this key	No
`422`	Validation failed; fix the request body	No
`429`	Rate limited (beta: 60 detects/hour)	Yes. Back off and retry

Next steps

Detect

Synchronous provider detection: request schema and response fields.

Get detection

The resolved connections: provider, actionType, actionUrl.

Coverage & limits

105 providers, how detection works, and the beta limits.

Examples

Runnable scripts: GTM enrichment, agent tools, vertical lenses.

​Overview

​Handling errors

​Next steps

Detect

Get detection

Coverage & limits

Examples

Overview

Handling errors

Next steps