Features Docs Log in Contact sales

API reference

Sonicbean API

Base URL: https://api.sonicbean.online/v1

Overview

The Sonicbean API lets you send product events and manage user profiles so funnels, retention, and feature adoption analyses stay accurate. All requests use HTTPS and JSON. Responses use standard HTTP status codes.

Typical flow: authenticate with a project API key, identify the user, then track events as users move through your product. Properties should be consistent with your event catalog so dashboards and cohorts remain trustworthy.

Authentication

Authenticate with a project write key in the Authorization header as a Bearer token. Create and rotate keys in your workspace settings under Project → API keys.

POST /v1/events HTTP/1.1
Host: api.sonicbean.online
Authorization: Bearer sk_live_••••••••••••
Content-Type: application/json

Never embed write keys in public client bundles without appropriate restrictions. Prefer server-side tracking for sensitive properties, or use a restricted client key with allowlisted event names.

Events

Endpoint: POST https://api.sonicbean.online/v1/events

Track a single product event. Event names should be stable, past-tense or noun-phrase labels your team agrees on (for example project_created).

{
  "event": "project_created",
  "user_id": "usr_8f2a1c",
  "timestamp": "2026-06-12T14:22:01Z",
  "properties": {
    "plan": "growth",
    "template": "blank",
    "source": "web"
  },
  "context": {
    "ip": "203.0.113.10",
    "user_agent": "Mozilla/5.0 …"
  }
}

Batch: POST https://api.sonicbean.online/v1/events/batch accepts an array under events (max 100 per request).

{
  "events": [
    { "event": "signed_up", "user_id": "usr_1", "properties": { "method": "sso" } },
    { "event": "invite_sent", "user_id": "usr_1", "properties": { "count": 3 } }
  ]
}

Successful single-event responses return 202 Accepted with a body such as { "status": "accepted", "id": "evt_…" }. Events are processed asynchronously for funnel and retention pipelines.

Users

Identify / upsert: POST https://api.sonicbean.online/v1/users

Attach traits to a user so you can segment funnels and retention by plan, role, company size, and other stable attributes.

{
  "user_id": "usr_8f2a1c",
  "traits": {
    "email": "alex@acme.com",
    "name": "Alex Morgan",
    "plan": "growth",
    "company_id": "org_991",
    "role": "admin"
  },
  "timestamp": "2026-06-12T14:20:00Z"
}

Retrieve: GET https://api.sonicbean.online/v1/users/{user_id} returns the latest traits and first/last seen timestamps for debugging identity resolution.

Alias: POST https://api.sonicbean.online/v1/users/alias merges an anonymous previous_id into a known user_id after sign-up so pre-auth behavior appears in the same journey.

Errors

Error bodies include a machine-readable code and human-readable message:

{
  "error": {
    "code": "invalid_payload",
    "message": "event is required"
  }
}
  • 400 — validation failed (missing event name, invalid JSON)
  • 401 — missing or invalid API key
  • 403 — key not allowed for this project or method
  • 429 — rate limited; retry with exponential backoff
  • 5xx — temporary server error; safe to retry idempotent sends with the same client-generated id

SDKs & implementation tips

Official lightweight clients are available for JavaScript (browser and Node), Python, and Go. They wrap authentication, batching, and retries for /v1/events and /v1/users.

  • Name events once in a shared catalog; avoid synonyms like signup and signed_up.
  • Send timestamps in UTC ISO-8601 when events are queued offline.
  • Prefer user_id over email for identity; store email as a trait.
  • Instrument activation and aha moments first—those power the most valuable funnels and retention views.

Questions about schema design or migration from another analytics stack? Contact our team or email hello@sonicbean.online.