AI Assistants API

Overview

The AI Assistants API enables you to build intelligent conversational interfaces powered by Claude AI models. Create custom AI assistants with specialized knowledge, integrate vector-based semantic search for context-aware responses, and manage persistent conversation threads for engaging user experiences. This API forms the foundation for AI-powered personalization and customer experience features in Stack9.

Resource Description

The AI Assistants ecosystem in Stack9 consists of three interconnected components:

• AI Assistants: Configurable AI agents with customized system prompts, model selection, and tool integration capabilities
• Chat Threads: Persistent conversation histories that maintain context across multiple interactions
• Vector Indexes: Semantic search capabilities for knowledge retrieval and RAG (Retrieval Augmented Generation) implementations

Key Capabilities

• Multi-Model Support: Choose between Claude 3 Opus, Sonnet, and Haiku models based on performance and cost requirements
• Custom System Prompts: Define specialized behaviors and knowledge domains for each assistant
• Tool Integration: Enable function calling for dynamic actions and external system integration
• Conversation Memory: Maintain context across sessions with persistent thread management
• Semantic Search: Build knowledge bases with vector embeddings for accurate information retrieval
• Multimodal Support: Process text and image inputs for richer interactions

Authentication

All endpoints require API key authentication:

X-API-Key: your-api-key-here

---

AI Assistant Management

Create AI Assistant

Create a new AI assistant with custom configuration including model selection, system prompt, and parameters.

POST /api/ai/assistants

Parameters

Parameter	Type	Required	Description
name	string	Yes	Short, memorable name for the assistant
description	string	Yes	Description of the assistant's purpose and capabilities
llmConfiguration	object	Yes	Language model configuration object
llmConfiguration.system	string	Yes	System prompt defining the assistant's behavior and context
llmConfiguration.temperature	number	Yes	Randomness in responses (0.0-1.0). Lower for analytical tasks, higher for creative
llmConfiguration.model	string	Yes	Claude model to use (see model options below)
llmConfiguration.max_tokens	number	Yes	Maximum tokens to generate in responses
llmConfiguration.tools	array	No	Function calling tools available to the assistant

Model Options

Model	Description	Use Cases
claude-3-opus-20240229	Most capable model with superior performance	Complex reasoning, creative writing, detailed analysis
claude-3-5-sonnet-20240620	Balanced performance and speed	General purpose, customer support, content generation
claude-3-sonnet-20240229	Previous generation Sonnet model	Legacy applications, cost optimization
claude-3-haiku-20240307	Fastest and most cost-effective	Simple queries, high-volume processing, real-time responses

Tool Configuration

Tools enable the assistant to perform actions and retrieve information dynamically:

Field	Type	Required	Description
name	string	Yes	Unique identifier for the tool
description	string	Yes	Detailed description of tool functionality (3-4 sentences recommended)
input_schema	object	Yes	JSON Schema defining expected parameters
input_schema.type	string	Yes	Must be "object"
input_schema.properties	object	Yes	Parameter definitions
input_schema.required	array	Yes	List of required parameter names

Example Request

curl -X POST \
  https://apis.app.stack9.co/api/ai/assistants \
  -H 'X-API-Key: your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Customer Support Assistant",
    "description": "AI assistant specialized in handling customer inquiries and support tickets",
    "llmConfiguration": {
      "system": "You are a helpful customer support assistant for an e-commerce platform. You have access to order information, product details, and can help with returns and exchanges. Always be polite, professional, and aim to resolve customer issues efficiently.",
      "temperature": 0.3,
      "model": "claude-3-5-sonnet-20240620",
      "max_tokens": 2048,
      "tools": [
        {
          "name": "lookup_order",
          "description": "Retrieves order details by order ID. Use this when customers ask about their order status, tracking information, or order contents. Returns order date, status, items, and tracking number.",
          "input_schema": {
            "type": "object",
            "properties": {
              "order_id": {
                "type": "string",
                "description": "The unique order identifier"
              },
              "include_tracking": {
                "type": "boolean",
                "description": "Whether to include tracking details"
              }
            },
            "required": ["order_id"]
          }
        }
      ]
    }
  }'

