API Channels

API Channels provide programmatic access to your peers through the Cognipeer SDK and REST API. Each API channel generates a unique hookId that identifies which peer should handle requests.

Overview

An API Channel:

• Connects to exactly one peer
• Generates a unique hookId for authentication
• Can have custom settings (prompt, message history)
• Can be enabled/disabled without deletion
• Tracks usage and last sync date

Creating an API Channel

Step 1: Navigate to Peer Settings

1. Go to your peer list
2. Select the peer you want to connect to
3. Click on the Channels tab

Step 2: Add API Channel

1. Click Add Channel or Channel Gallery
2. Find and select API Access
3. Click Install or Create

Step 3: Configure Channel

1. Name: Give your channel a descriptive name (e.g., "Production API", "Development")
2. Custom Prompt (optional): Add channel-specific instructions
3. Message History (optional): Override peer's default message count
4. Click Save

Step 4: Copy Hook ID

1. After creation, you'll see your channel in the list
2. Copy the hookId - you'll need this for SDK configuration
3. Keep the hookId secure (though less sensitive than your PAT)

Using API Channels

With the SDK

import { CognipeerClient } from '@cognipeer/sdk';

const client = new CognipeerClient({
  token: 'token',
  hookId: 'your-channel-hook-id'
});

// All requests will use the peer associated with this channel
const response = await client.conversations.create({
  messages: [{ role: 'user', content: 'Hello!' }]
});

With REST API

fetch('https://api.cognipeer.com/v1/sdk/conversation', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer oken',
    'Content-Type': 'application/json',
    'X-Hook-Id': 'your-channel-hook-id'
  },
  body: JSON.stringify({
    messages: [{ role: 'user', content: 'Hello!' }]
  })
});

Channel Settings

Custom Prompt

Add channel-specific instructions that will be included in the system prompt:

Example:

When responding through the production API, always format responses 
in JSON and keep them concise. Focus on actionable information.

This prompt is added to the peer's system prompt when messages come through this channel.

Message History Limit

Override the peer's default message history setting for this channel:

• Empty: Use peer's default setting
• Custom Number: Include this many previous messages in context

Example:

• Peer default: 20 messages
• API Channel: 5 messages (for cost optimization)

Managing Channels

Viewing Channels

1. Go to Peer Settings → Channels
2. See all channels with their status, hookId, and settings
3. Click on a channel to view details

Editing Channels

1. Click on the channel in the list
2. Modify settings:
   • Name
   • Custom prompt
   • Message history limit
   • Active status
3. Click Save

Disabling Channels

To temporarily disable a channel without deleting it:

1. Click on the channel
2. Toggle Active status to OFF
3. Click Save

Disabled channels will reject API requests with a 403 error.

Deleting Channels

WARNING

Deleting a channel invalidates its hookId. Any applications using that hookId will stop working.

To delete a channel:

1. Click on the channel
2. Click Delete Channel
3. Confirm deletion

Multiple Channels

You can create multiple API channels for the same peer to:

Separate Environments

// Production
const prodClient = new CognipeerClient({
  token: process.env.PROD_PAT,
  hookId: process.env.PROD_HOOK_ID
});

// Staging
const stagingClient = new CognipeerClient({
  token: process.env.STAGING_PAT,
  hookId: process.env.STAGING_HOOK_ID
});

// Development
const devClient = new CognipeerClient({
  token: process.env.DEV_PAT,
  hookId: process.env.DEV_HOOK_ID
});

Different Use Cases

// Customer support channel - include more history
const supportChannel = {
  hookId: 'support-hook-id',
  settings: { messagesCount: 50 }
};

// Analytics channel - optimized for speed
const analyticsChannel = {
  hookId: 'analytics-hook-id',
  settings: { messagesCount: 5 }
};

Partner Integrations

Create separate channels for each partner integration to:

• Track usage per partner
• Apply partner-specific prompts
• Enable/disable partners independently

Security Best Practices

Hook ID Security

