Skip to main content

Custom APIs TeamBusinessEnterprise

Create and manage API keys for programmatic access to Chat Aid. Custom APIs allow you to integrate Chat Aid's AI capabilities into your own applications, scripts, and workflows.

Overview​

Custom APIs enable:

  • Programmatic access to Chat Aid's question-answering capabilities
  • Integration with your own applications and services
  • Custom search configurations per API key
  • Team-specific data access control
  • Independent persona and search flow settings
  • Usage tracking per API key

Creating an API Key​

Step-by-Step​

  1. Navigate to Custom APIs:

    • Go to Settings → Custom APIs

  2. Click "Create API Key":

    • Click the + New API Key button

  3. Configure Settings:

    • Name: Give your API key a descriptive name (e.g., "Support Widget", "Internal Tools")
    • Teams: Select which teams this API key can access
    • Search Settings: Configure data sources and search behavior
    • Persona: Choose the AI persona for responses
    • Search Flow: Select Deep or Quick search
    • Query Filters: Enable advanced filtering (optional)
    • Agent Mode: Enable autonomous agent capabilities (optional)

  4. Save and Copy Key:

    • Click Create
    • Copy the API key immediately
    • Store it securely - it won't be shown again
Security Warning

Treat API keys like passwords! Anyone with your API key can query your Chat Aid knowledge base. Store keys securely and never commit them to version control.

API Key Settings​

Name​

A descriptive label for your API key to help you identify its purpose.

Examples:

  • "Customer Support Widget"
  • "Internal Slack Bot"
  • "Mobile App Integration"
  • "Data Analytics Pipeline"

Teams (Data Access)​

Select which teams' data this API key can access.

Multiple Teams:

  • Select multiple teams to search across combined data sources
  • API queries will search all selected teams
  • User asking the question must have access to the teams (if user context is provided)

No Teams Selected:

  • API key cannot access any team-specific data
  • Only searches organization-wide data sources
  • Use for general knowledge queries only

Best Practice:

  • Create separate API keys for different use cases
  • Limit team access to only what's needed
  • Review team assignments regularly

Search Settings​

Configure what data sources the API key uses to answer questions.

Company Data Sources Only​

  • Search only your indexed company data
  • No external/online information
  • Fastest response time
  • Best for internal knowledge bases

Online Data Only​

  • Search the internet using GPT-4.1 with May 2024 knowledge cutoff
  • No access to your proprietary data
  • Useful for general knowledge questions
  • Good for public-facing applications

Both Company and Online Data​

  • Combined search across company data and online sources
  • Prioritizes company data when available
  • Falls back to online sources when needed
  • Most comprehensive answers

Persona (Optional)​

Write custom instructions to define the AI's personality, tone, and behavior for this API key.

Format:

  • Free-text field (not a dropdown selector)
  • Write custom instructions like: "Be professional and concise, emphasizing a formal tone suitable for business interactions"
  • Overrides the organization-wide persona setting
  • Leave blank to use default behavior

Examples:

  • Support API: "You are a friendly support agent. Be empathetic and provide step-by-step instructions."
  • Sales API: "You are a consultative sales assistant. Focus on value and benefits, avoid technical jargon."
  • Technical API: "You are a technical expert. Use precise terminology and include code examples."
Different from Organization Personas

Custom APIs use a text field for persona instructions, not the personas created in Settings → Personas. This allows API-specific customization independent of your organization's settings.

Entry Point​

Tag for tracking where queries originate.

Examples:

  • website-widget
  • mobile-app
  • slack-bot
  • internal-dashboard

Usage:

  • Track API usage by source
  • Analyze which entry points get the most queries
  • Debug integration issues

Agent Mode​

Enable autonomous agent capabilities for this API key.

When Enabled:

  • Chat Aid can take actions to answer questions
  • May query multiple data sources
  • Can execute multi-step reasoning
  • Longer response times but more thorough answers

When Disabled:

  • Standard search and response
  • Single-pass answer generation
  • Faster responses
  • Simpler, more predictable behavior
note

Agent mode is more powerful but may use more resources. Enable only when needed for complex queries.

Search Flow​

Choose the search depth and speed tradeoff.

Deep Search:

  • Thorough, comprehensive search
  • Multiple search strategies
  • Longer processing time (typically 15-60 seconds)
  • Best for complex or important queries
  • Higher quality answers

Quick Search:

  • Fast, efficient search
  • Single-pass search strategy
  • Minimal processing time (typically 5-15 seconds)
  • Best for simple queries or high-volume APIs
  • Good enough for most use cases

Recommendation:

  • Use Deep for customer-facing applications
  • Use Quick for internal tools or high-volume endpoints

Query Filters​

Enable advanced query filtering capabilities.

When Enabled:

  • API can filter by document IDs
  • Filter by specific data sources/providers
  • Filter by tags/categories
  • Exclude specific data sources (e.g., exclude Slack messages)

Use Cases:

  • Search only specific documents
  • Search only certain integrations (e.g., only Confluence)
  • Exclude conversational data from results
  • Build custom search experiences

API Usage:

{
  "question": "What is our return policy?",
  "queryFilters": {
    "providers": ["confluence"],
    "excludeSlack": true
  }
}

See Wiki Filters in the API documentation for detailed usage.

Manage Sources Permission​

Grant this API key permission to add and manage data sources.

When Enabled:

  • API can add new documents to the knowledge base
  • Can update existing documents
  • Can remove documents
  • Useful for automation workflows

When Disabled (Default):

  • API can only query existing data
  • Cannot modify data sources
  • Recommended for most use cases
Security Risk

Only enable source management for trusted internal applications. This permission allows full control over your knowledge base content.

