Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.knotie-ai.pro/llms.txt

Use this file to discover all available pages before exploring further.

​
Base URL

All MCP endpoints use your Knotie AI base URL: 
https://YOUR_BASE_URL/api/v1/mcp
All requests require the X-API-Key header. See Authentication for details.

​
Customer management

​
Create customer (onboard)

POST /api/v1/mcp/customers/onboard
Onboard a new customer with optional portal access. Request body: 
{
  "basic": {
    "email": "client@example.com",
    "firstName": "Jane",
    "lastName": "Doe",
    "businessPhone": "+15551234567"
  },
  "business": {
    "companyName": "Acme Corp",
    "monthlyCallVolume": "500-1000",
    "peakHours": "9am-5pm EST"
  },
  "requirements": {
    "primaryUseCase": "lead-follow-up",
    "callComplexity": "medium",
    "scriptComplexity": "standard",
    "languages": ["en"],
    "customAutomation": ""
  },
  "integration": {
    "crmSystem": "GoHighLevel",
    "phoneSystem": "Twilio"
  },
  "deployment": {
    "deploymentTimeline": "this-week",
    "wantsDemo": false
  },
  "isQuickOnboarding": true,
  "allowPortalAccess": true,
  "planId": "plan_abc123"
}
FieldRequiredNotes
basic.emailYesMust be unique within your partner scope
basic.firstNameNo
basic.lastNameNo
basic.businessPhoneNo
business.*NoAll business fields are optional
isQuickOnboardingNoSkip extended intake fields
allowPortalAccessNoIf true, sends portal invite email with credentials
planIdNoApplies subscription plan features automatically
Response 200 OK: 
{
  "success": true,
  "message": "Customer onboarded successfully",
  "data": {
    "id": "cust_abc123",
    "email": "client@example.com",
    "firstName": "Jane",
    "lastName": "Doe",
    "companyName": "Acme Corp",
    "monthlyCallVolume": "500-1000",
    "estimatedPrice": 0,
    "priceBreakdown": "{}",
    "orderStatus": "new",
    "isOnboardingCompleted": false,
    "createdAt": "2026-04-10T12:00:00.000Z",
    "updatedAt": "2026-04-10T12:00:00.000Z"
  }
}
Side effects:
  • Creates the customer record
  • Sends portal invite email (if allowPortalAccess is true)
  • Applies plan features (if planId is provided)
Errors:
CodeReason
400Missing or invalid email, or email already exists
401Invalid or missing API key
403Partner account not found or inactive

​
Create customer (simple)

POST /api/v1/mcp/customers
Create a customer record with minimal fields.

​
List customers

