API Reference Overview

The Cognipeer API allows you to programmatically interact with the Cognipeer platform, enabling you to create, manage, and deploy AI assistants (peers) and their associated resources. This reference provides detailed information about the available endpoints, authentication methods, and data models.

Base URL

All API requests should be made to the following base URL:

https://api.cognipeer.com/v1

Authentication

The Cognipeer API uses API keys for authentication. You can obtain an API key from your Cognipeer Dashboard under Settings > API Keys.

Include your API key in all requests using the Authorization header:

Authorization: Bearer YOUR_API_KEY

Rate Limits

The Cognipeer API implements rate limiting to ensure fair usage and platform stability. Current rate limits are:

• 100 requests per minute per API key
• 5,000 requests per day per API key

Rate limit information is included in the response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1715291260

If you exceed the rate limit, you'll receive a 429 Too Many Requests response.

Versioning

The Cognipeer API uses versioning to ensure backward compatibility. The current version is v1. The version is included in the URL path.

Future API versions will be announced with adequate notice and migration guides.

Response Format

All API responses are returned in JSON format. Successful responses include a data object with the requested information:

{
  "data": {
    "id": "peer_123456",
    "name": "Support Assistant",
    "description": "An AI assistant for customer support",
    "createdAt": "2025-03-15T12:00:00.000Z",
    "updatedAt": "2025-04-10T09:30:00.000Z"
  }
}

Error responses include an error object with details about what went wrong:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key",
    "status": 401
  }
}

Common Status Codes

Status Code	Description
200	OK - The request was successful
201	Created - The resource was successfully created
400	Bad Request - The request was invalid or cannot be otherwise served
401	Unauthorized - Authentication failed or credentials were not provided
403	Forbidden - The authenticated user doesn't have permission
404	Not Found - The requested resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Server Error - Something went wrong on our end

Available Endpoints

The Cognipeer API is organized around the following resources:

Peers

Endpoints for managing AI assistants (peers):

• GET /peer - List all peers
• POST /peer - Create a new peer
• GET /peer/{id} - Get a specific peer
• PUT /peer/{id} - Update a peer
• DELETE /peer/{id} - Delete a peer

Conversations

Endpoints for managing conversations with peers:

• GET /conversation - List all conversations
• POST /conversation - Create a new conversation
• GET /conversation/{id} - Get a specific conversation
• DELETE /conversation/{id} - Delete a conversation
• POST /conversation/{id}/messages - Send a message in a conversation
• GET /conversation/{id}/messages - List messages in a conversation

Evaluation

Endpoints for testing and evaluating peer performance:

• POST /evaluation - Create evaluation suite
• GET /evaluation - List evaluation suites
• GET /evaluation/{id} - Get evaluation suite
• POST /evaluation/{id}/run - Run evaluation
• POST /evaluation/{id}/questions/import - Import questions
• POST /evaluation/{runId}/suggest-improvements - Get AI analysis

Widgets

Endpoints for managing custom widgets:

• POST /widget - Create widget
• GET /widget - List widgets
• GET /widget/{id} - Get widget details
• PUT /widget/{id} - Update widget
• POST /peer/{id}/widgets - Add widget to peer

Error Handling

For robust applications, implement proper error handling. The Cognipeer API may return various error types:

async function callCognipeerApi(endpoint) {
  try {
    const response = await fetch(`https://api.cognipeer.com/v1${endpoint}`, {
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      }
    });
    
    const data = await response.json();
    
    if (!response.ok) {
      // Handle API errors
      if (response.status === 401) {
        // Handle authentication errors
        console.error("Authentication failed. Please check your API key.");
      } else if (response.status === 429) {
        // Handle rate limiting
        const resetTime = response.headers.get('X-RateLimit-Reset');
        console.error(`Rate limit exceeded. Try again after ${new Date(resetTime * 1000).toLocaleTimeString()}`);
      } else {
        // Handle other errors
        console.error(`API Error: ${data.error.message}`);
      }
      return null;
    }
    
    return data;
  } catch (error) {
    // Handle network errors
    console.error("Network error:", error);
    return null;
  }
}

SDKs and Client Libraries

To simplify API integration, Cognipeer provides official client libraries for several programming languages:

• JavaScript/TypeScript - @cognipeer/client-js