Skip to content
Last updated

Threads Overview

🔨 In Development — This section is still being developed and may change.
Threads represent persistent conversation contexts that maintain message history across multiple API requests. Freddy's Thread API provides comprehensive management capabilities including creation, modification, message handling, and intelligent context management.

Core Capabilities

Thread Management

  • Create and configure threads with metadata
  • List and filter threads by various criteria
  • Modify thread properties and visibility
  • Delete threads and messages

Message Operations

  • Retrieve paginated message history
  • Edit individual messages
  • Delete specific messages or entire history
  • Track message metadata and edits

AI Features

  • Automatic thread naming based on content
  • Intelligent context mode management
  • Organization and user scoping
  • Assistant integration

Quick Start

Create a Thread

curl https://api.freddy.aitronos.com/v1/threads \
  -H "Authorization: Bearer $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_abc123",
    "assistantId": "asst_xyz789",
    "metadata": {
      "category": "support",
      "priority": "high"
    }
  }'

List User Threads

curl "https://api.freddy.aitronos.com/v1/user/threads?organizationId=org_abc123" \
  -H "Authorization: Bearer $FREDDY_API_KEY"

Get Thread Messages

curl "https://api.freddy.aitronos.com/v1/threads/thread_abc123/messages?limit=50" \
  -H "Authorization: Bearer $FREDDY_API_KEY"

API Endpoints Summary

CategoryEndpointMethodPurpose
Core/v1/threadsPOSTCreate thread
Core/v1/threadsGETList threads
Core/v1/threads/{id}GETGet thread
Core/v1/threads/{id}POSTModify thread
Core/v1/threads/{id}DELETEDelete thread
User/v1/user/threadsGETList user threads
Messages/v1/threads/{id}/messagesGETGet messages
Messages/v1/threads/{id}/messagesDELETEDelete all messages
Content/v1/threads/{id}/metadataPATCHUpdate metadata
Content/v1/threads/{id}/messages/{msgId}PATCHUpdate message
Content/v1/threads/{id}/messages/{msgId}DELETEDelete message
Operations/v1/threads/{id}/renamePUTRename thread
Operations/v1/threads/{id}/generateNamePOSTGenerate AI name

Context Management

Threads support three intelligent context modes that automatically handle conversation history when exceeding neuron capacity limits:

recent (Default) - Keeps most recent messages, optimal for performance and cost

smart - Preserves conversation start and recent context, ideal for complex conversations

full - Maintains complete history, best for short threads requiring full context

Learn more about context modes →

OpenAI Compatibility

Freddy's Thread API is fully compatible with OpenAI's Threads API, with additional enhancements:

Compatible Endpoints:

  • POST /v1/threads - Create thread
  • GET /v1/threads - List threads
  • GET /v1/threads/{id} - Get thread
  • POST /v1/threads/{id} - Modify thread
  • DELETE /v1/threads/{id} - Delete thread

Freddy Enhancements:

  • Organization scoping
  • Assistant integration
  • UI visibility control
  • AI-powered naming
  • Advanced filtering
  • Message editing
  • Metadata updates

Common Use Cases

Customer Support

// Create support thread with metadata
const thread = await fetch('https://api.freddy.aitronos.com/v1/threads', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    organizationId: 'org_abc123',
    metadata: {
      category: 'billing',
      priority: 'high',
      customerId: 'cust_456'
    }
  })
});

Code Assistance

# Use smart context mode for technical conversations
response = requests.post(
    'https://api.freddy.aitronos.com/v1/model/response',
    headers={'Authorization': f'Bearer {api_key}'},
    json={
        'organizationId': 'org_abc123',
        'model': 'gpt-4.1',
        'thread': 'thread_abc123',
        'threadContextMode': 'smart',
        'inputs': [
            {'role': 'user', 'texts': [{'text': 'Continue debugging'}]}
        ]
    }
)

Content Moderation

# Edit inappropriate message
curl -X PATCH "https://api.freddy.aitronos.com/v1/threads/thread_abc/messages/msg_xyz" \
  -H "Authorization: Bearer $FREDDY_API_KEY" \
  -d '{
    "content": "[Message removed by moderator]",
    "metadata": {"moderated": true, "reason": "policy_violation"}
  }'

Best Practices

Performance

  • Use recent context mode for most conversations
  • Implement pagination for message retrieval
  • Cache thread metadata client-side
  • Use streaming for name generation

Organization

  • Add meaningful metadata for filtering
  • Use AI-generated names for better UX
  • Group threads by time periods
  • Archive old threads regularly

Security

  • Always scope threads to organizations
  • Validate user access before operations
  • Audit message modifications
  • Use soft deletes for compliance
Previous page
Next page