Example Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

---

List AI Assistants

Retrieve all AI assistants with pagination support.

GET /api/ai/assistants

Query Parameters

Parameter	Type	Required	Description
page	number	No	Page number for pagination (default: 1)
limit	number	No	Number of results per page (default: 20)

Example Request

curl -X GET \
  'https://apis.app.stack9.co/api/ai/assistants?page=1&limit=10' \
  -H 'X-API-Key: your-api-key-here'

Example Response

{
  "results": [
    {
      "version": 1,
      "created_at": "2024-01-15T10:30:00.123Z",
      "updated_at": null,
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Customer Support Assistant",
      "description": "AI assistant specialized in handling customer inquiries and support tickets"
    },
    {
      "version": 2,
      "created_at": "2024-01-14T08:15:00.456Z",
      "updated_at": "2024-01-15T09:20:00.789Z",
      "id": "660f9500-f39c-52e5-b827-557766550001",
      "name": "Product Recommendation Engine",
      "description": "Personalized product recommendations based on user preferences and behavior"
    }
  ],
  "total": 15,
  "totalPages": 2
}

---

Get AI Assistant

Retrieve detailed information about a specific AI assistant including full configuration.

GET /api/ai/assistants/{id}

Path Parameters

Parameter	Type	Required	Description
id	uuid	Yes	The unique assistant identifier

Example Request

curl -X GET \
  https://apis.app.stack9.co/api/ai/assistants/550e8400-e29b-41d4-a716-446655440000 \
  -H 'X-API-Key: your-api-key-here'

Example Response

{
  "version": 3,
  "created_at": "2024-01-15T10:30:00.123Z",
  "updated_at": "2024-01-16T14:45:00.789Z",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Customer Support Assistant",
  "description": "AI assistant specialized in handling customer inquiries and support tickets",
  "llmConfiguration": {
    "system": "You are a helpful customer support assistant for an e-commerce platform...",
    "temperature": 0.3,
    "model": "claude-3-5-sonnet-20240620",
    "max_tokens": 2048,
    "tools": [
      {
        "name": "lookup_order",
        "description": "Retrieves order details by order ID...",
        "input_schema": {
          "type": "object",
          "properties": {
            "order_id": {
              "type": "string",
              "description": "The unique order identifier"
            }
          },
          "required": ["order_id"]
        }
      }
    ]
  }
}

---

Update AI Assistant

Update an existing AI assistant's configuration, including system prompt, model, or tools.

PUT /api/ai/assistants/{id}

Path Parameters

Parameter	Type	Required	Description
id	uuid	Yes	The unique assistant identifier

Request Body

Same as Create AI Assistant parameters.

Example Request

curl -X PUT \
  https://apis.app.stack9.co/api/ai/assistants/550e8400-e29b-41d4-a716-446655440000 \
  -H 'X-API-Key: your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Enhanced Support Assistant",
    "description": "Upgraded customer support assistant with advanced capabilities",
    "llmConfiguration": {
      "system": "You are an expert customer support assistant...",
      "temperature": 0.4,
      "model": "claude-3-opus-20240229",
      "max_tokens": 4096
    }
  }'

Example Response

{
  "success": true
}

---

Chat Thread Management

Create Chat Thread

Initialize a new conversation thread with an AI assistant.

POST /api/ai/threads

Parameters

Parameter	Type	Required	Description
version	number	Yes	Version number for optimistic locking
created_at	datetime	Yes	ISO 8601 timestamp of creation
assistant_id	uuid	Yes	ID of the AI assistant to use
user_id	string	Yes	Unique user identifier (alphanumeric, hyphens, underscores)
messages	array	Yes	Initial messages in the conversation

