The Gossip API is organised around REST. It has predictable, resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP verbs, status codes and authentication. The base URL is:

https://api.gossipbuzz.app/v1

Endpoints are read-only by default and served by a dedicated FastAPI service backed by the same data as the app, so the public contract never diverges from the source of truth. You manage keys, webhooks and usage from the developer dashboard.

Authenticate by passing your secret API key as a bearer token. Create keys in the dashboard under API & Keys; the full secret is shown exactly once at creation and stored only as a hash — if you lose it, revoke and create a new one.

curl https://api.gossipbuzz.app/v1/buzzes \
  -H "Authorization: Bearer gsk_live_••••••••"

All requests must be made over HTTPS. Requests without a valid key return 401 Unauthorized. Never expose a live key in client-side code.

Keys come in two modes. gsk_test_… keys hit a sandbox with test data and never affect real accounts or spend. gsk_live_… keys hit production. The prefix tells you which mode a key is in at a glance.

Reads are free (only bandwidth is metered). You pay per call for writes, OTP, promo messages and AI. Every response returns its cost in the X-Gossip-Cost-Usd header (USD), and daily totals appear under Usage & analytics. Live numbers are at GET /v1/pricing, and the dashboard has an interactive Cost calculator.

Plans:

Exceeding the free daily cap returns 429; Pro-only endpoints return 402 on the Free plan. Cost is metered and reported (not yet auto-debited).

A daily request cap applies per key by plan: Free 100/day, Pro 100,000/day, Scale custom. Exceeding it returns 429 Too Many Requests. Track consumption live under Usage & analytics.

Messaging caps (anti-spam, WhatsApp-style):

Hitting a messaging cap returns 429. Recipients can also turn off promotional messages or block you entirely (then the send records but delivered: false).

Gossip uses conventional HTTP status codes. 2xx means success, 4xx indicates a problem with the request, and 5xx indicates a server error. Error bodies are JSON:

{
  "error": {
    "type": "invalid_request",
    "message": "Unknown profile username."
  }
}

List endpoints are cursor-paginated. Pass limit (max 100) and the next_cursor from the previous response as cursor. When next_cursor is null, you have reached the end.

GET /v1/buzzes?author=mohan&limit=20&cursor=b_8f2c…

Retrieve a public profile by username.

{
  "username": "mohan",
  "full_name": "Mohan Singh",
  "category": "personal",
  "followers": 12840,
  "buzzes": 312,
  "verified": true
}

List recent public buzzes, optionally filtered by author, or fetch a single buzz by id.

{
  "id": "b_8f2c…",
  "type": "text",
  "text": "दार्चुलाको कोसेली",
  "reactions": 128,
  "comments": 14,
  "created_at": "2026-06-10T09:21:00Z"
}

List recent public sips (short-form video / image posts), optionally filtered by author.

{
  "items": [
    {
      "id": "s_2a9c…",
      "author_id": "p_77f1…",
      "author_username": "mohan",
      "caption": "Sunrise over Api Himal 🌄",
      "media_type": "video",
      "video_url": "https://cdn.gossipbuzz.app/sips/…",
      "thumbnail_url": "https://cdn.gossipbuzz.app/sips/…_thumb",
      "like_count": 240,
      "comment_count": 18,
      "view_count": 5120,
      "created_at": "2026-06-09T05:00:00Z"
    }
  ],
  "next_cursor": null
}

List a creator’s public Studio assets — the photos and videos they’ve saved in Creator Studio for reuse across buzzes and sips. Only persistent (paid) assets are returned; ephemeral free-tier AI generations, forms and notes are never exposed.

{
  "items": [
    {
      "id": "sa_4d1f…",
      "kind": "photo",
      "url": "https://cdn.gossipbuzz.app/studio/…",
      "thumbnail_url": "https://cdn.gossipbuzz.app/studio/…_thumb",
      "title": "Sunrise over Api Himal",
      "width": 1920,
      "height": 1080,
      "tags": ["landscape", "darchula"],
      "created_at": "2026-06-09T04:12:00Z"
    }
  ],
  "next_cursor": null
}

Search public profiles (by username / name) and buzzes (by text). Returns both unless you scope it with type.

{
  "query": "nepal",
  "profiles": [
    { "username": "mohan", "full_name": "Mohan Singh", "verified": true, "followers": 12840 }
  ],
  "buzzes": [
    { "id": "b_8f2c…", "type": "text", "text": "दार्चुलाको कोसेली" }
  ]
}

A profile’s published Services (from its About → Services section). Returns an empty list if the section isn’t published.

[
  { "id": "sv_1a…", "name": "Logo design", "duration": "3 days",
    "category": "Design", "accepts_bookings": true }
]

Published Catalog items — products with prices, stock and images. Prices are display-only (price_currency is coin or usd).

[
  { "id": "ci_9f…", "name": "Pashmina shawl", "department": "Apparel",
    "price_amount": "2500", "price_currency": "coin", "in_stock": true,
    "images": ["https://cdn.gossipbuzz.app/…"] }
]

