Endpoints

Base URL

All MCP endpoints use your Knotie AI base URL:

https://YOUR_BASE_URL/api/v1/mcp

All requests require the Authorization: Bearer pkt_... header. The legacy X-API-Key header is deprecated. 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"
}

Field	Required	Notes
`basic.email`	Yes	Must be unique within your partner scope
`basic.firstName`	No
`basic.lastName`	No
`basic.businessPhone`	No
`business.*`	No	All business fields are optional
`isQuickOnboarding`	No	Skip extended intake fields
`allowPortalAccess`	No	If `true`, sends portal invite email with credentials
`planId`	No	Applies 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:

Code	Reason
`400`	Missing or invalid email, or email already exists
`401`	Invalid or missing API key
`403`	Partner 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:

Parameter	Default	Description
`page`	`1`	Page number
`limit`	`20`	Results 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:

Code	Reason
`404`	Customer 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` value	Meaning
`"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
}

Field	Required	Notes
`customerId`	Yes	The customer’s ID
`profitMultiplier`	Yes	Multiplier 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:

Code	Reason
`400`	Missing `customerId` or `profitMultiplier`
`404`	Agent 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"
}

Field	Required	Notes
`email`	Yes	Must be unique per customer
`name`	Yes	Display name
`role`	No	Defaults 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 code	Meaning
`400`	Bad request — missing or invalid fields
`401`	Unauthorized — invalid or missing API key
`403`	Forbidden — partner account inactive or insufficient permissions
`404`	Not found — customer, agent, or team member does not exist
`500`	Internal server error

Overview

MCP APIs

More API specs

Base URL

Customer management

Create customer (onboard)

Create customer (simple)

List customers

Get customer

Update customer

Portal access

Enable portal access

Block / unblock portal access

Reset customer password

Agent mapping

Map customer to Retell agent

Unmap customer from Retell agent

Map customer to VAPI agent

Unmap customer from VAPI agent

Team members

Add team member

List team members

Delete team member

Common error responses

​Base URL

​Customer management

​Create customer (onboard)

​Create customer (simple)

​List customers

​Get customer

​Update customer

​Portal access

​Enable portal access

​Block / unblock portal access

​Reset customer password

​Agent mapping

​Map customer to Retell agent

​Unmap customer from Retell agent

​Map customer to VAPI agent

​Unmap customer from VAPI agent

​Team members

​Add team member

​List team members

​Delete team member

​Common error responses

Base URL

Customer management

Create customer (onboard)

Create customer (simple)

List customers

Get customer

Update customer

Portal access

Enable portal access

Block / unblock portal access

Reset customer password

Agent mapping

Map customer to Retell agent

Unmap customer from Retell agent

Map customer to VAPI agent

Unmap customer from VAPI agent

Team members

Add team member

List team members

Delete team member

Common error responses