Conversation API

The Conversations API allows you to create and manage conversations with Cognipeer AI assistants (peers). Each conversation represents a session between a user and a peer.

Create Conversation

Creates a new conversation with a specific peer.

Request

POST /v1/client/conversation

Request Body

{
  "peerId": "90aa68af-d5c4-4b60-b63e-b732db08bb46"
}

Body Parameters

Parameter	Type	Required	Description
peerId	string	Yes	ID of the peer to create a conversation with

Response

{
  "status": "success",
  "data": {
    "_id": "7c8d9e0f-1a2b-3c4d-5e6f-7g8h9i0j1k2l",
    "peerId": "90aa68af-d5c4-4b60-b63e-b732db08bb46",
    "userId": "usr_12345",
    "createdAt": "2025-04-14T15:30:45.000Z",
    "updatedAt": "2025-04-14T15:30:45.000Z"
  }
}

List Conversations

Retrieves a list of conversations for the authenticated user.

Request

GET /v1/client/conversation

Query Parameters

Parameter	Type	Required	Description
peerId	string	No	Filter conversations by peer ID
limit	integer	No	Maximum number of conversations to return. Default: 10, Max: 100
skip	integer	No	Number of conversations to skip. Default: 0

Response

{
  "status": "success",
  "data": [
    {
      "_id": "7c8d9e0f-1a2b-3c4d-5e6f-7g8h9i0j1k2l",
      "peerId": "90aa68af-d5c4-4b60-b63e-b732db08bb46",
      "userId": "usr_12345",
      "lastMessage": {
        "content": "How can I help you today?",
        "role": "ai",
        "createdAt": "2025-04-14T15:30:45.000Z"
      },
      "createdAt": "2025-04-14T15:30:45.000Z",
      "updatedAt": "2025-04-14T15:35:12.000Z"
    },
    {
      "_id": "2a3b4c5d-6e7f-8g9h-0i1j-2k3l4m5n6o7p",
      "peerId": "7b45cd12-a987-4321-b555-e789f0123456",
      "userId": "usr_12345",
      "lastMessage": {
        "content": "What products are available?",
        "role": "user",
        "createdAt": "2025-04-12T10:22:33.000Z"
      },
      "createdAt": "2025-04-12T10:20:18.000Z",
      "updatedAt": "2025-04-12T10:22:33.000Z"
    }
  ]
}

Get Conversation

Retrieves details about a specific conversation.

Request

GET /v1/client/conversation/{conversationId}

Path Parameters

Parameter	Type	Required	Description
conversationId	string	Yes	ID of the conversation to retrieve

Response

{
  "status": "success",
  "data": {
    "_id": "7c8d9e0f-1a2b-3c4d-5e6f-7g8h9i0j1k2l",
    "peerId": "90aa68af-d5c4-4b60-b63e-b732db08bb46",
    "userId": "usr_12345",
    "createdAt": "2025-04-14T15:30:45.000Z",
    "updatedAt": "2025-04-14T15:35:12.000Z"
  }
}

Get Conversation Messages

Retrieves messages from a specific conversation.

Request

GET /v1/client/conversation/{conversationId}/message

Path Parameters

Parameter	Type	Required	Description
conversationId	string	Yes	ID of the conversation to retrieve messages from

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Maximum number of messages to return. Default: 10, Max: 100
skip	string	No	Number of messages to skip. Default: 0

Response

{
  "status": "success",
  "data": [
    {
      "_id": "msg_12345",
      "conversationId": "7c8d9e0f-1a2b-3c4d-5e6f-7g8h9i0j1k2l",
      "content": "Hello, how can I help you today?",
      "role": "ai",
      "createdAt": "2025-04-14T15:30:45.000Z"
    },
    {
      "_id": "msg_12346",
      "conversationId": "7c8d9e0f-1a2b-3c4d-5e6f-7g8h9i0j1k2l",
      "content": "I'm looking for information about your premium plan.",
      "role": "user",
      "createdAt": "2025-04-14T15:31:22.000Z"
    },
    {
      "_id": "msg_12347",
      "conversationId": "7c8d9e0f-1a2b-3c4d-5e6f-7g8h9i0j1k2l",
      "content": "Our premium plan offers several benefits...",
      "role": "ai",
      "createdAt": "2025-04-14T15:31:45.000Z"
    }
  ]
}

Send Message

Sends a message to an existing conversation.

Request

POST /v1/client/conversation/{conversationId}/message

Path Parameters

Parameter	Type	Required	Description
conversationId	string	Yes	ID of the conversation to send a message to

Request Body

{
  "content": "What features are included in the premium plan?",
  "responseFormat": "text"
}

Body Parameters

Parameter	Type	Required	Description
content	string	Yes	The message content
responseFormat	string	No	Format of the response. Can be 'text' (default) or 'json'
responseSchema	object	No	JSON schema for structured responses (when responseFormat is 'json')

Response (Text Format)

{
  "status": "success",
  "data": {
    "_id": "msg_12348",
    "conversationId": "7c8d9e0f-1a2b-3c4d-5e6f-7g8h9i0j1k2l",
    "content": "The premium plan includes the following features: 1. Advanced analytics...",
    "role": "ai",
    "createdAt": "2025-04-14T15:32:15.000Z"
  }
}

Response (JSON Format)

{
  "status": "success",
  "data": {
    "_id": "msg_12348",
    "conversationId": "7c8d9e0f-1a2b-3c4d-5e6f-7g8h9i0j1k2l",
    "content": "Response in JSON format",
    "role": "ai",
    "output": {
      "features": [
        {
          "name": "Advanced Analytics",
          "description": "Detailed insights into user interactions and AI performance"
        },
        {
          "name": "Custom Branding",
          "description": "Ability to fully customize the appearance of your AI assistants"
        },
        {
          "name": "Priority Support",
          "description": "24/7 dedicated technical support"
        }
      ],
      "pricing": {
        "monthly": 199.99,
        "annual": 1999.99
      }
    },
    "createdAt": "2025-04-14T15:32:15.000Z"
  }
}

Error Responses

Status Code	Error Code	Description
400	invalid_request	The request was malformed or missing required parameters
401	unauthorized	The API key is invalid or missing
403	forbidden	The API key does not have permission to perform this action
404	conversation_not_found	The specified conversation does not exist
429	rate_limit_exceeded	Too many requests in a given amount of time
500	server_error	An unexpected error occurred on the server