Message Structure

Messages support multiple content types:

Text Messages

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "Hello, I need help with my order"
    }
  ]
}

Image Messages

{
  "role": "user",
  "content": [
    {
      "type": "image",
      "source": {
        "type": "base64",
        "media_type": "image/png",
        "data": "base64_encoded_image_data"
      }
    }
  ]
}

Tool Use Messages

{
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "tool_use_123",
      "name": "lookup_order",
      "input": {
        "order_id": "ORD-2024-001234"
      }
    }
  ]
}

Tool Result Messages

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "tool_use_123",
      "content": [
        {
          "type": "text",
          "text": "Order found: Status - Shipped"
        }
      ],
      "is_error": false
    }
  ]
}

Example Request

curl -X POST \
  https://apis.app.stack9.co/api/ai/threads \
  -H 'X-API-Key: your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "version": 1,
    "created_at": "2024-01-20T10:00:00.000Z",
    "assistant_id": "550e8400-e29b-41d4-a716-446655440000",
    "user_id": "user_12345",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "I need to check on my recent order"
          }
        ]
      }
    ]
  }'

Example Response

{
  "id": "thread_abc123def456"
}

---

List Chat Threads

Retrieve all chat threads for a specific user.

GET /api/ai/threads

Query Parameters

Parameter	Type	Required	Description
user_id	string	Yes	Filter threads by user identifier
page	number	No	Page number for pagination
limit	number	No	Results per page

Example Request

curl -X GET \
  'https://apis.app.stack9.co/api/ai/threads?user_id=user_12345&page=1&limit=10' \
  -H 'X-API-Key: your-api-key-here'

Example Response

{
  "results": [
    {
      "version": 5,
      "created_at": "2024-01-20T10:00:00.000Z",
      "updated_at": "2024-01-20T10:15:00.000Z",
      "id": "thread_abc123def456",
      "assistant_id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "user_12345",
      "name": "Order inquiry - January 20"
    }
  ],
  "total": 25,
  "totalPages": 3
}

---

Get Chat Thread

Retrieve a complete chat thread including all messages.

GET /api/ai/threads/{id}

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Unique thread identifier

Example Request

curl -X GET \
  https://apis.app.stack9.co/api/ai/threads/thread_abc123def456 \
  -H 'X-API-Key: your-api-key-here'

Example Response

{
  "version": 5,
  "created_at": "2024-01-20T10:00:00.000Z",
  "updated_at": "2024-01-20T10:15:00.000Z",
  "id": "thread_abc123def456",
  "assistant_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "user_12345",
  "name": "Order inquiry - January 20",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "I need to check on my recent order"
        }
      ]
    },
    {
      "role": "assistant",
      "content": [
        {
          "type": "text",
          "text": "I'd be happy to help you check on your order. Could you please provide your order number?"
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "It's ORD-2024-001234"
        }
      ]
    },
    {
      "role": "assistant",
      "content": [
        {
          "type": "tool_use",
          "id": "tool_use_789",
          "name": "lookup_order",
          "input": {
            "order_id": "ORD-2024-001234"
          }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "tool_use_789",
          "content": [
            {
              "type": "text",
              "text": "{\"status\": \"shipped\", \"tracking\": \"1Z999AA10123456784\", \"expected_delivery\": \"2024-01-22\"}"
            }
          ],
          "is_error": false
        }
      ]
    },
    {
      "role": "assistant",
      "content": [
        {
          "type": "text",
          "text": "Great news! Your order ORD-2024-001234 has been shipped. Here are the details:\n\n- Status: Shipped\n- Tracking Number: 1Z999AA10123456784\n- Expected Delivery: January 22, 2024\n\nYou can track your package using the tracking number on the carrier's website."
        }
      ]
    }
  ]
}

---

Vector Index Operations

Create Vector Index

Create a new vector index for storing and searching embeddings.

