Authentication
All project endpoints require API-KEY bearer authentication.
JSON
{
"Authorization": "Bearer {{API-KEY}}"
}Get Project
Retrieve project metadata and configuration.
GET
/api/v1/key/projectsJSON
{
"success": true,
"data": {
"id": "UUID",
"name": "Project Name",
"description": "Project Description",
"clientId": "Client ID",
"plan": "Type of Plan",
"maxConversations": 0,
"maxMessagesPerConversation": 0,
"isActive": true
},
"message": "Project retrieved successfully"
}Update Project
Update project metadata such as name, description, and logo.
PUT
/api/v1/key/projectsJSON
{
"name": "Updated Project Name",
"description": "Updated description",
"logo": "Updated logo url"
}| Field | Type | Optional | Nullable | Enums/Format | Description | Notes |
|---|---|---|---|---|---|---|
| name | string | true | false | - | Updated project name | - |
| description | string | true | false | - | Updated project description | - |
| logo | string | true | true | URL | Project logo URL | - |
Get Conversations
Retrieve paginated conversations for a project.
GET
/api/v1/key/projects/conversationsJSON
Query Parameters
{
"limit": "integer",
"page": "integer"
}| Field | Type | Optional | Nullable | Enums/Format | Description | Notes |
|---|---|---|---|---|---|---|
| limit | integer | true | false | - | Items per page | - |
| page | integer | true | false | - | Page number | - |
Get Conversation By ID
Retrieve full conversation detail including messages.
GET
/api/v1/key/projects/conversations/:conversationIdJSON
{
"success": true,
"data": {
"id": "UUID",
"title": "Conversation title",
"status": "CLOSED",
"messages": [
{ "id": "UUID", "role": "USER", "content": "User Message" },
{ "id": "UUID", "role": "ASSISTANT", "content": "Assistant reply" }
]
}
}Get Leads
Retrieve all lead analysis records for the project.
GET
/api/v1/key/projects/leadsJSON
{
"success": true,
"data": [
{
"id": "UUID",
"projectId": "UUID",
"conversationId": "UUID",
"status": "WON",
"leadScore": 86,
"contactInfo": {
"name": "Lead Name",
"email": "Lead Email"
},
"createdAt": "ISO timestamp"
}
]
}Update Lead Status
Update lead outcome and reason details.
PUT
/api/v1/key/projects/leads/:leadId/statusJSON
{
"status": "WON",
"reason": "description"
}| Field | Type | Optional | Nullable | Enums/Format | Description | Notes |
|---|---|---|---|---|---|---|
| status | string | false | false | WON, LOST, IN_PROGRESS | New lead status | - |
| reason | string | true | true | - | Reason for status update | - |
Object Schemas
Normalized field contracts used across Project API-Key responses.
Project Object
| Field | Type | Optional | Nullable | Enums/Format | Description | Notes |
|---|---|---|---|---|---|---|
| id | string (uuid) | false | false | UUID | Project ID | - |
| name | string | false | false | - | Project name | - |
| description | string | false | false | - | Project description | - |
| logo | string | true | true | URL | Logo URL | Nullable |
| allowedOrigins | array<string> | false | false | URL | Allowed origins | - |
| clientId | string | false | false | - | Client identifier | - |
| plan | string | false | false | ENUM | Plan type | - |
| maxConversations | integer | false | false | - | Maximum conversations | - |
| maxMessagesPerConversation | integer | false | false | - | Maximum messages per conversation | - |
| isActive | boolean | false | false | - | Project active state | - |
| createdAt | string | false | false | ISO 8601 | Creation timestamp | - |
| updatedAt | string | false | false | ISO 8601 | Update timestamp | - |
| deletedAt | string | true | true | ISO 8601 | Soft-delete timestamp | - |
| pages | array | true | false | - | Page records | - |
| url | string | true | true | URL | Website URL | - |
| isLeadEnabled | boolean | false | false | - | Lead capture enabled | - |
| projectOverview | string | true | true | - | Project overview | - |
| targetAudience | string | true | true | - | Target audience | - |
| useCase | string | true | true | - | Use case | - |
Conversation Object
| Field | Type | Optional | Nullable | Enums/Format | Description | Notes |
|---|---|---|---|---|---|---|
| id | string (uuid) | false | false | UUID | Conversation ID | - |
| title | string | true | true | - | Conversation title | - |
| projectId | string (uuid) | false | false | UUID | Project ID | - |
| ipAddress | string | true | true | - | Requester IP | - |
| userAgent | string | true | true | - | Browser user-agent | - |
| status | string | false | false | ACTIVE, CLOSED | Conversation status | - |
| createdAt | string | false | false | ISO 8601 | Creation timestamp | - |
| updatedAt | string | false | false | ISO 8601 | Update timestamp | - |
| expiresAt | string | true | true | ISO 8601 | Expiry timestamp | - |
| lead | object | true | true | - | Associated lead object | - |
Lead Object
| Field | Type | Optional | Nullable | Enums/Format | Description | Notes |
|---|---|---|---|---|---|---|
| id | string (uuid) | false | false | UUID | Lead ID | - |
| projectId | string (uuid) | false | false | UUID | Project ID | - |
| conversationId | string (uuid) | false | false | UUID | Conversation ID | - |
| rawAnalysis | string | true | true | - | Raw AI analysis output | Can be large text |
| status | string | false | false | WON, LOST, IN_PROGRESS, REJECTED | Lead status | - |
| inProgressReason | string | true | true | - | Reason when in progress | - |
| lostReason | string | true | true | - | Reason when lost | - |
| wonReason | string | true | true | - | Reason when won | - |
| rejectedReason | string | true | true | - | Reason when rejected | - |
| chatSummary | string | true | true | - | Conversation summary | - |
| intent | string | true | true | - | Detected user intent | - |
| engagementLevel | string | true | true | LOW, MEDIUM, HIGH | Engagement level | - |
| leadScore | integer | true | false | 0-100 | Lead score | - |
| expectedResponse | string | true | true | - | Suggested response | - |
| contactApproach | string | true | true | - | Contact strategy | - |
| contactInfo | object | true | true | - | Contact detail object | - |
| painPoints | array<string> | true | false | - | Extracted pain points | - |
| buyingSignals | array<string> | true | false | - | Buying intent indicators | - |
| conversionStrategy | string | true | true | - | Conversion strategy | - |
| conversionNextSteps | array<string> | true | false | - | Conversion next steps | - |
| immediateSteps | array<string> | true | false | - | Immediate action list | - |
| followUpSteps | array<string> | true | false | - | Follow-up action list | - |
| createdAt | string | false | false | ISO 8601 | Creation timestamp | - |
Contact Info Object
| Field | Type | Optional | Nullable | Enums/Format | Description | Notes |
|---|---|---|---|---|---|---|
| name | string | true | true | - | Lead name | - |
| string | true | true | Lead email | - | ||
| phone | string | true | true | - | Lead phone | Consider E.164 format |
| company | string | true | true | - | Company name | - |
| location | string | true | true | - | Geographic location | - |
| other_details | string | true | true | - | Additional details | - |
