# Create thread

div
strong
🔨 In Development
 — This section is still being developed and may change.


Create a new conversation thread with optional metadata, assistant configuration, and visibility settings.

Create a new conversation thread with optional metadata, assistant configuration, and visibility settings. All fields are optional, allowing you to create an empty thread and configure it later.

#### Request Body

**`messages`** array optional

Array of initial messages to add to the thread. Each message must have a `role` and `content`.

details
summary
Show message structure
**`role`** string required

The role of the message. One of `user`, `assistant`, or `system`.

**`content`** string required

The text content of the message.

Example: `[{"role": "user", "content": "Hello, I need help with billing"}]`

**`metadata`** object optional

Custom key-value pairs for attaching structured information to the thread. Maximum 16 key-value pairs. Keys must be ≤64 characters, values ≤512 characters.

Example: `{"category": "support", "priority": "high", "tags": ["billing", "urgent"]}`

**`assistantId`** string optional

ID of the assistant to bind to this thread. When provided, the assistant's configuration will be applied to all responses in this thread.

**`visibleInUi`** boolean optional · Defaults to `true`

Whether this thread should be visible in the user interface. Requires Bearer token authentication (not API key).

**`title`** string optional

Display name for the thread. Maximum 200 characters. If not provided, can be generated later using the [Generate AI Name](/docs/api-reference/threads/generate-name) endpoint.

**`organizationId`** string required

Organization ID for scoping. All API requests must be scoped to an organization for billing, access control, and resource management. Find your organization ID in [Freddy Hub → Settings → Organization](https://freddy-hub.aitronos.com/settings/organization).

Minimal

```bash
curl https://api.freddy.aitronos.com/v1/threads \
  -H "Authorization: Bearer $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```


```python
import requests

response = requests.post(
    "https://api.freddy.aitronos.com/v1/threads",
    headers={"Authorization": f"Bearer {api_key}"},
    json={}
)

thread = response.json()
print(f"Created thread: {thread['id']}")
```


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/threads', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({})
});

const thread = await response.json();
console.log(`Created thread: ${thread.id}`);
```

With Messages

```bash
curl https://api.freddy.aitronos.com/v1/threads \
  -H "Authorization: Bearer $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "ORG_123",
    "messages": [
      {
        "role": "user",
        "content": "Hello, I need help with my billing"
      }
    ],
    "title": "Billing Support Request"
  }'
```


```python
import requests

response = requests.post(
    "https://api.freddy.aitronos.com/v1/threads",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "organizationId": "ORG_123",
        "messages": [
            {
                "role": "user",
                "content": "Hello, I need help with my billing"
            }
        ],
        "title": "Billing Support Request"
    }
)

thread = response.json()
print(f"Created thread with {len(thread.get('messages', []))} messages")
```


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/threads', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    organizationId: 'ORG_123',
    messages: [
      {
        role: 'user',
        content: 'Hello, I need help with my billing'
      }
    ],
    title: 'Billing Support Request'
  })
});

const thread = await response.json();
console.log(`Created thread with ${thread.messages?.length || 0} messages`);
```

With Assistant

```bash
curl https://api.freddy.aitronos.com/v1/threads \
  -H "Authorization: Bearer $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "ORG_123",
    "assistantId": "asst_support_agent",
    "metadata": {
      "category": "support",
      "priority": "high",
      "tags": ["billing", "urgent"]
    },
    "title": "Customer Support Query"
  }'
```


```python
import requests

response = requests.post(
    "https://api.freddy.aitronos.com/v1/threads",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "organizationId": "ORG_123",
        "assistantId": "asst_support_agent",
        "metadata": {
            "category": "support",
            "priority": "high",
            "tags": ["billing", "urgent"]
        },
        "title": "Customer Support Query"
    }
)

thread = response.json()
print(f"Created thread with assistant: {thread['assistant_id']}")
```


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/threads', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    organizationId: 'ORG_123',
    assistantId: 'asst_support_agent',
    metadata: {
      category: 'support',
      priority: 'high',
      tags: ['billing', 'urgent']
    },
    title: 'Customer Support Query'
  })
});

const thread = await response.json();
console.log(`Created thread with assistant: ${thread.assistant_id}`);
```

## Response

201 Created

```json
{
  "id": "thread_abc123",
  "object": "thread",
  "createdAt": 1741476542,
  "updatedAt": 1741476600,
  "metadata": {
    "category": "support",
    "priority": "high",
    "tags": ["billing", "urgent"]
  },
  "assistantId": "asst_support_agent",
  "organizationId": "ORG_123",
  "userId": "uid_user123",
  "title": "Customer Support Query",
  "visibleInUi": true,
  "messageCount": 0,
  "status": "inactive"
}
```

Errors

```json 400 Bad Request
{
  "error": {
    "message": "Invalid request parameters",
    "type": "invalid_request_error",
    "code": "invalid_parameters"
  }
}
```


```json 401 Unauthorized
{
  "error": {
    "message": "Authentication required",
    "type": "authentication_error",
    "code": "missing_authentication"
  }
}
```


```json 422 Validation Error
{
  "error": {
    "message": "Title cannot be empty",
    "type": "validation_error",
    "code": "invalid_title",
    "param": "title"
  }
}
```

## Related Resources

- [Threads Overview](/docs/documentation/core-concepts/threads-overview)
- [List Threads](/docs/api-reference/threads/list)
- [Generate AI Name](/docs/api-reference/threads/generate-name)
- [Thread Context Modes](/docs/documentation/core-concepts/thread-context-modes)