Build a connector. Give your agent real data.

A SupportCore connector is a small HTTPS service you host. It lets your support agent look up live data and run the actions you allow — order status, returns, warranty, account changes — all declared by a manifest so SupportCore discovers your capabilities automatically. One contract, any stack, no custom work on our side.

01Quick start

02Authentication

SupportCore sends a bearer key you issue in the Connections tab. Verify it on every request; reject anything else.

POST https://api.yourapp.com/supportcore/v1/lookup/customer
Authorization: Bearer sc_live_9f2c…a71b
Content-Type: application/json
Idempotency-Key: e0b6…c455   # on actions; safe to retry

HTTPS only. Compare the key in constant time; return 401 on mismatch. Rotate it from the Connections tab any time — no redeploy. Optionally verify an X-SupportCore-Signature HMAC of the body.

03The manifest — where you define capabilities

The heart of the spec. SupportCore fetches your manifest and turns every entry into a tool the agent can use. To teach the agent a new action — say, a note on an order — add one object here and implement its endpoint. That's it.

{
  "connector": "YourApp", "version": "1.0",
  "lookups": [
    { "id": "customer", "title": "Customer profile",
      "description": "Plan, status and recent activity for an email",
      "params": [ { "name": "email", "type": "string", "required": true } ],
      "returns": "plan, status, signup_date, last_active" }
  ],
  "actions": [
    { "id": "add_order_note", "title": "Add a note to an order",
      "params": [ { "name": "order_id", "type": "string", "required": true, "pattern": "^[0-9]+$" },
                 { "name": "note", "type": "string", "required": true } ],
      "approval": "optional", "reversible": true },
    { "id": "cancel_subscription", "title": "Cancel a subscription",
      "params": [ { "name": "email", "type": "string", "required": true } ],
      "approval": "required", "reversible": false }
  ]
}

04Lookups · read

Return support-relevant, non-sensitive data. On no match, return 200 with { "found": false } — not a 404.

{ "email": "kees@example.com" }

{ "found": true,
  "data": { "plan": "Pro", "status": "active",
            "open_invoices": 0 } }

05Actions · write

The logic and permission checks live in your backend — SupportCore only requests it. Return a short human message; the agent may quote it. Honour Idempotency-Key so the same key never acts twice.

{ "email": "kees@example.com",
  "_meta": { "approved_by": "stephen@urenapp.eu",
            "ticket": "89155065-…" } }

{ "ok": true,
  "message": "Cancelled, effective 1 Aug.",
  "reference": "CANCEL-7731" }

06Reference data & follow-up questions

The agent is only as good as what it can see. Two kinds of lookups make it genuinely helpful:

Record lookups — “this specific customer / order”

Keyed by an identifier (email, order id). We strongly recommend backing these with a read-only database account — grant SELECT on just the tables or views support needs (customers, orders, bookings, invoices) so the agent can see history and status without any write access or exposure of sensitive fields.

Catalogue lookups — “what do we even offer?”

Expose your options too, not just records. A hotel publishes a room_types lookup (types, capacity, price); a shop publishes shipping_options. This is what lets the agent reason and ask the right follow-up instead of guessing.

Structured catalogue — categories & articles, filterable

Take it one step further. Mark a catalogue lookup "catalog": true and point SupportCore at the list of items with an items descriptor. SupportCore imports it into a structured, category-driven Catalog — every entry becomes an article, grouped into categories — and refreshes it on every sync, so a tariff or stock change in your backoffice flows straight through. This is what lets the agent answer “which pitch fits a 5 m caravan with electricity under €40?” by filtering real data instead of guessing from prose.

Name the field that holds each entry's category with items.category and SupportCore groups the articles under it. A category is a first-class thing: the company adds shared remarks and specifications to it once (e.g. “10 A electricity, dogs allowed”), and every article inside inherits them — so the same fact is never repeated per row, and the agent reads it as one truth per category. Omit category for a flat catalogue. The exact same shape works for a booking system, a webshop, a bakery or a butcher — one universal contract, no domain assumptions.

// manifest entry — a catalogue lookup that becomes a category-driven Catalog
{ "id": "products", "title": "Product catalogue",
  "catalog": true, "personal": false,
  "items": { "list": "products", "key": "sku",
             "title": "name", "category": "category" },
  "params": [] }

// the lookup's response — each entry is one article; `category` groups them
{ "products": [
    { "sku": "CB-COL-250", "name": "Colombia Supremo 250g", "category": "Koffiebonen",
      "price": 8.5, "in_stock": true, "weight_g": 250 },
    { "sku": "TH-EARL-50", "name": "Earl Grey losse thee 50g", "category": "Thee",
      "price": 5.25, "in_stock": true, "weight_g": 50 } ] }

Common fields map onto universal columns automatically — price/price_per_night/tarief → price, description → description, image → photo, stock/in_stock/availability → availability. Everything else (like weight_g) becomes its own typed column — text, number or yes/no, inferred from the values. Return the full list; SupportCore keeps it in step on each sync. A separate per-item lookup that answers the live price or availability keeps those columns live rather than a stored snapshot.

Rule of thumb: if a human agent would need to look something up or ask a clarifying question to answer, publish a lookup for it. The agent will use it the same way.

07Errors & limits

08Security

