Partner REST API

One-call customer onboarding

POST /api/partner/customers/onboard is a main-app endpoint (not a gateway tool path) — it lives on knotie-ai.pro or on your own white-label domain, and you can call it directly with either credential type. The gateway exposes exactly the same contract as the customers_onboard tool.

When both are present the X-API-Key header wins — an explicit key header is an unambiguous statement of intent, so it is never silently ignored. A customer key (ckt_) is rejected even though it carries a partner id: it is a customer's credential and must not be able to mint that partner's customers. The endpoint is behind the Redis-backed partner rate limiter and returns 429 when you exceed it.

Apply order (fixed, and load-bearing)

1. Your catalog / dashboard-mode defaults for a new customer
2. planId features — the primary upsell lever
3. Per-call features overrides — secondary, per-customer
4. Your partner master switches — last, unconditional, fail-closed

Step 4 runs even when you send no overrides at all: a stored plan row may predate a master switch being turned off, so the clamp is what makes the grant safe — not the input validation. The five master-gated keys are showMediaStudio, showWebsiteStudio, showAiAgents, enableAiMemory and showAiGateway. Requesting one while its master switch is off is not an error — the key is written false and the reason lands in warnings[]. Read that array.

Request body

Which features keys are honoured

Anything outside these lists is ignored rather than written — the body must never be able to name an arbitrary column.

• Portal menu & capability toggles: enableAdvancedAnalytics, enableDetailedCallAnalysis, enableActionPointAnalysis, showIntegration, showKnowledgeBase, showDocsAndMedia, showSocialPlanner, showPhoneNumbers, showCampaigns, showScheduleMeeting, showPricingInformation, showMarketplaceSolutions, showMcp, showServerTerminal, enableVpsPurchase, vpsMarginPercent, showVpsCatalogApps, autoEmbeddingEnabled, enableApiAccess, showApiKeys, enableTeamMembers, maxTeamMembers, storageAllocatedMB, selfServeAgentLimit, customerInfraResellerMode, customerAgencyDashboardMode
• Master-gated grants (requests, not guarantees): showMediaStudio, showWebsiteStudio, showAiAgents, enableAiMemory, showAiGateway
• Credit metering & knowledge-base tier: aiCreditsEnabled, aiCreditPricePerMinute, aiCreditGracePeriodSeconds, lowCreditThreshold, lowCreditNotificationsEnabled, restrictCustomerCreditPlanVisibility, visibleCustomerCreditPlanIds, kbProcessingEnabled, kbTier

• selfServeAgentLimit is clamped to 0–20.
• enableApiAccess: false also forces showApiKeys: false.
• kbTier: "premium" needs the admin-granted premium ingestion entitlement; without it the customer is created on the default tier and you get a warning.
• visibleCustomerCreditPlanIds is re-validated against your own credit plans — ids you do not own are dropped and listed in warnings[] rather than failing the call.
• Unlike customers_update, enableAiMemory here can never flip your partner-wide switch. An API call must not change partner-level state.

Call it

curl -X POST https://knotie-ai.pro/api/partner/customers/onboard \
  -H 'X-API-Key: pkt_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "[email protected]",
    "firstName": "Alice",
    "lastName": "Smith",
    "companyName": "Acme Corp",
    "planId": "plan_abc123",
    "experienceType": "MEDIA_STUDIO",
    "features": {
      "showKnowledgeBase": true,
      "showMediaStudio": true,
      "selfServeAgentLimit": 3
    },
    "initialAiCredits": 250,
    "sendWelcomeEmail": true
  }'

curl -X POST https://mcp.knotie-ai.pro/api/partner-rest/tools/customers_onboard \
  -H 'Authorization: Bearer pkt_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "email": "[email protected]", "companyName": "Acme Corp",
        "planId": "plan_abc123", "initialAiCredits": 250 }'

Response

{
  "customerId": "cus_abc123",
  "userOnboardingId": "onb_abc123",
  "created": true,
  "existing": false,
  "appliedPlanId": "plan_abc123",
  "appliedFeatures": [
    "plan:plan_abc123",
    "experienceType:MEDIA_STUDIO",
    "showKnowledgeBase",
    "selfServeAgentLimit",
    "showMediaStudio",
    "initialAiCredits"
  ],
  "warnings": []
}

appliedFeatures lists what actually landed — it is the honest record, not an echo of your request. Through the gateway the same result is wrapped with a leading outcome (CREATED / EXISTING_UNCHANGED), an attention line and warningCount, so an AI agent cannot scroll past a clamped grant.

{
  "customerId": "cus_existing",
  "userOnboardingId": "onb_existing",
  "created": false,
  "existing": true,
  "appliedFeatures": [],
  "warnings": [
    "A customer with this email already exists for this partner — returned unchanged. Nothing was mutated (planId, features, and initialAiCredits were ignored)."
  ]
}

This is the contract, not a bug: re-applying a plan or overrides on a repeat call would let a retry silently rewrite a live customer's entitlements, which is exactly what idempotency exists to prevent. To change an existing customer use customers_update / customer_credits_top_up / customer_credits_set_monthly.

Failure policy

Money and toggles are hard failures. If the plan application, the override write or the credit grant fails, the customer is rolled back by a compensating delete and the call returns 500 — you never get a half-configured, billable account. The welcome email is the only leg allowed to degrade: an undelivered email becomes a warnings[] entry and the account still exists.

Discover what you can set