POST /api/ai/indexes

Parameters

Parameter	Type	Required	Description
name	string	Yes	Index name (lowercase, numbers, hyphens only)
contentsDescription	string	Yes	Description of content stored in the index (used by LLM for relevance)
metadataDefinition	array	Yes	Schema for metadata fields

Metadata Field Definition

Field	Type	Required	Description
fieldName	string	Yes	Name of the metadata field
fieldType	string	Yes	Data type: "string", "number", "boolean", "array"

Example Request

curl -X POST \
  https://apis.app.stack9.co/api/ai/indexes \
  -H 'X-API-Key: your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "product-knowledge-base",
    "contentsDescription": "Product documentation, specifications, and user manuals for customer support queries",
    "metadataDefinition": [
      {
        "fieldName": "category",
        "fieldType": "string"
      },
      {
        "fieldName": "product_id",
        "fieldType": "string"
      },
      {
        "fieldName": "version",
        "fieldType": "number"
      },
      {
        "fieldName": "tags",
        "fieldType": "array"
      },
      {
        "fieldName": "is_public",
        "fieldType": "boolean"
      }
    ]
  }'

Example Response

{
  "name": "product-knowledge-base"
}

---

Upsert Vector Data

Add or update documents in a vector index. The API automatically converts text to embeddings.

POST /api/ai/indexes/{name}/upsert

Path Parameters

Parameter	Type	Required	Description
name	string	Yes	Name of the vector index

Request Body

Parameter	Type	Required	Description
data	array	Yes	Array of documents to upsert
data[].id	string	Yes	Unique document identifier
data[].input	string	Yes	Text content to be embedded
data[].metadata	object	Yes	Metadata for filtering and context

Example Request

curl -X POST \
  https://apis.app.stack9.co/api/ai/indexes/product-knowledge-base/upsert \
  -H 'X-API-Key: your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": [
      {
        "id": "doc_001",
        "input": "The XR-500 Smart Router features dual-band Wi-Fi 6 technology with speeds up to 5.4 Gbps. It includes 4 Gigabit Ethernet ports, USB 3.0 connectivity, and advanced security features including WPA3 encryption and automatic firmware updates.",
        "metadata": {
          "category": "networking",
          "product_id": "XR-500",
          "version": 2.1,
          "tags": ["router", "wifi6", "networking", "smart-home"],
          "is_public": true
        }
      },
      {
        "id": "doc_002",
        "input": "Troubleshooting connection issues: 1) Power cycle the router by unplugging for 30 seconds. 2) Check all cable connections. 3) Verify ISP service status. 4) Reset to factory defaults if needed by holding the reset button for 10 seconds.",
        "metadata": {
          "category": "support",
          "product_id": "XR-500",
          "version": 2.1,
          "tags": ["troubleshooting", "connection", "reset"],
          "is_public": true
        }
      }
    ]
  }'

Example Response

{
  "success": true
}

---

Engage Conversation

Create a temporary conversation token for frontend applications to continue conversations securely.

POST /api/ai/engage-conversation

Parameters

Parameter	Type	Required	Description
key	string	Yes	Unique key to identify the conversation context
payload	object	Yes	Conversation state and context data

Example Request

curl -X POST \
  https://apis.app.stack9.co/api/ai/engage-conversation \
  -H 'X-API-Key: your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "session_12345",
    "payload": {
      "thread_id": "thread_abc123def456",
      "assistant_id": "550e8400-e29b-41d4-a716-446655440000",
      "user_context": {
        "user_id": "user_12345",
        "preferences": {
          "language": "en",
          "timezone": "America/New_York"
        }
      }
    }
  }'

Example Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

---

Integration Patterns

Building a Conversational Interface

Implement a chat interface with conversation history:

// Initialize assistant and thread
const assistantId = await createAssistant({
  name: "Support Bot",
  llmConfiguration: {
    model: "claude-3-5-sonnet-20240620",
    temperature: 0.3,
    max_tokens: 2048
  }
});