• ✓Least privilege. Read-only for lookups; writes only through the specific operations your actions implement. Never an admin account.
• ✓Expose only what support needs. No password hashes, full card numbers or unrelated personal data — even behind a valid key.
• ✓Validate server-side. The manifest pattern is a first gate; re-check ownership and entitlements in your handler.
• ✓Rotate & log. Rotate the key; log every call with its ticket and approved_by.

09Full minimal example

const app = require("express")(); app.use(require("express").json());
const KEY = process.env.SUPPORTCORE_KEY;

app.use((req, res, next) => {                       // 1 · auth
  const t = (req.headers.authorization || "").replace("Bearer ", "");
  if (t !== KEY) return res.status(401).json({ error: { code: "unauthorized" } });
  next();
});

app.get("/supportcore/v1/manifest", (_, res) => res.json({   // 2 · manifest
  connector: "YourApp", version: "1.0",
  lookups: [{ id: "customer", title: "Customer profile",
              params: [{ name: "email", type: "string", required: true }] }],
  actions: [{ id: "add_order_note", title: "Add order note", approval: "optional",
              params: [{ name: "order_id", type: "string", required: true, pattern: "^[0-9]+$" },
                       { name: "note", type: "string", required: true }] }]
}));

app.post("/supportcore/v1/lookup/customer", async (req, res) => {  // 3 · lookup
  const u = await db.user(req.body.email);
  res.json(u ? { found: true, data: { plan: u.plan, status: u.status } } : { found: false });
});

app.post("/supportcore/v1/action/add_order_note", async (req, res) => {  // 4 · action
  await db.addNote(req.body.order_id, req.body.note);
  res.json({ ok: true, message: "Note added to order " + req.body.order_id });
});

app.listen(8080);

10Readiness checklist

• ✓HTTPS at a stable /supportcore/v1 base URL.
• ✓GET /manifest lists every lookup and action; each id has a handler.
• ✓Bearer auth enforced; 401 on mismatch; key rotatable.
• ✓Lookups return { found, data }; actions { ok, message }; under 5s.
• ✓Idempotency on actions; destructive ones approval:"required".
• ✓Read-only, least-privilege data; no sensitive fields exposed.

11The other direction — drive tickets from your systems

The Connector API above is how SupportCore calls into your systems. The Support API is the reverse: how your systems talk to SupportCore. Open a ticket from a chat widget, an app or a helpdesk; read the AI's suggested reply; post an answer; close the conversation. Every ticket runs through the same pipeline, trust model and learning loop as email — so a chat widget is just channel:"chat". Building support into your own app or portal? Use channel:"api": that channel never sends email — storing the reply and firing reply.sent is the delivery, and your app shows it. Per category you choose in Console → Settings → AI agent (column App/API) whether the agent answers instantly, chat-style, or every reply waits for human approval first.

POST https://app.supportcore.ai/api/v1/tickets
Authorization: Bearer sc_live_…          # create one in Console → Developers
Content-Type: application/json

Keys are per-company, hashed at rest and revocable. Each key resolves to exactly one company; all data stays isolated by the same row-level security as the rest of SupportCore.

12Ticket endpoints

{ "customer_email": "kees@acme.com",
  "channel": "api",
  "message": "How do I reset my password?",
  "external_id": "app-ticket-8841",
  "verified": true }

{ "id": "a1f2…", "status": "open",
  "draft": {
    "status": "pending", "confidence": 0.94,
    "needs_human": false,
    "suggested_reply": "Go to Settings → …" } }

external_id is optional and makes creation idempotent — a retried call returns the same ticket instead of opening a duplicate. When draft.needs_human is true the AI handed off; write the reply yourself and POST it to /reply.

verified: true tells SupportCore that your system already authenticated this customer (a logged-in app user, a portal session). The conversation then starts fully verified: the agent skips identity questions and connector lookups on the customer's own record are allowed immediately. Only set it when the email address is genuinely proven — the claim is made under your API key and lands in the audit log.

Delivery on channel:"api": when the category's App/API column is on auto, the reply is delivered in the API response and reply.sent fires immediately (same guards as chat: permission matrix for actions, no unbacked "it's been sent" claims, paywall). On control, the draft waits in the inbox; human approval then delivers it along the same webhook — never by email.

13Webhooks — get notified the moment anything happens

Register an endpoint in Console → Developers and SupportCore POSTs a signed JSON event to it. Pick the events you care about, or all of them. Deliveries retry with backoff and are logged in plain language so anyone can see what happened — no engineer required.

{ "event": "ticket.created",
  "tenant": "acme",
  "at": 1753142400,
  "data": { "ticket_id": "a1f2…",
            "customer_email": "guest@acme.com",
            "channel": "chat" } }

X-SupportCore-Event: ticket.created
X-SupportCore-Timestamp: 1753142400
X-SupportCore-Signature: sha256=9f2c…

Answer with any 2xx to acknowledge. Anything else (or a timeout) is retried up to three times with backoff, then marked failed in the delivery log.

14Verify the signature

Every delivery is signed so you can trust it came from SupportCore and was not tampered with or replayed. Recompute the HMAC over {timestamp}.{raw_body} with your endpoint secret and compare.

const crypto = require("crypto");

function verify(req, secret) {
  const ts  = req.headers["x-supportcore-timestamp"];
  const sig = req.headers["x-supportcore-signature"];
  const mine = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(ts + "." + req.rawBody)          // the exact bytes we sent
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(mine));
}