Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vibefollow.com/llms.txt

Use this file to discover all available pages before exploring further.

The SDK handles this for you. Read on if you’re calling the REST endpoints directly — from a language without an official SDK, or for ad-hoc curl debugging.

​
The header

​
Full request example

curl https://api.vibefollow.com/api/v1/events \
  -X POST \
  -H "Authorization: Bearer $VIBEFOLLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "external_user_id": "usr_42",
    "name": "user_signed_up",
    "properties": { "plan": "trial" }
  }'
A success response: 
HTTP/1.1 202 Accepted
Content-Type: application/json

{ "data": { "accepted": true } }
202 Accepted confirms the event was enqueued, not that it has been fully processed. Vibefollow’s ingest pipeline is asynchronous — the event lands in your project’s event stream within a few hundred milliseconds.

​
Failure modes

Header missing, malformed, or key revoked. Body: { "errors": [{ "code": "auth_required", ... }] }.
Key valid but doesn’t authorise access to the resource (e.g. wrong project).
Request body failed validation. errors[0].field names the offending field.
Rate limited. Respect the Retry-After header.
Safe to retry — the Idempotency-Key prevents duplicates.
The full mapping to typed SDK errors is documented in Errors.

​
Idempotency in detail

The Idempotency-Key is required on every mutating request — the SDK auto-generates one if you don’t pass it. The backend dedupes within a 24-hour window keyed by (project_id, idempotency_key).
ScenarioResult
Same key + same body within 24hReturns the original response (the second request is a no-op)
Same key + different body within 24hRejected with 422 (code: "idempotency_key_reuse")
Same key after 24hThe key is forgotten; safe to reuse
Use a fresh UUID per logical write. Don’t share keys across unrelated events.

​
CORS

The API does not send Access-Control-Allow-Origin headers. The browser cannot call Vibefollow directly — build a server proxy if you need browser-originated events.

​
TLS

HTTPS only. Plaintext HTTP requests are refused at the edge with a redirect to https://. TLS 1.2+ required. We do not support TLS 1.0/1.1.