While hookIds are less sensitive than PATs, still follow these practices:

✅ Do:

• Store hookIds in environment variables
• Use different hookIds for different environments
• Rotate hookIds periodically for production
• Monitor hookId usage through the dashboard

❌ Don't:

• Commit hookIds to public repositories
• Share hookIds across environments
• Expose hookIds in client-side code
• Reuse hookIds across different applications

Access Control

• Use separate PATs for different users/applications
• Create dedicated channels for each integration
• Disable unused channels
• Delete channels that are no longer needed

Monitoring and Analytics

Channel Dashboard

View channel metrics:

• Total conversations created
• Messages sent
• Last used timestamp
• Error rates

Usage Tracking

// Get channel information
const channel = await client.channels.get();

console.log('Channel:', channel.name);
console.log('Last used:', channel.updatedAt);
console.log('Status:', channel.isActive ? 'Active' : 'Inactive');

Troubleshooting

"Channel not found" Error

Possible causes:

• HookId is incorrect or misspelled
• Channel has been deleted
• Wrong API endpoint

Solution:

• Verify hookId in channel settings
• Check channel hasn't been deleted
• Ensure you're using the correct API URL

"Channel disabled" Error (403)

Cause: Channel's isActive status is false

Solution:

1. Go to channel settings
2. Enable the channel
3. Save changes

Conversations Not Using Expected Peer

Cause: Wrong hookId or channel configured incorrectly

Solution:

1. Verify hookId matches the intended channel
2. Check channel's peerId matches expected peer
3. Use client.peers.get() to verify which peer is being used

Rate Limiting

If you hit rate limits:

• Use multiple channels to distribute load
• Implement exponential backoff
• Contact support for higher limits

API Reference

Get Channel Information

const channel = await client.channels.get();

Returns:

{
  _id: string;
  name: string;
  hookId: string;
  peerId: string;
  channelType: 'api';
  isActive: boolean;
  prompt?: string;
  messagesCount?: number;
  createdAt: string;
  updatedAt: string;
}

Examples

Basic Usage

import { CognipeerClient } from '@cognipeer/sdk';

// Initialize with channel
const client = new CognipeerClient({
  token: process.env.COGNIPEER_TOKEN,
  hookId: process.env.COGNIPEER_HOOK_ID
});

// Verify channel is active
const channel = await client.channels.get();
if (!channel.isActive) {
  throw new Error('API channel is disabled');
}

// Get associated peer
const peer = await client.peers.get();
console.log(`Using peer: ${peer.name}`);

// Create conversation
const response = await client.conversations.create({
  messages: [{ role: 'user', content: 'Hello!' }]
});

Environment-Specific Channels

# .env.production
COGNIPEER_TOKEN=pat_prod_token
COGNIPEER_HOOK_ID=prod_hook_id

# .env.development
COGNIPEER_TOKEN=pat_dev_token
COGNIPEER_HOOK_ID=dev_hook_id

// config.ts
const client = new CognipeerClient({
  token: process.env.COGNIPEER_TOKEN!,
  hookId: process.env.COGNIPEER_HOOK_ID!
});

export default client;

Dynamic Channel Selection

function getClient(environment: 'prod' | 'dev' | 'staging') {
  const configs = {
    prod: {
      token: process.env.PROD_PAT,
      hookId: process.env.PROD_HOOK_ID
    },
    dev: {
      token: process.env.DEV_PAT,
      hookId: process.env.DEV_HOOK_ID
    },
    staging: {
      token: process.env.STAGING_PAT,
      hookId: process.env.STAGING_HOOK_ID
    }
  };

  return new CognipeerClient(configs[environment]);
}

const client = getClient(process.env.NODE_ENV as any);

Next Steps

• Authentication - Learn about Personal Access Tokens
• JavaScript SDK - Complete SDK documentation
• Conversation API - Create and manage conversations
• API Reference - Full API documentation

Support

Need help with API channels?

• 📖 Documentation
• 💬 Discord Community
• 📧 Email Support