const threadId = await createThread({
  assistant_id: assistantId,
  user_id: currentUser.id,
  messages: []
});

// Send user message and get response
async function sendMessage(text) {
  // Add user message to thread
  const updatedThread = await addMessage(threadId, {
    role: "user",
    content: [{ type: "text", text }]
  });

  // Get AI response
  const response = await getAssistantResponse(threadId);

  // Update UI with response
  displayMessage(response);
}

Implementing RAG with Vector Search

Create a knowledge-augmented assistant:

// 1. Create vector index for knowledge base
const indexName = await createVectorIndex({
  name: "company-knowledge",
  contentsDescription: "Company documentation and FAQs",
  metadataDefinition: [
    { fieldName: "source", fieldType: "string" },
    { fieldName: "section", fieldType: "string" }
  ]
});

// 2. Populate index with documents
await upsertDocuments(indexName, documents.map(doc => ({
  id: doc.id,
  input: doc.content,
  metadata: {
    source: doc.source,
    section: doc.section
  }
})));

// 3. Create assistant with RAG tool
const assistant = await createAssistant({
  name: "Knowledge Assistant",
  llmConfiguration: {
    tools: [{
      name: "search_knowledge",
      description: "Search company knowledge base for relevant information",
      input_schema: {
        type: "object",
        properties: {
          query: {
            type: "string",
            description: "Search query"
          }
        },
        required: ["query"]
      }
    }]
  }
});

Multi-Model Strategy

Optimize for performance and cost:

// Use Haiku for simple queries
const quickAssistant = {
  model: "claude-3-haiku-20240307",
  temperature: 0.2,
  max_tokens: 512
};

// Use Sonnet for standard interactions
const standardAssistant = {
  model: "claude-3-5-sonnet-20240620",
  temperature: 0.5,
  max_tokens: 2048
};

// Use Opus for complex reasoning
const advancedAssistant = {
  model: "claude-3-opus-20240229",
  temperature: 0.7,
  max_tokens: 4096
};

// Route based on query complexity
function selectModel(query) {
  if (isSimpleQuery(query)) return quickAssistant;
  if (requiresReasoning(query)) return advancedAssistant;
  return standardAssistant;
}

---

Best Practices

System Prompt Engineering

Create effective system prompts:

1. Define Role Clearly: Start with who the assistant is and their primary function
2. Specify Knowledge Domain: Clearly state what the assistant knows and doesn't know
3. Set Behavioral Guidelines: Define tone, style, and interaction patterns
4. Include Constraints: Specify what the assistant should and shouldn't do
5. Provide Examples: Include sample interactions when appropriate

Example:

You are a professional customer service representative for TechCorp, specializing in technical support for our product line. You have extensive knowledge of our products, troubleshooting procedures, and warranty policies.

Guidelines:
- Always maintain a helpful and professional tone
- If you don't know something, admit it and offer to escalate
- Prioritize customer satisfaction while following company policies
- Use simple language and avoid technical jargon unless necessary
- Always verify order numbers and customer information before providing specific details

You have access to order lookup and product information tools. Use these when customers ask about specific orders or products.

Temperature Selection Guide

Choose the right temperature for your use case:

Temperature	Use Cases	Characteristics
0.0 - 0.2	Factual queries, data extraction, classifications	Highly deterministic, minimal variation
0.3 - 0.5	Customer support, Q&A, information retrieval	Balanced consistency and naturalness
0.6 - 0.8	Content creation, brainstorming, creative writing	More variety and creativity
0.9 - 1.0	Artistic generation, exploration, ideation	Maximum creativity and unpredictability

Vector Index Optimization

Optimize semantic search performance:

