API Connection

Overview

The API Connection feature allows you to interact with Attive programmatically through a REST API. Using API keys, you can send messages to your AI agents, continue chat conversations, and integrate Attive's intelligence into your own applications, workflows, and automations.

This is ideal for:

• Building custom integrations with your internal tools
• Automating workflows that need AI-powered insights
• Embedding Attive's capabilities into third-party applications
• Creating chatbots or assistants that leverage your GTM data

Prerequisites

Before using the API, you need:

1. Admin access to your Attive workspace
2. An API key generated from the workspace settings

Managing API Keys

Creating an API Key

1. Navigate to Settings > API Keys in your workspace
2. Enter a descriptive name for your key (e.g., "Production Integration", "Testing")
3. Click Create Key
4. Important: Copy and save your API key immediately — you won't be able to see it again after this step

Managing Existing Keys

The API Keys page displays all your workspace's API keys with:

• Key name: The descriptive name you provided
• Key prefix: The first few characters of the key for identification
• Created by: Who created the key
• Created date: When the key was created
• Last used: When the key was last used for an API request

To delete a key, click the trash icon next to it. Note that deleting a key immediately revokes access for any applications using it.

API Reference

Endpoint

POST /api/chat

Authentication

Include your API key in the Authorization header using Bearer authentication:

Authorization: Bearer YOUR_API_KEY

Request Format

Send a POST request with a JSON body:

{
  "message": "string (required, 1-10000 characters)",
  "agentId": "string (optional)",
  "chatId": "string (optional)"
}

Parameter	Type	Required	Description
message	string	Yes	The question or prompt to send to the AI agent (1-10,000 characters)
agentId	string	No	ID of a specific agent to use for this request. If not provided, the default assistant behavior is used.
chatId	string	No	ID of an existing chat session to continue the conversation. If not provided, a new chat is created.

Response Format

Successful responses return a JSON object:

{
  "chatId": "string",
  "response": "string",
  "messageId": "string"
}

Field	Description
chatId	Unique identifier for the chat session. Use this to continue the conversation in subsequent requests.
response	The AI agent's response to your message
messageId	Unique identifier for the assistant's message

Error Handling

The API uses standard HTTP status codes:

Status Code	Description
200	Success
400	Bad request — invalid parameters or malformed JSON
401	Unauthorized — invalid or missing API key
404	Workspace not found
500	Internal server error

Error responses include a JSON object with details:

{
  "error": "Error message describing the issue",
  "details": "Additional details (optional)"
}

Examples

Basic Request

Send a simple question to your workspace's AI:

curl -X POST https://your-attive-instance.com/api/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are the top deals in our pipeline?"
  }'

Response:

{
  "chatId": "clx1234567890",
  "response": "Based on your current pipeline, here are the top 5 deals by value:\n\n1. Acme Corp - $500,000 (Negotiation stage)\n2. TechStart Inc - $350,000 (Proposal stage)\n...",
  "messageId": "msg_abc123"
}

Using a Specific Agent

Direct your message to a specific agent by ID:

curl -X POST https://your-attive-instance.com/api/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Analyze renewal risk for Enterprise accounts",
    "agentId": "agent_renewal_risk_123"
  }'

Continuing a Conversation

Use the chatId from a previous response to maintain context:

curl -X POST https://your-attive-instance.com/api/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Can you break that down by region?",
    "chatId": "clx1234567890"
  }'

Python Example

import requests

API_KEY = "your_api_key_here"
BASE_URL = "https://your-attive-instance.com"

def send_message(message, agent_id=None, chat_id=None):
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
    
    payload = {"message": message}
    if agent_id:
        payload["agentId"] = agent_id
    if chat_id:
        payload["chatId"] = chat_id
    
    response = requests.post(
        f"{BASE_URL}/api/chat",
        headers=headers,
        json=payload
    )
    
    response.raise_for_status()
    return response.json()

# Start a new conversation
result = send_message("What's our current pipeline value?")
print(f"Response: {result['response']}")

# Continue the conversation
follow_up = send_message(
    "How does that compare to last quarter?",
    chat_id=result['chatId']
)
print(f"Follow-up: {follow_up['response']}")

JavaScript/Node.js Example

const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://your-attive-instance.com';

async function sendMessage(message, agentId, chatId) {
  const response = await fetch(`${BASE_URL}/api/chat`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      message,
      ...(agentId && { agentId }),
      ...(chatId && { chatId }),
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error || 'API request failed');
  }

  return response.json();
}

// Usage
const result = await sendMessage('Summarize recent customer feedback');
console.log('Response:', result.response);

// Continue conversation
const followUp = await sendMessage(
  'What are the main themes?',
  null,
  result.chatId
);
console.log('Follow-up:', followUp.response);

Best Practices

Security

• Never expose API keys in client-side code or public repositories
• Rotate keys periodically and delete unused keys
• Use descriptive names for keys so you can identify their purpose
• Monitor usage by checking the "last used" timestamp

Performance

• Reuse chat sessions when having multi-turn conversations to maintain context
• Keep messages concise but include enough context for accurate responses
• Handle timeouts gracefully — complex queries may take longer to process

Integration Patterns

• Webhook automation: Trigger API calls from your CRM or other systems when specific events occur
• Scheduled reports: Use cron jobs to generate daily or weekly insights
• Chatbot integration: Power Slack bots or other messaging interfaces with Attive's intelligence
• Dashboard embedding: Pull insights into custom dashboards or BI tools

Features

Feature	What it does
Bearer Authentication	Secure API access using workspace-scoped API keys
Agent Selection	Direct messages to specific agents with pre-configured context and instructions
Conversation Continuity	Maintain multi-turn conversations by reusing chat IDs
Full Response Access	Receive complete AI responses with message and chat identifiers
Error Handling	Structured error responses with clear status codes and messages
Usage Tracking	Monitor when API keys are used via the settings interface

Rate Limits

API requests are subject to rate limiting to ensure fair usage. If you encounter rate limit errors (status 429), implement exponential backoff in your retry logic.

Related Features

• Agents — Configure specialized AI assistants to use with the API
• Chat — Understand how chat conversations work
• Integrations — Connect external data sources that power AI responses
• Automations — Build automated workflows that can complement API usage