Documentation Hub
Back to API Reference
Partner / Developer API

Developer Hub

Integrate Flowk AI into Your SaaS Platform

Use these endpoints to programmatically provision and manage your sub-entities and AI agents.

Authenticated

All requests must include your Partner API Key in the Authorization header.

Real-time

Provisioning is instantaneous. Your users can start chatting immediately.

Isolated

Data is strictly sandboxed. Sub-entities cannot access each other's messages or configurations.

Provisioning API

POSThttps://api-flowk.kemonai.com/api/v1/partners/provision

Request Body (JSON)

externalIdRequired

string

Unique ID of the entity in your platform.

nameRequired

string

Human readable name of the business.

descriptionOptional

string

Brief summary of the business purpose.

maxAiSessionsOptional

number

Hard limit for monthly AI usage.

providerConfigOptional

object

Optional entity-specific configurations.

Implementation Example

curl -X POST https://api-flowk.kemonai.com/api/v1/partners/provision \
  -H "Authorization: Bearer YOUR_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "business_123",
    "name": "Global Solutions",
    "description": "Managed entity for Global Solutions",
    "maxAiSessions": 1000
  }'

Success Response

{
  "success": true,
  "businessId": "cl-xyz-123",
  "agentId": "agent-456",
  "message": "Business and Agent provisioned successfully"
}

Update Merchant API

PATCHhttps://api-flowk.kemonai.com/v1/partners/merchants/:externalId

Description

Use this endpoint to modify an existing sub-merchant. It is primarily used when a sub-tenant upgrades their subscription on your platform and you need to increase their quotaAiMessages limit so their AI agents continue serving customers.

Request Body (JSON)

maxAiSessionsOptional

number

New hard limit for monthly AI usage.

nameOptional

string

Update the business name.

isActiveOptional

boolean

Suspend or activate the merchant.

Implementation Example

curl -X PATCH https://api-flowk.kemonai.com/v1/partners/merchants/shop_12345 \
  -H "Authorization: Bearer fk_live_12345" \
  -H "Content-Type: application/json" \
  -d '{
    "maxAiSessions": 10000
  }'

Success Response

{
  "status": "success",
  "businessId": "biz_abc123",
  "maxAiSessions": 10000,
  "isActive": true,
  "message": "Merchant successfully updated"
}

SSO Magic Links API

POSThttps://api-flowk.kemonai.com/api/v1/partners/magic-link

Description

Generate a secure, one-time use URL to seamlessly log your sub-merchants into their white-labeled dashboard without requiring passwords. The returned magicUrl is cryptographically signed and expires in 5 minutes. Redirect the user's browser to this URL to initiate the SSO session.

Request Body (JSON)

businessIdRequired

string

The ID of the provisioned business.

adminNameOptional

string

Name of the sub-merchant logging in.

Implementation Example

curl -X POST https://api-flowk.kemonai.com/api/v1/partners/magic-link \
  -H "Authorization: Bearer YOUR_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "businessId": "cl-xyz-123",
    "adminName": "John Doe"
  }'

Success Response

{
  "success": true,
  "businessId": "cl-xyz-123",
  "magicUrl": "https://app.flowk.ai/api/auth/magic?token=ey...",
  "expiresIn": "5m"
}

Web Widget Integration

To deploy the chat widget, embed the script and provide your configuration via the window.Flowk object. For logged-in users, you can pass their details and Quick Actions to bypass onboarding and provide a personalized experience.

<script>
  window.Flowk = {
    agentId: "YOUR_AGENT_ID",
    
    /* Logged-in User (Optional) */
    fullname: "John Doe",
    email: "[email protected]",
    avatarUrl: "https://example.com/avatar.png",
    
    /* Quick Actions (Optional buttons shown to identified users) */
    quickActions: [
      { label: "Check order status", message: "I'd like to check my order status" },
      { label: "Book a demo", message: "I want to book a product demo" }
    ],

    metadata: {
       plan: "Premium",
       userId: "user_123"
    }
  };
</script>
<script src="https://app.flowk.ai/widget.js" async defer></script>

Implementation Tip:

If fullname and email are provided, the widget will skip the lead capture form and show a "Welcome back" greeting instead. Using quickActions allows users to start common tasks with a single click.

Security Best Practices

Never expose your Partner API Key in client-side code (browsers or mobile apps). Provisioning calls should only be made from your server-to-server environment. If you suspect your key has been compromised, please contact the Flowk Superadmin immediately to rotate it.