POST /api/threads

​

Authentication

sub | ClaimTypes.NameIdentifier → User UUID (required)
email | ClaimTypes.Email → User email
full_name | name | ClaimTypes.Name → Display name

​

Request Body

​

Response

curl -X POST 'http://localhost:5079/api/threads' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"title": "New Conversation"}'

const response = await fetch('http://localhost:5079/api/threads', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${jwt}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'New Conversation'
  })
});

const thread = await response.json();

import requests

response = requests.post(
    'http://localhost:5079/api/threads',
    headers={
        'Authorization': f'Bearer {jwt}',
        'Content-Type': 'application/json'
    },
    json={'title': 'New Conversation'}
)

thread = response.json()

{
  "thread_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "user_id": "user-uuid-here",
  "title": "New Conversation",
  "visibility": "private",
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:30:00.000Z"
}

{
  "error": "User ID claim missing"
}

{
  "success": false,
  "error": "Database constraint violation",
  "code": "THREAD_CREATE_ERROR"
}

​

Side Effects

1. users table UPSERT (Lines 83-92):
   await _userSyncService.EnsureUserExistsAsync(userId.Value, email, name);
   
   • Timing: Happens before thread creation
   • Purpose: Ensures users table row exists (FK constraint requirement)
   • Idempotent: UPSERT operation
   • Failure: Would bubble to 500 error
2. threads table INSERT (Line 94):
   await _threadsService.CreateThreadAsync(request?.Title, userId);
   
   • INSERT new thread row
   • Sets user_id = userId from JWT
   • Sets visibility to default value (service-defined)
   • Generates thread_id UUID
   • Sets created_at and updated_at timestamps

​

Permissions

• Any authenticated user

• Thread user_id set to authenticated user’s UUID
• Cannot create threads for other users

​

Validation

• null allowed
• Empty string allowed
• Whitespace-only allowed
• No length constraints enforced by controller

• MUST be valid GUID from JWT
• MUST exist in JWT claims
• Returns 401 if missing or invalid

​

Authorization

• Authenticated user can create unlimited threads
• No quota enforcement by controller

• Set by service (not specified in controller)
• Assumed default: "private"

​

Edge Cases

1. Null title: Allowed, service may generate default (Line 94)
2. Empty title: Allowed
3. Very long title: Not validated by controller (database column limit may apply)
4. Duplicate title: Allowed (titles not unique)
5. User doesn’t exist in database: Synced before creation (Lines 92)
6. User sync fails: 500 error (blocks thread creation)

​

Error Conditions

catch (Exception ex) {
    return StatusCode(500, new { error = ex.Message, code = "THREAD_CREATE_ERROR" });
}

• All exceptions return 500
• Error message exposed to client

​

Behavioral Guarantees

• User sync and thread creation not wrapped in transaction
• User sync failure blocks thread creation
• Thread creation failure leaves user synced (not rolled back)

• Each call creates new thread (even with same title)
• No deduplication logic

​

Database Schema Dependencies