Developer Docs

API Documentation

Complete reference for authentication, endpoint behavior, request contracts, response schemas, and field-level specifications.

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/projects
JSON
{
  "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/projects
JSON
{
  "name": "Updated Project Name",
  "description": "Updated description",
  "logo": "Updated logo url"
}
FieldTypeOptionalNullableEnums/FormatDescriptionNotes
namestringtruefalse-Updated project name-
descriptionstringtruefalse-Updated project description-
logostringtruetrueURLProject logo URL-

Get Conversations

Retrieve paginated conversations for a project.

GET/api/v1/key/projects/conversations
JSON
Query Parameters
{
  "limit": "integer",
  "page": "integer"
}
FieldTypeOptionalNullableEnums/FormatDescriptionNotes
limitintegertruefalse-Items per page-
pageintegertruefalse-Page number-

Get Conversation By ID

Retrieve full conversation detail including messages.

GET/api/v1/key/projects/conversations/:conversationId
JSON
{
  "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/leads
JSON
{
  "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/status
JSON
{
  "status": "WON",
  "reason": "description"
}
FieldTypeOptionalNullableEnums/FormatDescriptionNotes
statusstringfalsefalseWON, LOST, IN_PROGRESSNew lead status-
reasonstringtruetrue-Reason for status update-

Object Schemas

Normalized field contracts used across Project API-Key responses.

Project Object

FieldTypeOptionalNullableEnums/FormatDescriptionNotes
idstring (uuid)falsefalseUUIDProject ID-
namestringfalsefalse-Project name-
descriptionstringfalsefalse-Project description-
logostringtruetrueURLLogo URLNullable
allowedOriginsarray<string>falsefalseURLAllowed origins-
clientIdstringfalsefalse-Client identifier-
planstringfalsefalseENUMPlan type-
maxConversationsintegerfalsefalse-Maximum conversations-
maxMessagesPerConversationintegerfalsefalse-Maximum messages per conversation-
isActivebooleanfalsefalse-Project active state-
createdAtstringfalsefalseISO 8601Creation timestamp-
updatedAtstringfalsefalseISO 8601Update timestamp-
deletedAtstringtruetrueISO 8601Soft-delete timestamp-
pagesarraytruefalse-Page records-
urlstringtruetrueURLWebsite URL-
isLeadEnabledbooleanfalsefalse-Lead capture enabled-
projectOverviewstringtruetrue-Project overview-
targetAudiencestringtruetrue-Target audience-
useCasestringtruetrue-Use case-

Conversation Object

FieldTypeOptionalNullableEnums/FormatDescriptionNotes
idstring (uuid)falsefalseUUIDConversation ID-
titlestringtruetrue-Conversation title-
projectIdstring (uuid)falsefalseUUIDProject ID-
ipAddressstringtruetrue-Requester IP-
userAgentstringtruetrue-Browser user-agent-
statusstringfalsefalseACTIVE, CLOSEDConversation status-
createdAtstringfalsefalseISO 8601Creation timestamp-
updatedAtstringfalsefalseISO 8601Update timestamp-
expiresAtstringtruetrueISO 8601Expiry timestamp-
leadobjecttruetrue-Associated lead object-

Lead Object

FieldTypeOptionalNullableEnums/FormatDescriptionNotes
idstring (uuid)falsefalseUUIDLead ID-
projectIdstring (uuid)falsefalseUUIDProject ID-
conversationIdstring (uuid)falsefalseUUIDConversation ID-
rawAnalysisstringtruetrue-Raw AI analysis outputCan be large text
statusstringfalsefalseWON, LOST, IN_PROGRESS, REJECTEDLead status-
inProgressReasonstringtruetrue-Reason when in progress-
lostReasonstringtruetrue-Reason when lost-
wonReasonstringtruetrue-Reason when won-
rejectedReasonstringtruetrue-Reason when rejected-
chatSummarystringtruetrue-Conversation summary-
intentstringtruetrue-Detected user intent-
engagementLevelstringtruetrueLOW, MEDIUM, HIGHEngagement level-
leadScoreintegertruefalse0-100Lead score-
expectedResponsestringtruetrue-Suggested response-
contactApproachstringtruetrue-Contact strategy-
contactInfoobjecttruetrue-Contact detail object-
painPointsarray<string>truefalse-Extracted pain points-
buyingSignalsarray<string>truefalse-Buying intent indicators-
conversionStrategystringtruetrue-Conversion strategy-
conversionNextStepsarray<string>truefalse-Conversion next steps-
immediateStepsarray<string>truefalse-Immediate action list-
followUpStepsarray<string>truefalse-Follow-up action list-
createdAtstringfalsefalseISO 8601Creation timestamp-

Contact Info Object

FieldTypeOptionalNullableEnums/FormatDescriptionNotes
namestringtruetrue-Lead name-
emailstringtruetrueEmailLead email-
phonestringtruetrue-Lead phoneConsider E.164 format
companystringtruetrue-Company name-
locationstringtruetrue-Geographic location-
other_detailsstringtruetrue-Additional details-