Developer Guide

Plans & pricing API

Fetch published packages and prices without authentication. Use these endpoints to show gellhub plans on your own site or to obtain planId for POST /api/register or POST /api/billing/checkout-session. When you pass your integration client_id, results are limited to the product line you chose for that app in the Developer Console (Client Gallery or Drive).

Base URL examples: https://gellhub.com/api/public/plans?type=drive · https://gellhub.com/api/public/plans?client_id=YOUR_CLIENT_ID

Embedded connect (external sites & add-ons)

Use this when your product sends users to gellhub to sign up or subscribe; after checkout they return to your registered redirect URL with a one-time code. Only your backend can exchange the code, using your client id and client secret (OAuth-style confidential client). Never log the code or secret in the browser.

{}

{
  "code": "from_return_url_query",
  "client_id": "same as start",
  "client_secret": "from server env only"
}

After sign-in or registration, gellhub returns the user to your return_url with a one-time code — not to the gellhub dashboard — when embedded connect cookies are active. Email login returns connectRedirect from POST /api/login; Google sign-in and Stripe success use server redirects to the same partner URL. Paid gallery/drive plans may open Stripe first; success lands on GET /integrations/connect/stripe-return then your callback.

Paid plans: with connect cookies active, Stripe Checkout success is routed to GET /integrations/connect/stripe-return?session_id=… which verifies the Checkout Session and then redirects to your return_url with the same code pattern. You can still pass successUrl on POST /api/register if you build the URL yourself (must include {CHECKOUT_SESSION_ID}).

// 1) Redirect user to gellhub (client_id from Developer Console → Applications; return_url must match registered URIs)
window.location.href =
  'https://gellhub.com/api/integrations/connect/start?' +
  'client_id=' + encodeURIComponent('YOUR_CLIENT_ID') +
  '&return_url=' + encodeURIComponent('https://yourapp.com/api/gellhub/callback') +
  '&state=' + encodeURIComponent(csrfState) +
  '&plan=' + planId; // product inferred from plan; must match app’s allowed services in Console

// 2) User finishes on gellhub → browser lands on your return_url?code=...&state=...

// 3) Your server only: exchange (never from the browser)
const r = await fetch('https://gellhub.com/api/integrations/connect/exchange', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    code,
    client_id: process.env.GELLHUB_CLIENT_ID,       // server env
    client_secret: process.env.GELLHUB_CLIENT_SECRET,
  }),
});
const account = await r.json();
// store account.profileId + keys for this merchant in your database

Partner verification

After Embedded connect, your SaaS stores a mapping between your tenant id (store, studio, merchant) and the gellhub profileId returned from POST /api/integrations/connect/exchange. Use the endpoints below to confirm the merchant is still registered, still linked to your app, and still subscribed to the product line you sell.

{
  "profile_id": "from exchange",
  "client_id": "same as connect/start",
  "client_secret": "from server env only"
}

Typical SaaS flow: on connect callback → exchange → save profileId + product key → enable the add-on. On a schedule or before sensitive actions → billing/status with the stored key; optionally connect/verify to confirm the link is still valid without exposing keys.

// After connect: store profileId + messagingApiKey (or apiKey / driveApiKey) per merchant

// Later — is this merchant still linked to our app?
const link = await fetch('https://gellhub.com/api/integrations/connect/verify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    profile_id: merchant.gellhubProfileId,
    client_id: process.env.GELLHUB_CLIENT_ID,
    client_secret: process.env.GELLHUB_CLIENT_SECRET,
  }),
});
if (link.status === 404) { /* never connected or unlinked */ }

// Later — is their Messaging subscription still active?
const bill = await fetch('https://gellhub.com/api/billing/status', {
  headers: { 'x-api-key': merchant.messagingApiKey },
});
const j = await bill.json();
const eligible =
  j.plan &&
  (j.plan.price <= 0 ||
    ['active', 'trialing', 'past_due'].includes(String(j.stripeStatus || '').toLowerCase()));

