Skip to main content

Getting Started with the Chat Aid API

Learn how to authenticate, make your first request, and understand error handling.

Overview​

The Chat Aid API provides programmatic access to your organization's knowledge base. Query your connected data sources and receive AI-generated answers with source citations.

Base URL: https://api.chataid.com

Content Type: application/json

Quick Start​

1. Get an API Key​

  1. Navigate to Settings → Custom APIs
  2. Click + New API Key
  3. Configure:
    • Name: Descriptive identifier
    • Teams: Select accessible data sources
    • Search Settings: Configure behavior (Quick/Deep)
    • Persona: Optional AI personality
  4. Click Create and copy your key immediately
Store Securely

API keys are shown only once. Never expose them in client-side code or commit to version control.

2. Make Your First Request​

curl -X POST https://api.chataid.com/chat/completions/custom \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "What is our refund policy?"}'

Response:

{
  "ok": true,
  "promptId": "65e1c08202791119fbe1d476",
  "pollEndpoint": "https://api.chataid.com/chat/completions/custom/65e1c08202791119fbe1d476",
  "timeInterval": 5000
}

3. Poll for the Answer​

curl https://api.chataid.com/chat/completions/custom/65e1c08202791119fbe1d476 \
  -H "Authorization: YOUR_API_KEY"

When ready (canPoll: false):

{
  "ok": true,
  "data": {
    "canPoll": false,
    "response": "Our refund policy allows...",
    "sources": {
      "formatted": "**Sources:**\n- [Refund Policy](https://...)",
      "raw": [{"name": "Refund Policy", "provider": "confluence", "url": "https://..."}]
    }
  }
}
Complete Examples

See Asking Questions for full implementations in JavaScript, Python, and cURL including polling logic.

Authentication​

Include your API key in the Authorization header:

Authorization: YOUR_API_KEY
No Bearer Prefix

Chat Aid does not use a "Bearer " prefix. Include only the API key.

Authentication Errors​

Error MessageSolution
Unauthorized: No Authorization Token ProvidedAdd Authorization: YOUR_API_KEY header
Unauthorized: Invalid Access TokenGenerate a new API key in Settings → Custom APIs

Error Handling​

All errors return a consistent format:

{
  "ok": false,
  "message": "Human-readable error description"
}

Common Errors​

StatusErrorSolution
401Unauthorized: No Authorization Token ProvidedAdd Authorization header
401Unauthorized: Invalid Access TokenGenerate new API key
403You are forbidden from accessing this resourceCheck API key permissions
426You have reached your limit for this billing cycleUpgrade plan or wait for reset

Basic Error Handling​

Error Handling Example
const response = await fetch('https://api.chataid.com/chat/completions/custom', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ prompt: 'What is our refund policy?' })
});

const data = await response.json();

if (!data.ok) {
  throw new Error(`API Error: ${data.message}`);
}

Best Practices​

Security​

  • Never expose API keys in client-side code
  • Store keys in environment variables
  • Rotate keys every 90 days
  • Create separate keys per application

Performance​

  • Cache responses for 30-60 minutes
  • Respect the timeInterval when polling
  • Stop polling when canPoll is false
  • Set reasonable timeouts (60-300 seconds)

Error Handling​

  • Implement exponential backoff for 5xx errors
  • Log errors with context (prompt ID, timestamp)
  • Handle all error codes gracefully

Data Access​

  • Assign appropriate teams to each API key
  • Use wikiFilters to restrict search scope
  • Test with sample data before production

Next Steps​

Core Endpoints​

  • Asking Questions - Query your knowledge base

    • Complete request/response documentation
    • Polling implementation examples
    • Wiki filters and conversation threading

  • Training Sources - Manage file uploads

    • Upload, list, retrieve, and delete files
    • Bulk operations and filtering

Configuration​

Support​

Need Help?

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