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. Inference runs on the platform — you do not supply OpenAI or other provider API keys. Each agent stores a modelKey from your messaging plan's model catalog (e.g. openai:gpt-4o-mini). Chat turns use that agent's model; credit cost varies by model.

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

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

{
  "name": "Sales bot",
  "botDisplayName": "Store assistant",
  "botRoleSummary": "Help with products and prices",
  "systemInstructions": "Be friendly and concise.",
  "modelKey": "openai:gpt-4o-mini",
  "humanHandoffEnabled": false,
  "isDefault": true
}

{
  "botDisplayName": "Updated name",
  "systemInstructions": "New instructions…",
  "modelKey": "openai:gpt-4o",
  "isDefault": true
}

{
  "agentId": "agent-cuid",
  "kind": "faq",
  "faqs": [
    {
      "question": "Do you ship internationally?",
      "answer": "Yes, to EU and UK within 5–7 days."
    },
    {
      "question": "What is your return window?",
      "answer": "30 days unused, with receipt."
    }
  ]
}

{
  "agentId": "agent-cuid",
  "kind": "pricing",
  "plans": [
    {
      "name": "Starter",
      "price": "$29",
      "period": "per month",
      "features": [
        "1 agent",
        "5k messages"
      ]
    },
    {
      "name": "Pro",
      "price": "$99",
      "period": "per month",
      "features": [
        "Unlimited agents"
      ]
    }
  ]
}

{
  "agentId": "agent-cuid",
  "kind": "policy",
  "sections": [
    {
      "heading": "Shipping",
      "content": "Orders ship within 2 business days."
    },
    {
      "heading": "Returns",
      "content": "Contact support within 30 days."
    }
  ]
}

{
  "agentId": "agent-cuid",
  "kind": "text",
  "title": "About us",
  "bodyText": "We are a boutique studio founded in 2018…"
}

{
  "faqs": [
    {
      "question": "Holiday hours?",
      "answer": "Closed Dec 24–26."
    }
  ]
}

{
  "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"
      ]
    }
  ]
}

{
  "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": "…" }]
}

{
  "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" }
    ]
  }
}

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

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

<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": "v_uuid-or-cust_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?",
  "embedAuthMode": "none",
  "embedAuthClientId": "",
  "rotateEmbedId": false
}

window.addEventListener("message", (event) => {
  const data = event.data;
  if (data?.type === "gellhub:customer-auth") {
    // { embedId, token, customer: { id, email, displayName } }
    // visitorId is cust_* on merchant sites; ad links keep ephemeral v_* on the page
  }
});

{
  "embedId": "emb_…",
  "email": "customer@example.com",
  "password": "min-6-chars",
  "displayName": "Jane",
  "clientId": "optional-for-partner-connect",
  "returnUrl": "https://yourapp.com/oauth/customer/callback",
  "state": "csrf-state"
}

{
  "embedId": "emb_…",
  "email": "customer@example.com",
  "password": "password"
}

{
  "embedId": "emb_…",
  "visitorId": "v_uuid-or-cust_id",
  "messages": [
    {
      "role": "user",
      "content": "Hello"
    }
  ]
}

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

// 1) Before opening chat, send shopper to GellHub sign-in
window.location.href =
  'https://gellhub.com/api/integrations/customers/connect/start?' +
  'embed_id=' + encodeURIComponent('emb_MERCHANT_WIDGET') +
  '&client_id=' + encodeURIComponent(process.env.GELLHUB_CLIENT_ID) +
  '&return_url=' + encodeURIComponent('https://yourstore.com/api/gellhub/customer/callback') +
  '&state=' + encodeURIComponent(csrfState);

// 2) After Google/email sign-in → browser lands on return_url?code=ecc_…&state=…

// 3) Your server only: exchange (never from the browser)
const r = await fetch('https://gellhub.com/api/integrations/customers/connect/exchange', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    code,
    client_id: process.env.GELLHUB_CLIENT_ID,
    client_secret: process.env.GELLHUB_CLIENT_SECRET,
  }),
});
const { customer, merchantProfileId, embedPublicId } = await r.json();
// Map customer.id to your storefront user; open widget with their session token if you host custom UI

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

{
  "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"
}

{
  "content": "Thanks for waiting — a colleague will help you now."
}

{
  "reenableAi": true
}

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
});