Managing API Keys​

Viewing API Keys​

The Custom APIs page shows all your API keys with:

  • Key name
  • Creation date
  • Masked key (e.g., sk-...abc123)
  • Usage statistics
  • Status (active/disabled)

Editing API Keys​

  1. Click on an API key in the list
  2. Modify settings as needed
  3. Click Save Changes
note

You cannot view the full API key again after creation. If lost, you must create a new key.

Disabling API Keys​

Temporarily disable an API key without deleting it:

  1. Click on the API key
  2. Toggle Status to Disabled
  3. Click Save

Effect:

  • API requests will immediately fail with authentication error
  • Settings and configuration are preserved
  • Can re-enable anytime

Use Cases:

  • Temporary maintenance
  • Security incident response
  • Testing without deleting the key

Deleting API Keys​

Permanently remove an API key:

  1. Click on the API key
  2. Click Delete API Key
  3. Confirm deletion
Irreversible

Deleting an API key is permanent. Applications using the key will immediately lose access.

Regenerating API Keys​

If an API key is compromised, you cannot regenerate it. Instead:

  1. Create a new API key with the same settings
  2. Update your application to use the new key
  3. Delete the old API key

Best Practice:

  • Rotate API keys regularly (every 90 days)
  • Use environment variables for key storage
  • Never hardcode keys in source code

Using the API​

For complete API documentation including endpoints, authentication, request/response formats, query filters, code examples, and more, see the API Reference Guide.

Quick Links:

Usage Tracking​

Viewing Usage​

Track API key usage:

  1. Go to Settings → Custom APIs
  2. View Interactions column for each API key
  3. Click on an API key to see detailed usage

Metrics:

  • Total queries
  • Queries per day/week/month
  • Average response time
  • Error rate

Usage Limits​

API usage counts toward your plan's:

  • Question limits: Each API query counts as 1 question
  • Rate limits: Requests per minute (varies by plan)

See Billing for plan limits.

Monitoring​

Set up monitoring for production APIs:

  • Track error rates
  • Monitor response times
  • Set up alerts for unusual activity
  • Review usage patterns regularly

Security Best Practices​

1. Store Keys Securely​

  • ✅ Use environment variables
  • ✅ Use secrets management tools (AWS Secrets Manager, HashiCorp Vault)
  • ✅ Encrypt at rest
  • ❌ Never commit to version control
  • ❌ Never log full API keys
  • ❌ Never share via email or chat

2. Principle of Least Privilege​

  • Create separate API keys for each application
  • Limit team access to only what's needed
  • Disable source management unless required
  • Use query filters to restrict data access

3. Regular Rotation​

  • Rotate API keys every 90 days
  • Immediately rotate if compromised
  • Keep rotation schedule documented
  • Test new keys before deleting old ones

4. Monitor for Anomalies​

  • Track unusual query patterns
  • Monitor failed authentication attempts
  • Set up alerts for high-volume usage
  • Review logs regularly

5. Rate Limiting​

Implement rate limiting in your application:

  • Prevents abuse
  • Protects your question quota
  • Reduces costs
  • Improves reliability

Common Integration Patterns​

1. Customer Support Widget​

Configuration:

  • Teams: Support documentation team
  • Search: Company data only
  • Persona: Support Agent
  • Flow: Deep search
  • Filters: Enabled (exclude internal docs)

Use Case: Embed Chat Aid in your customer support portal for instant answers.

2. Internal Slack Bot​

Configuration:

  • Teams: All teams
  • Search: Company and online data
  • Persona: Default
  • Flow: Quick search
  • Agent: Enabled

Use Case: Custom Slack bot that queries Chat Aid on behalf of users.

3. Mobile App Integration​

Configuration:

  • Teams: Public knowledge base team
  • Search: Company data only
  • Persona: Friendly Assistant
  • Flow: Quick search
  • Filters: Disabled

Use Case: In-app help system that answers user questions.

4. Data Analytics Pipeline​

Configuration:

  • Teams: Analytics team
  • Search: Company data only
  • Persona: Default
  • Flow: Deep search
  • Filters: Enabled
  • Source Management: Enabled

Use Case: Automated system that trains Chat Aid on new reports and queries for insights.

Troubleshooting​

Authentication Errors​

Error: "Invalid API Key"

Causes:

  • Key was deleted
  • Key was disabled
  • Key was copied incorrectly
  • Using wrong environment/key

Solutions:

  • Verify key is active in Custom APIs settings
  • Check for extra spaces or characters
  • Ensure using correct key for environment
  • Generate a new key if lost

Rate Limit Errors​

Error: "Rate limit exceeded"

Causes:

  • Too many requests per minute
  • Burst traffic spike
  • Shared key across multiple applications

Solutions:

  • Implement exponential backoff
  • Reduce request frequency
  • Create separate keys for each application
  • Upgrade plan for higher limits

Search Results Issues​

Problem: Not finding expected documents

Check:

  1. Are the teams assigned to the API key?
  2. Are query filters excluding the documents?
  3. Is the document indexed and active?
  4. Are you searching the right teams?

Solutions:

  • Add missing teams to API key configuration
  • Adjust or remove query filters
  • Verify document status in Data Sources
  • Test with broader team selection

Timeout Errors​

Problem: Requests timing out

Causes:

  • Deep search on large data set
  • Agent mode with complex queries
  • Network issues

Solutions:

  • Switch to Quick search for faster responses
  • Disable agent mode if not needed
  • Increase client timeout settings
  • Use streaming for long-running queries

API Documentation​

For complete API reference documentation, see the API Reference Guide.

Need Help?

Our support team is here to help you get the most out of Chat Aid.