Authentication

Use only the API key. The platform derives your account from the key — no need to pass studioId or driveId in requests. Use apiKey (Client Gallery) or driveApiKey (Drive). Your Studio ID and Drive ID are shown in the dashboard for reference.

x-api-key: sk_your_api_key_here

{
  "email": "studio@example.com",
  "password": "your-password",
  "displayName": "My Studio",
  "accountType": "studio",
  "planId": "optional_plan_id_from_GET_/api/public/plans",
  "successUrl": "https://yourapp.com/billing/done?sid={CHECKOUT_SESSION_ID}",
  "cancelUrl": "https://yourapp.com/billing/cancel"
}

// successUrl / cancelUrl: optional absolute URLs for Stripe return (omit to use platform dashboard defaults).
// planId must match accountType (clientGallery plan + studio, or drive plan + drive).

// Response includes keys + billing:
// - apiKey / driveApiKey: use in x-api-key for API calls
// - requiresPayment: true if plan has price > 0
// - checkoutUrl: open in browser to pay (same Stripe Checkout as the website)
// - checkoutError: if payment required but session failed — retry POST /api/billing/checkout-session with x-api-key

Manage collections, upload files, and share client galleries. Send apiKey in the x-api-key header — no Studio ID in the request.

{
  "name": "Wedding 2024",
  "clientName": "John Doe",
  "date": "2024-06-15",
  "categoryId": "cat_xxx"
}

{
  "name": "General"
}

FormData: collectionId, clientName, file

{
  "collectionId": "",
  "clientName": "",
  "fileName": "",
  "contentType": "",
  "sizeBytes": 0
}

{
  "collectionId": "",
  "clientName": "",
  "storageKey": "",
  "fileName": "",
  "contentType": "",
  "sizeBytes": 0
}

File storage with folders. Send driveApiKey in the x-api-key header — no Drive ID in the request. External apps and large or batched uploads should use /api/drive/upload/presign then PUT to Wasabi, then /api/drive/upload/complete (same header on all three steps). Direct /api/drive/upload streams the whole file through this server and often times out on big files; your bucket CORS must allow PUT from the browser or server origin that performs the upload.

Partner apps (Developer Console): after the user completes POST /api/integrations/connect/exchange, uploads may include header x-gellhub-integration-client-id: YOUR_CLIENT_ID (or JSON field integrationClientId on presign/complete). gellhub creates a top-level Drive folder named like your app and stores files there; the Drive web UI treats that tree as read-only while your backend keeps full API access when the same header is sent. Omit the header for normal user uploads to My Drive root or a folder they own.

{
  "name": "My Folder",
  "parentId": null
}

FormData: folderId (optional), file

{
  "fileName": "",
  "contentType": "",
  "sizeBytes": 0,
  "folderId": null,
  "integrationClientId": "optional; or header x-gellhub-integration-client-id"
}

{
  "storageKey": "",
  "fileName": "",
  "contentType": "",
  "sizeBytes": 0,
  "folderId": null,
  "integrationClientId": "optional; match presign"
}

{
  "name": "New name",
  "targetFolderId": "folder_id"
}

{
  "fileIds": [],
  "folderIds": []
}

{
  "fileIds": [],
  "folderIds": []
}

For registered GellHub accounts with an active Messaging plan. Sign in, open Dashboard → Messaging, generate a msg_… key, and send it as x-api-key on the endpoints below. Use this to connect WhatsApp bridges, mobile apps, or your own backend while keeping bot training in the dashboard.

GellHub AI engine. Replies run on the platform. You never choose inference models or third-party AI providers — only credits, agents, and conversations on your account.

SaaS partners can onboard Messaging via Embedded connect with product=messaging and a plan id from the public plans API.

Dashboard-only (cookie session)