GET /api/v1/mcp/customers
Returns a paginated list of all customers under your partner account. Query parameters:
ParameterDefaultDescription
page1Page number
limit20Results per page (max 100)
search—Searches name, email, phone, and company
monthlyCallVolume—Filter by call volume tier
callComplexity—Filter by complexity level
deploymentTimeline—Filter by deployment timeline
Response 200 OK: 
{
  "success": true,
  "data": [
    {
      "id": "cust_abc123",
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "client@example.com",
      "companyName": "Acme Corp",
      "monthlyCallVolume": "500-1000",
      "callComplexity": "medium",
      "customerId": "cid_xyz789",
      "subscriptions": 1,
      "unbilledAmount": 0,
      "deploymentStatus": "completed",
      "hasRetellAgent": true,
      "hasKnovaAgent": false,
      "isOnTrial": false,
      "subscriptionStatus": "active",
      "credentialStatus": "active",
      "createdAt": "2026-04-10T12:00:00.000Z",
      "updatedAt": "2026-04-10T12:00:00.000Z"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 3,
    "totalCount": 47,
    "limit": 20,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

​
Get customer

GET /api/v1/mcp/customers/{customerId}
Returns full details for a single customer, including feature flags, menu visibility, credit settings, and deployment status. Response 200 OK: 
{
  "success": true,
  "data": {
    "id": "cust_abc123",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "client@example.com",
    "companyName": "Acme Corp",
    "monthlyCallVolume": "500-1000",
    "estimatedPrice": 99,
    "customerId": "cid_xyz789",
    "orderStatus": "active",
    "dealStatus": "won",
    "billingType": "subscription",
    "agreedPrice": 99,
    "enableAdvancedAnalytics": true,
    "enableApiAccess": false,
    "customerPortalEnabled": true,
    "showKnowledgeBase": true,
    "showIntegration": true,
    "allowedApps": ["retell", "vapi"],
    "maxTeamMembers": 5,
    "enableTeamMembers": true,
    "aiCreditsEnabled": true,
    "aiCreditPricePerMinute": 0.12,
    "lowCreditThreshold": 100,
    "lowCreditNotificationsEnabled": true,
    "deploymentStatus": "completed",
    "deploymentNotes": null,
    "deploymentCompletedAt": "2026-04-10T14:00:00.000Z"
  }
}
Errors:
CodeReason
404Customer not found

​
Update customer

PATCH /api/v1/mcp/customers/{customerId}
Update any customer field. All fields are optional — only send the fields you want to change. Request body (all fields optional): 
{
  "firstName": "Jane",
  "companyName": "Acme Corp Updated",
  "enableApiAccess": true,
  "aiCreditsEnabled": true,
  "aiCreditPricePerMinute": 0.15,
  "deploymentStatus": "agent_ready",
  "showKnowledgeBase": false
}
Common updatable fields include basic info, feature flags (enableAdvancedAnalytics, enableApiAccess, customerPortalEnabled), menu visibility (showKnowledgeBase, showIntegration, allowedApps, etc.), team settings (maxTeamMembers, enableTeamMembers), AI credit settings, and deployment tracking fields. Validation:
  • Email format is validated and must be unique within your partner scope
  • Credit plan IDs are validated if provided
Response 200 OK: Same shape as the GET response.

​
Portal access

​
Enable portal access

POST /api/v1/mcp/customers/{customerId}/portal-access
Enables customer portal access and sends an invite email with temporary credentials. Request body: None required. Response 200 OK: 
{
  "success": true,
  "message": "Portal access enabled and credentials sent to client@example.com"
}
Side effects:
  • Creates or updates customer credentials
  • Generates a temporary password
  • Sends a branded portal invite email

​
Block / unblock portal access

POST /api/v1/mcp/customers/{customerId}/portal-access/block
Toggles the customer’s portal access. If currently active, blocks it. If currently suspended, re-enables it. Request body: None required. Response 200 OK: 
{
  "success": true,
  "message": "Customer portal access has been blocked",
  "newStatus": "suspended",
  "action": "blocked"
}
action valueMeaning
"blocked"Access was active and is now suspended
"granted"Access was suspended and is now active

​
Reset customer password

POST /api/v1/mcp/customers/{customerId}/reset-password
Sends a password reset email to the customer. Response 200 OK: 
{
  "success": true,
  "message": "Password reset email sent successfully"
}

​
Agent mapping

​
Map customer to Retell agent

POST /api/v1/mcp/retell-agents/{agentId}/map-customer
Assign a customer to a Retell agent. Request body: 
{
  "customerId": "cust_abc123",
  "profitMultiplier": 1.5
}
FieldRequiredNotes
customerIdYesThe customer’s ID
profitMultiplierYesMultiplier applied to call costs for billing
Response 200 OK: 
{
  "success": true,
  "agent": {
    "id": "agent_retell_456",
    "name": "Sales Follow-up Agent",
    "customer": {
      "id": "cust_abc123",
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "client@example.com"
    },
    "profitMultiplier": 1.5
  },
  "message": "Successfully mapped customer to agent"
}
Errors:
CodeReason
400Missing customerId or profitMultiplier
404Agent or customer not found

​
Unmap customer from Retell agent

POST /api/v1/mcp/retell-agents/{agentId}/unmap-customer
Remove the customer mapping from a Retell agent.

​
Map customer to VAPI agent

POST /api/v1/mcp/vapi-agents/{agentId}/map-customer
Same request/response shape as the Retell mapping endpoint.

​
Unmap customer from VAPI agent

POST /api/v1/mcp/vapi-agents/{agentId}/unmap-customer
Remove the customer mapping from a VAPI agent.

​
Team members

​
Add team member

POST /api/v1/mcp/customers/{customerId}/team-members
Invite a team member to a customer’s account. Request body: 
{
  "email": "team@example.com",
  "name": "John Smith",
  "role": "member"
}
FieldRequiredNotes
emailYesMust be unique per customer
nameYesDisplay name
roleNoDefaults to "member"
Response 200 OK: 
{
  "success": true,
  "message": "Team member invited successfully",
  "data": {
    "id": "tm_abc123",
    "customerId": "cust_abc123",
    "name": "John Smith",
    "email": "team@example.com",
    "role": "member",
    "status": "pending",
    "createdAt": "2026-04-10T12:00:00.000Z"
  }
}
Validation:
  • Team member count is checked against the customer’s maxTeamMembers limit

​
List team members

GET /api/v1/mcp/customers/{customerId}/team-members
Response 200 OK: 
{
  "success": true,
  "data": [
    {
      "id": "tm_abc123",
      "customerId": "cust_abc123",
      "name": "John Smith",
      "email": "team@example.com",
      "role": "member",
      "status": "active",
      "createdAt": "2026-04-10T12:00:00.000Z",
      "updatedAt": "2026-04-10T12:00:00.000Z"
    }
  ]
}

​
Delete team member

DELETE /api/v1/mcp/customers/{customerId}/team-members/{teamMemberId}
Response 200 OK: 
{
  "success": true,
  "message": "Team member deleted successfully"
}

​
Common error responses

All endpoints return standard error responses: 
{
  "success": false,
  "error": "Description of what went wrong"
}
HTTP codeMeaning
400Bad request — missing or invalid fields
401Unauthorized — invalid or missing API key
403Forbidden — partner account inactive or insufficient permissions
404Not found — customer, agent, or team member does not exist
500Internal server error