> ## 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.

# Endpoints

> Complete reference for MCP partner API endpoints — request/response schemas and usage notes.

## 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](/api-reference/mcp/authentication) for details.

***

## Customer management

### Create customer (onboard)

```
POST /api/v1/mcp/customers/onboard
```

Onboard a new customer with optional portal access.

**Request body:**

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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):

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "success": true,
  "message": "Team member deleted successfully"
}
```

***

## Common error responses

All endpoints return standard error responses:

```json theme={null}
{
  "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                                            |