# Threads Overview

div
strong
🔨 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


```bash
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


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

### Get Thread Messages


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

## API Endpoints Summary

| Category | Endpoint | Method | Purpose |
|  --- | --- | --- | --- |
| **Core** | `/v1/threads` | POST | Create thread |
| **Core** | `/v1/threads` | GET | List threads |
| **Core** | `/v1/threads/{id}` | GET | Get thread |
| **Core** | `/v1/threads/{id}` | POST | Modify thread |
| **Core** | `/v1/threads/{id}` | DELETE | Delete thread |
| **User** | `/v1/user/threads` | GET | List user threads |
| **Messages** | `/v1/threads/{id}/messages` | GET | Get messages |
| **Messages** | `/v1/threads/{id}/messages` | DELETE | Delete all messages |
| **Content** | `/v1/threads/{id}/metadata` | PATCH | Update metadata |
| **Content** | `/v1/threads/{id}/messages/{msgId}` | PATCH | Update message |
| **Content** | `/v1/threads/{id}/messages/{msgId}` | DELETE | Delete message |
| **Operations** | `/v1/threads/{id}/rename` | PUT | Rename thread |
| **Operations** | `/v1/threads/{id}/generateName` | POST | Generate 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 →](/docs/documentation/core-concepts/thread-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


```javascript
// 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


```python
# 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


```bash
# 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


## Related Resources

- [Create Thread](/docs/api-reference/threads/create)
- [List Threads](/docs/api-reference/threads/list)
- [Get Thread Messages](/docs/api-reference/threads/messages)
- [Thread Context Modes](/docs/documentation/core-concepts/thread-context-modes)
- [Best Practices](/docs/documentation/best-practices)