Published FAQ entries for a profile.

[
  { "id": "fq_3c…", "question": "Do you ship abroad?",
    "answer": "Yes, worldwide via DHL.", "category": "Shipping" }
]

The list of published About sections a profile has, in display order — useful to know which of the above to fetch.

[
  { "id": "ps_…", "kind": "services", "position": 0, "status": "published" },
  { "id": "ps_…", "kind": "catalog",  "position": 1, "status": "published" }
]

Writes require a real key and act only on your own content — a key can never modify another account. Buzzes and sips are delete-only (creating/editing posts is intentionally not exposed); Studio is fully manageable below.

curl -X DELETE https://api.gossipbuzz.app/v1/buzzes/b_8f2c… \
  -H "Authorization: Bearer gsk_live_••••••••"

{ "ok": true, "id": "b_8f2c…" }

Returns 404 if the post doesn’t exist or isn’t yours. Deletes are soft (recoverable by support).

Full CRUD over your own Creator Studio photos & videos. Upload the file to your own storage first, then register the URL here so it can be reused across buzzes and sips.

curl -X POST https://api.gossipbuzz.app/v1/studio \
  -H "Authorization: Bearer gsk_live_••••••••" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "photo", "url": "https://cdn.you.app/a.jpg",
        "title": "Api Himal", "tags": ["landscape"] }'

Register HTTPS endpoints in the dashboard to receive events as they happen. Each webhook has its own signing secret (shown once). Every delivery includes a signature header you should verify before trusting the payload:

X-Gossip-Signature: sha256=HMAC_SHA256(secret, raw_body)

Verify it in your handler (Node example):

import crypto from 'node:crypto'

function verify(rawBody, header, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex')
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header))
}

Respond with 2xx within 5 seconds. Non-2xx responses are retried with exponential backoff. Rotate the secret any time — the previous one stops working immediately.

Send an in-app verification code, then verify what the user entered. The code is delivered to the recipient as a “Gossip OTP” push (no carrier SMS needed) and is never returned to you. $0.0001 per code; available on every plan, including Free. Codes expire after 5 minutes.

1. Send

curl -X POST https://api.gossipbuzz.app/v1/otp/send \
  -H "Authorization: Bearer gsk_live_••••••••" \
  -d '{"to":"+9779800000000"}'

{ "id": "ot_…", "status": "sent", "channel": "in_app", "cost_usd": 0.0001, "delivered": true }

2. Verify the code the user typed back to you (free):

curl -X POST https://api.gossipbuzz.app/v1/otp/verify \
  -H "Authorization: Bearer gsk_live_••••••••" \
  -d '{"to":"+9779800000000","code":"123456"}'

{ "verified": true }

Send an in-app promotional message, WhatsApp/Instagram-style. Choose the channel with via: profile lands in the recipient's profile chat as your profile name (creator/Instagram-style); account lands in their contact chat as your account/business name (WhatsApp-Business-style). Defaults by your account type (business → account, personal → profile). $0.01 per message; Pro.

Every recipient controls this: they can turn off promotional messages or block your account, and per-user rate caps + spam protection apply. If the recipient has opted out, the response is delivered: false with a reason.

curl -X POST https://api.gossipbuzz.app/v1/promo/send \
  -H "Authorization: Bearer gsk_live_••••••••" \
  -H "Content-Type: application/json" \
  -d '{ "to": "p_77f1…", "text": "20% off this week 🎉", "via": "profile" }'

{ "id": "pr_…", "status": "sent", "channel": "profile", "cost_usd": 0.01, "delivered": true }

Generate drafts, captions and replies. Pro plan + a configured AI provider (returns 402 without Pro, 503 if AI is unconfigured). $0.01 per call.

curl -X POST https://api.gossipbuzz.app/v1/ai/generate \
  -H "Authorization: Bearer gsk_live_••••••••" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "Write a 1-line caption for a sunrise over Api Himal." }'

{ "text": "First light on Api Himal — दार्चुलाको कोसेली 🌄", "model": "…", "cost_milli": 5000 }

Build a conversational bot — pass the message history and get the assistant's next reply. Keep your own conversation state and send the recent turns each call. Pro plan + a configured provider. $0.01 per call.

curl -X POST https://api.gossipbuzz.app/v1/ai/chat \
  -H "Authorization: Bearer gsk_live_••••••••" \
  -H "Content-Type: application/json" \
  -d '{ "system": "You are a helpful Gossip support bot.",
        "messages": [{ "role": "user", "content": "How do I create a key?" }] }'

{ "reply": "Open the dashboard → API & Keys → New app…", "role": "assistant",
  "model": "…", "cost_usd": 0.01 }

Classify text for unsafe content before you publish or store it. $0.002 per call. Pro plan required.

{ "flagged": false, "categories": [], "model": "moderation" }