End users manage keys in the dashboard. Integrators use the msg_… key on all /api/messaging/v1/* routes below.

Bot & chat (x-api-key)

{
  "channel": "api",
  "agentId": "optional-agent-cuid",
  "conversationRef": "whatsapp:+15551234567:thread-1",
  "messages": [
    {
      "role": "user",
      "content": "Hello"
    }
  ]
}

Agents API (x-api-key)

Create and manage bots for a connected account. Max 25 agents per profile. At least one agent must remain. Fields: name, botDisplayName, botRoleSummary, systemInstructions, handoff URLs, isDefault.

{
  "name": "Sales bot",
  "botDisplayName": "Store assistant",
  "botRoleSummary": "Help with products and prices",
  "systemInstructions": "Be friendly and concise.",
  "humanHandoffEnabled": false,
  "isDefault": true
}

{
  "botDisplayName": "Updated name",
  "systemInstructions": "New instructions…",
  "isDefault": true
}

Website widget API (x-api-key)

Enable the floating chat widget, set allowed domains, accent color, greeting, and launcher icon (emoji or HTTPS image). Response includes embedPublicId (emb_…), embedShareLink, and ready-to-paste embedCodeFloating / embedCodeButton.

• embedLauncherIcon — emoji (e.g. 💬) or public https://… image URL for the floating button
• embedAllowedOrigins — hostnames only (e.g. shop.example.com)
• rotateEmbedId — optional on PUT; invalidates old emb_… id

{
  "embedEnabled": true,
  "embedAllowedOrigins": [
    "tenant-store.com",
    "www.tenant-store.com"
  ],
  "embedAccentColor": "#0d9488",
  "embedLauncherIcon": "💬",
  "embedShowLauncher": true,
  "embedGreeting": "Hi! How can we help?",
  "rotateEmbedId": false
}

SaaS onboarding flow

1. Register a Developer app with allowedProductTypes: ["messaging"] in the Console.
2. Connect each merchant via Embedded connect (product=messaging).
3. Merchant generates msg_… in Dashboard → Messaging → API key (or your UI calls dashboard session endpoints).
4. Your backend calls POST /api/messaging/v1/agents then PUT /api/messaging/v1/embed with the merchant's key.
5. Paste embedCodeFloating on the tenant site or share embedShareLink in ads.
6. Route customer messages through POST /api/messaging/v1/chat (WhatsApp bridge, app, etc.).
7. Enable Dynamic skills so booking/product questions call your webhook (0 AI credits).

Dynamic skills webhook

For live data (booking slots, product catalog, forms). GellHub detects keywords, POSTs to your HTTPS endpoint, validates the JSON response, and renders UI in the chat widget — without asking the LLM to build the interface. Skill turns cost 0 credits.

{
  "skillsEnabled": true,
  "skillsWebhookUrl": "https://yourstore.com/api/gellhub/skills",
  "skillsWebhookSecret": "your-hmac-secret",
  "skills": [
    {
      "key": "booking",
      "label": "Booking",
      "keywords": [
        "book",
        "appointment",
        "schedule"
      ]
    },
    {
      "key": "catalog",
      "label": "Products",
      "keywords": [
        "product",
        "price",
        "catalog"
      ]
    }
  ]
}

{
  "skillsEnabled": true,
  "skillsWebhookUrl": "https://yourstore.com/api/gellhub/skills",
  "skills": [
    {
      "key": "booking",
      "label": "Booking",
      "keywords": [
        "book",
        "appointment"
      ]
    }
  ]
}

Your webhook receives (POST):

{
  "version": 1,
  "skill": "booking",
  "profileId": "…",
  "conversationRef": "web:emb_…:visitor-id",
  "visitorId": "visitor-id",
  "channel": "web",
  "message": "What times are available tomorrow?",
  "messages": [{ "role": "user", "content": "…" }]
}

Headers: X-GellHub-Timestamp, X-GellHub-Skill, optional X-GellHub-Signature (HMAC-SHA256 of timestamp + "." + body).

Respond with JSON (version 1):

{
  "version": 1,
  "message": "Available times tomorrow:",
  "ui": {
    "type": "slot_list",
    "items": [
      { "id": "10:00", "title": "10:00", "subtitle": "30 min" },
      { "id": "11:30", "title": "11:30", "subtitle": "Available" }
    ]
  }
}

Allowed ui.type values (rendered by GellHub, not the LLM):

• slot_list — booking/time buttons
• product_cards — title, price, imageUrl, actionUrl
• buttons — action message or url
• iframe — url (HTTPS), optional height for complex booking forms

Chat responses from POST /api/messaging/embed/v1/chat and POST /api/messaging/v1/chat may include an extra field ui alongside content.

Human handoff webhook (SaaS inbox)

When a visitor asks for a real person, GellHub POSTs to your platform — not GellHub notifications. Merchants embedded in your app never open GellHub; your store dashboard shows the alert and inbox.

{
  "handoffWebhookUrl": "https://your-saas.com/api/gellhub/handoff",
  "handoffWebhookSecret": "your-hmac-secret"
}

GellHub POSTs to your URL:

{
  "version": 1,
  "event": "handoff.requested",
  "profileId": "clx…",
  "conversationRef": "web:emb_…:visitor-uuid",
  "conversationId": "…",
  "visitorId": "visitor-uuid",
  "agentId": "…",
  "channel": "web",
  "message": "I need to speak with someone on your team",
  "requestedAt": "2026-05-25T12:00:00.000Z"
}

Headers: X-GellHub-Timestamp, X-GellHub-Event = handoff.requested, optional X-GellHub-Signature (HMAC-SHA256 of timestamp + "." + body).

Routing many stores: keep a table your_store_id ↔ profileId when the merchant completes Embedded connect. On webhook, lookup store and push to that tenant's team only.

Iframe embed: the widget also sends postMessage with type: "gellhub:handoff" to window.parent for instant UI badges (webhook remains the source of truth).

Respond with HTTP 200 and optional JSON { "ok": true }. Your app handles staff replies in your own inbox API.

Website chat widget (per profile)

Each subscriber profile on GellHub can enable a hosted chat widget scoped to that account only. The browser never sees the secret msg_… key — only a public emb_… embed id plus an Origin allowlist configured in Messaging → Website widget.

SaaS apps with a msg_… key can use PUT /api/messaging/v1/embed to set accent color and floating button icon, and POST /api/messaging/v1/agents to create bots per tenant.

Direct chat link (ads)

https://gellhub.com/chat/emb_…

Install on merchant site

<script
  src="https://gellhub.com/embed/gellhub-chat.js"
  data-embed-id="emb_…"
  data-chat-title="Store or bot name"
  data-launcher-icon="💬"
  data-launcher="true"
  async
></script>

<script
  src="https://gellhub.com/embed/gellhub-chat.js"
  data-embed-id="emb_…"
  data-chat-title="Store or bot name"
  data-launcher="false"
  async
></script>
<button type="button" onclick="window.GellHubChat && GellHubChat.open()">Chat</button>

{
  "embedId": "emb_…",
  "visitorId": "visitor-stable-id",
  "messages": [
    {
      "role": "user",
      "content": "What are your prices?"
    }
  ]
}

{
  "embedEnabled": true,
  "embedAllowedOrigins": [
    "yourstore.com"
  ],
  "embedShowLauncher": true,
  "embedAccentColor": "#0d9488",
  "embedLauncherIcon": "💬",
  "embedGreeting": "Hi! How can we help?",
  "rotateEmbedId": false
}

Billing & Stripe

Subscribe and pay with the same x-api-key you use for API calls (Client Gallery key or Drive key). The platform maps the key to your account and starts a Stripe Checkout session. You can also use a browser session after signing in at the dashboard.

See Plans & pricing API for GET /api/public/plans and GET /api/public/plans/by-id. Use planId on POST /api/register or POST /api/billing/checkout-session with x-api-key.

{
  "planId": "plan_xxx",
  "successUrl": "https://yourapp.com/done?session_id={CHECKOUT_SESSION_ID}",
  "cancelUrl": "https://yourapp.com/cancel"
}

{
  "returnUrl": "https://yourapp.com/account"
}

Configure STRIPE_SECRET_KEY and webhook endpoint POST /api/webhooks/stripe with STRIPE_WEBHOOK_SECRET so subscriptions sync to your plan limits after payment.

Examples

cURL - List Drive files

curl -H "x-api-key: YOUR_DRIVE_API_KEY" \
  "https://gellhub.com/api/drive"

cURL - Upload to Drive (small files only)

curl -X POST "https://gellhub.com/api/drive/upload" \
  -H "x-api-key: YOUR_DRIVE_API_KEY" \
  -F "folderId=FOLDER_ID" \
  -F "file=@/path/to/image.jpg"

For external integrations, large files, or batch uploads, use presigned uploads below instead of proxy upload.

JavaScript - Drive presigned upload (recommended)

const apiKey = 'YOUR_DRIVE_API_KEY';
const file = fileInput.files[0];
const folderId = 'optional_folder_id_or_null';

// 1) Ask gellhub for presigned PUT URL
const presignRes = await fetch('https://gellhub.com/api/drive/upload/presign', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': apiKey,
  },
  body: JSON.stringify({
    fileName: file.name,
    contentType: file.type || 'application/octet-stream',
    sizeBytes: file.size,
    folderId: folderId || null,
  }),
});
if (!presignRes.ok) throw new Error(await presignRes.text());
const { uploadUrl, storageKey, headers } = await presignRes.json();

// 2) Upload directly to object storage (Wasabi)
const putRes = await fetch(uploadUrl, {
  method: 'PUT',
  headers: { 'Content-Type': headers?.['Content-Type'] || file.type || 'application/octet-stream' },
  body: file,
});
if (!putRes.ok) throw new Error('PUT failed: ' + putRes.status);

// 3) Finalize on gellhub
// If storage is not immediately visible, retry /complete a few times.
for (let attempt = 1; attempt <= 5; attempt++) {
  const completeRes = await fetch('https://gellhub.com/api/drive/upload/complete', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey,
    },
    body: JSON.stringify({
      storageKey,
      fileName: file.name,
      contentType: file.type || 'application/octet-stream',
      sizeBytes: file.size,
      folderId: folderId || null,
    }),
  });

  if (completeRes.ok) {
    const fileRecord = await completeRes.json();
    console.log('Uploaded:', fileRecord);
    break;
  }

  const err = await completeRes.json().catch(() => ({}));
  const retryable = err?.error === 'upload_incomplete_or_mismatch' &&
    err?.detail === 'object_not_visible_yet_retry_complete';
  if (!retryable || attempt === 5) throw new Error(JSON.stringify(err));

  await new Promise((r) => setTimeout(r, attempt * 1000));
}

JavaScript - Create collection (Client Gallery)

const res = await fetch('https://gellhub.com/api/collections', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_CLIENT_GALLERY_API_KEY'
  },
  body: JSON.stringify({
    name: 'Wedding Album',
    clientName: 'Jane Smith',
    date: '2024-06-15',
    categoryId: 'cat_xxx'
  })
});
const collection = await res.json();

JavaScript - Upload to collection

const formData = new FormData();
formData.append('collectionId', collection.id);
formData.append('clientName', 'Jane Smith');
formData.append('file', fileInput.files[0]);

await fetch('https://gellhub.com/api/upload', {
  method: 'POST',
  headers: { 'x-api-key': 'YOUR_CLIENT_GALLERY_API_KEY' },
  body: formData
});