Rather than hard-coding the field list above into your integration, ask for it. GET /api/partner/customers/capabilities returns the complete writable surface for your account — and it is derived at request time from the same validation schema and catalogs the product itself runs on, so it never falls behind a release. Same auth as the onboarding endpoint (partner bearer token or pkt_ key); read-only; mutates nothing.

• features — every key you may send inside features, with its type (boolean, number, string, array, or tri-state for the null-means-inherit toggles), its declared bounds or enum values, and a human label and description where we have one.
• masterGate — on each master-gated key: which partner switch backs it and whether yours is currently on. This is how you find out a grant would be clamped before you send it, instead of reading it back out of warnings[].
• experiences — the exact experienceType values that will validate for your account. Anything else is dropped with a warning.
• apps — the ids and names accepted in features.allowedApps, with category and stability.
• plans — your planId values, so you never have to look one up by hand.

curl https://knotie-ai.pro/api/partner/customers/capabilities \
  -H 'X-API-Key: pkt_YOUR_KEY'

{
  "counts": { "features": 44, "experiences": 2, "apps": 39, "plans": 3 },
  "features": [
    {
      "key": "selfServeAgentLimit",
      "type": "number", "integer": true, "min": 0, "max": 20,
      "optional": true, "nullable": false,
      "label": null, "description": null, "category": null,
      "masterGate": null
    },
    {
      "key": "showMediaStudio",
      "type": "boolean", "optional": true, "nullable": false,
      "label": "Media Studio",
      "description": "Customer can generate images & video in the branded studio …",
      "category": "infrastructure",
      "masterGate": {
        "partnerField": "mediaStudioEnabled",
        "enabled": false,
        "label": "Media Studio",
        "note": "Your Media Studio master switch is OFF — requesting this will be
                 clamped to false and reported in warnings[]."
      }
    },
    { "key": "kbTier", "type": "string", "enum": ["essential","moderate","premium"] },
    { "key": "showVpsCatalogApps", "type": "tri-state", "nullable": true }
  ],
  "experiences": [
    { "experienceType": "AI_RECEPTIONIST", "name": "Front Desk", "isDefault": true, "enabled": true }
  ],
  "apps": [ { "id": "gmail", "name": "gmail", "displayName": "Gmail", "category": "free" } ],
  "plans": [ { "id": "plan_abc123", "name": "Starter", "isActive": true } ]
}

curl -X POST https://mcp.knotie-ai.pro/api/partner-rest/tools/customers_capabilities \
  -H 'Authorization: Bearer pkt_YOUR_KEY' \
  -H 'Content-Type: application/json' -d '{}'

Re-read it rather than caching it. New toggles, new experiences and new apps appear here automatically — that is the point of the endpoint, and a cached copy throws it away.

Sell an experience from your own landing page

Three calls turn any landing page into a storefront on your own Stripe account: capabilities (what can I sell?) → customers/onboard (register the buyer, optional) → payment-links (get a checkout URL). The buyer pays you — the Checkout session is created on your connected Stripe account — and our webhook is what turns that payment into a provisioned, entitled customer.

Before you start

• Connect Stripe. Minting is refused (422) until your connected account exists and has charges enabled.
• Approve your redirect domains. Settings → API Keys → “Payment redirect domains”, or PUT /api/partner/settings/redirect-domains. Success and cancel URLs must be https on an approved domain or a subdomain of one. Stripe accepts any URL; this list is our guard, and it is what stops a leaked key from redirecting your paying buyers somewhere else. An empty list means no links can be minted.
• Use a key with payments:write. A customers/CRM key cannot mint money links. Grant the scope on the key in Settings → API Keys.

curl -X PUT https://knotie-ai.pro/api/partner/settings/redirect-domains \
  -H 'X-API-Key: pkt_YOUR_KEY' -H 'Content-Type: application/json' \
  -d '{ "domains": ["their-agency.com"] }'

curl -X POST https://knotie-ai.pro/api/partner/payment-links \
  -H 'X-API-Key: pkt_YOUR_KEY' -H 'Content-Type: application/json' \
  -d '{
    "email": "[email protected]",
    "amount": 49900,
    "currency": "usd",
    "interval": "one_time",
    "experienceType": "MEDIA_STUDIO",
    "features": { "showMediaStudio": true, "showKnowledgeBase": true },
    "successUrl": "https://their-agency.com/thanks?session={CHECKOUT_SESSION_ID}",
    "cancelUrl": "https://their-agency.com/pricing",
    "description": "Creator Pack - launch offer"
  }'

{
  "intentId": "b0c1…",
  "url": "https://checkout.stripe.com/c/pay/cs_test_…",
  "stripeSessionId": "cs_test_…",
  "status": "created",
  "amount": 49900,
  "currency": "usd",
  "interval": "one_time",
  "expiresAt": "2026-08-16T12:00:00.000Z",
  "statusUrl": "/api/partner/payment-links/b0c1…"
}

Fields

Confirm on your thank-you page

curl 'https://knotie-ai.pro/api/partner/payment-links?stripeSessionId=cs_test_…' \
  -H 'X-API-Key: pkt_YOUR_KEY'

# 200 OK
# { "intentId": "b0c1…", "status": "completed", "paid": true,
#   "customerId": "…", "userOnboardingId": "…", "warnings": [] }

paid flips only when the signature-verified webhook has applied the grant. Until then the status is created. If the buyer paid but a feature you asked for is missing, look at warnings[] — a master switch that is off on your account clamps the grant rather than selling something your account cannot hand out.

Rate limits: the standard partner limiter, plus a per-partner cap of 200 minted links per rolling 24 hours (429 when reached; existing links keep working).