1. Chunk Size: Keep text chunks between 200-800 tokens for optimal retrieval
2. Metadata Design: Include relevant filtering fields without over-complicating
3. Content Quality: Ensure indexed content is clean and well-structured
4. Regular Updates: Keep indexes current with latest information
5. Relevance Testing: Regularly test and tune search results

Conversation Thread Management

Maintain effective conversation context:

1. Thread Lifecycle: Create new threads for distinct conversation topics
2. Context Window: Monitor token usage and summarize long conversations
3. User Association: Always associate threads with specific users
4. Message History: Preserve important context while pruning redundant information
5. Thread Naming: Auto-generate descriptive names for easy identification

Cost Optimization Strategies

Manage API usage efficiently:

1. Model Selection:

   • Use Haiku for high-volume, simple queries
   • Reserve Opus for complex reasoning tasks
   • Default to Sonnet for balanced performance

2. Token Management:

   • Set appropriate max_tokens limits
   • Implement response streaming for long outputs
   • Cache common responses when possible

3. Batch Processing:

   • Group similar queries for bulk processing
   • Use vector search to find existing answers before generating new ones

4. Monitoring:

   • Track usage by assistant and model
   • Set up alerts for unusual activity
   • Review and optimize system prompts regularly

---

Error Handling

Common Error Responses

400 Bad Request

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid model specified",
    "details": {
      "field": "llmConfiguration.model",
      "value": "invalid-model"
    }
  }
}

401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

404 Not Found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Assistant not found",
    "details": {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

429 Rate Limited

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests",
    "retry_after": 60
  }
}

500 Internal Server Error

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred",
    "request_id": "req_123456"
  }
}

Error Recovery Strategies

1. Implement Exponential Backoff: For rate limit errors, wait progressively longer between retries
2. Fallback Models: If primary model fails, try with a simpler model
3. Cache Responses: Store successful responses to handle temporary failures
4. Graceful Degradation: Provide basic functionality when AI features are unavailable
5. User Feedback: Always inform users of issues and provide alternatives

---

Performance Considerations

Response Time Optimization

• Haiku: ~500ms average response time
• Sonnet: ~1-2 seconds average response time
• Opus: ~3-5 seconds average response time

Consider implementing:

• Response streaming for better perceived performance
• Typing indicators during generation
• Partial response display as content generates

Scaling Guidelines

1. Concurrent Requests: Each assistant can handle multiple concurrent conversations
2. Thread Limits: No hard limit on threads per user, but consider archiving old threads
3. Vector Index Size: Indexes can handle millions of documents with proper configuration
4. Rate Limits: Default 100 requests per minute, contact support for higher limits

---

Security Considerations

Data Privacy

1. PII Handling: Avoid storing sensitive personal information in prompts or vector indexes
2. Thread Isolation: Threads are isolated per user and cannot be accessed cross-user
3. Assistant Segregation: Assistants operate in isolation and cannot access other assistants' data

Access Control

1. API Key Management: Rotate API keys regularly
2. User Authentication: Always verify user identity before granting thread access
3. Tool Permissions: Carefully design tool schemas to prevent unauthorized actions
4. Content Filtering: Implement content moderation for user inputs

Compliance

1. Data Retention: Configure appropriate retention policies for threads and indexes
2. Audit Logging: All API calls are logged for security and compliance
3. GDPR Compliance: Support for data export and deletion requests
4. Regional Data: Specify data residency requirements if applicable

---

Migration Guide

Upgrading Models

When new model versions are released:

1. Test Compatibility: Validate prompts work with new models in development
2. Gradual Rollout: Update assistants incrementally
3. Monitor Performance: Track metrics during transition
4. Rollback Plan: Keep previous configuration for quick rollback

Vector Index Migration

For index schema changes:

1. Create New Index: Build new index with updated schema
2. Parallel Indexing: Populate new index while old remains active
3. Validate Results: Compare search results between indexes
4. Switch Traffic: Update assistants to use new index
5. Archive Old Index: Keep for rollback, then remove after validation period