Peer API

The Peers API allows you to interact with AI assistants (peers) in the Cognipeer platform. You can list available peers, get details about specific peers, and send messages to peers.

List Peers

Retrieves a list of all available peers.

Request

GET /v1/client/peer

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Maximum number of peers to return. Default: 10, Max: 100
skip	integer	No	Number of peers to skip. Default: 0
filter	string	No	Filter peers by name or description

Response

{
  "status": "success",
  "data": [
    {
      "_id": "90aa68af-d5c4-4b60-b63e-b732db08bb46",
      "name": "Customer Support Assistant",
      "description": "Helps with product information and troubleshooting",
      "avatarUrl": "https://example.com/avatar.png",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-04-01T14:22:33.000Z"
    },
    {
      "_id": "7b45cd12-a987-4321-b555-e789f0123456",
      "name": "Sales Specialist",
      "description": "Provides information about products and pricing",
      "avatarUrl": "https://example.com/sales-avatar.png",
      "createdAt": "2025-02-20T08:15:00.000Z",
      "updatedAt": "2025-03-25T11:42:15.000Z"
    }
  ]
}

Get Peer

Retrieves details about a specific peer.

Request

GET /v1/client/peer/{peerId}

Path Parameters

Parameter	Type	Required	Description
peerId	string	Yes	ID of the peer to retrieve

Response

{
  "status": "success",
  "data": {
    "_id": "90aa68af-d5c4-4b60-b63e-b732db08bb46",
    "name": "Customer Support Assistant",
    "description": "Helps with product information and troubleshooting",
    "avatarUrl": "https://example.com/avatar.png",
    "modelId": "gpt-4",
    "capabilities": ["answer_questions", "troubleshoot_issues", "explain_features"],
    "topicIds": ["customer-support", "product-information"],
    "datasourceIds": ["ds_12345", "ds_67890"],
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-04-01T14:22:33.000Z"
  }
}

Competition

Sends a message to a peer in competition mode, which creates a new conversation.

Request

POST /v1/client/peer/{peerId}/competition

Path Parameters

Parameter	Type	Required	Description
peerId	string	Yes	ID of the peer to send the message to

Request Body

{
  "content": "Tell me about your products",
  "responseFormat": "text",
  "responseSchema": {
    "type": "object",
    "properties": {
      "products": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "description": { "type": "string" },
            "price": { "type": "number" }
          }
        }
      }
    }
  },
  "additionalContext": {
    "customerType": "enterprise",
    "region": "North America"
  }
}

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')
additionalContext	object	No	Additional context to provide to the peer

Response

Text Response Format

{
  "status": "success",
  "data": {
    "conversationId": "7c8d9e0f-1a2b-3c4d-5e6f-7g8h9i0j1k2l",
    "content": "We offer several products designed for enterprise customers in North America...",
    "role": "ai",
    "createdAt": "2025-04-14T15:30:45.000Z"
  }
}

JSON Response Format

{
  "status": "success",
  "data": {
    "conversationId": "7c8d9e0f-1a2b-3c4d-5e6f-7g8h9i0j1k2l",
    "content": "Response in JSON format",
    "role": "ai",
    "output": {
      "products": [
        {
          "name": "Cognipeer Enterprise",
          "description": "Full-featured AI platform for enterprise",
          "price": 499.99
        },
        {
          "name": "Cognipeer Professional",
          "description": "Professional AI assistant solution",
          "price": 199.99
        }
      ]
    },
    "createdAt": "2025-04-14T15:30:45.000Z"
  }
}

Chat

Chat with a peer by sending a series of messages, creating a new conversation.

Request

POST /v1/client/peer/{peerId}/chat

Path Parameters

Parameter	Type	Required	Description
peerId	string	Yes	ID of the peer to chat with

Request Body

{
  "messages": [
    {
      "role": "user",
      "content": "Hello, who are you?"
    },
    {
      "role": "ai",
      "content": "I am an AI assistant from Cognipeer."
    },
    {
      "role": "user",
      "content": "What services do you offer?"
    }
  ],
  "responseFormat": "text",
  "additionalContext": {
    "customerType": "enterprise"
  }
}

Body Parameters

Parameter	Type	Required	Description
messages	array	Yes	Array of message objects, each with role ('user' or 'ai') and 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')
additionalContext	object	No	Additional context to provide to the peer

Response

{
  "status": "success",
  "data": {
    "conversationId": "7c8d9e0f-1a2b-3c4d-5e6f-7g8h9i0j1k2l",
    "content": "We offer a range of AI services tailored for enterprise customers...",
    "role": "ai",
    "createdAt": "2025-04-14T15:30:45.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	peer_not_found	The specified peer 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