# Create assistant

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


**POST** `/v1/assistants` - Create a new AI assistant with custom configuration, tools, and behavior rules.

#### Request Body

**`name`** string required

The name of the assistant. Must be unique within the organization.

**`organization_id`** string required

The unique identifier of the organization to create the assistant in.

**`description`** string optional

A brief description of the assistant's purpose and capabilities.

**`model`** string optional · Defaults to `gpt-4o`

The AI model to use for this assistant. [View available models →](/docs/documentation/getting-started/models)

**`allowed_model_providers`** array optional

Array of model provider identifiers that this assistant is allowed to use. When specified, the assistant will only be able to use models from these providers. Example: `["openai", "anthropic", "aitronos"]`.

**`instructions`** string optional

System instructions that define the assistant's behavior and personality.

**`tools`** array optional

Array of tools the assistant can use. [Learn more about tools →](/docs/documentation/core-concepts/function-calling)

**`vector_store_ids`** array optional

Array of vector store IDs for file search capabilities.

**`access_mode`** string optional · Defaults to `private`

Access control for the assistant. One of `public`, `private`, `organization`.

**`temperature`** number optional · Defaults to `0.7`

Controls randomness in responses (0.0 to 2.0).

**`max_output_synapses`** integer optional · Defaults to `4000`

Maximum output length in synapses (neurons). [Learn more](/docs/documentation/core-concepts/synapses-and-neurons)

**`avatar_id`** string optional

Predefined avatar identifier from the Aitronos avatar library. [View available avatars →](/docs/api-reference/avatars/list)

**`avatar`** string optional

Custom avatar URL. Used when you want to provide your own avatar image instead of using a predefined one.

**`tool_configurations`** object optional

Detailed configuration for built-in system tools. Use this for fine-grained control over tool behavior.

details
summary
Show tool configurations
**`systemTools`** object

Built-in Aitronos tools configuration.

**`webSearch`** object · `mode`: `on`/`off`/`auto`, `sources`: boolean

**`codeInterpreter`** object · `mode`: `on`/`off`/`auto`, `outputs`: boolean

**`fileSearch`** object · `mode`: `on`/`off`/`auto`, `results`: boolean

**`computerUsePreview`** object · `mode`: `on`/`off`/`auto`, `imageUrl`: boolean

**`imageGeneration`** object · `mode`: `on`/`off`/`auto`, `provider`: `openai`/`clipdrop`

**`fileRetrieval`** object · `mode`: `on`/`off`/`auto`

**`mcpTools`** array

Enable the assistant to utilize external tools through Model Context Protocol (MCP) server integrations. [Learn more about MCP](/docs/documentation/core-concepts/mcp-tools)

details
summary
Show properties
**`serverLabel`** string required

Identifier label for the MCP server, used for recognition during tool invocations.

**`type`** string required

The type of the MCP tool. Always `mcp`.

**`allowedTools`** array or object optional

Specify permitted tools either as a string array or filter configuration object.

details
summary
Show possible types
**MCP allowed tools** array

String array containing names of permitted tools.

**MCP tool filter** object

Filter configuration defining which tools are permitted.

details
summary
Show properties
**`readOnly`** boolean optional

Determines if a tool performs data modifications or operates in read-only mode. Matches MCP servers annotated with `readOnlyHint`.

**`toolNames`** array optional

Array of permitted tool identifiers.

**`authorization`** string optional

OAuth bearer token for authenticating with remote MCP servers (custom URLs or service connectors). Your application manages the OAuth flow and supplies the token.

**`connectorId`** string optional

Service connector identifier for pre-integrated platforms. Either `serverUrl` or `connectorId` is required.

Examples: `connector_googledrive`, `connector_gmail`

[View all supported connectors →](/docs/documentation/tools/mcp-connectors)

**`headers`** object optional

Custom HTTP headers transmitted to the MCP server for authentication or additional metadata.

**`requireApproval`** object or string optional · Defaults to `always`

Define approval requirements for MCP server tools.

details
summary
Show possible types
**MCP tool approval filter** object

Configure tool-specific approval policies using `always`, `never`, or conditional filter rules.

details
summary
Show properties
**`always`** object optional

Filter rules defining tools that always require approval.

details
summary
Show properties
**`readOnly`** boolean optional

Indicates whether or not a tool modifies data or is read-only. If an MCP server is annotated with `readOnlyHint`, it will match this filter.

**`toolNames`** array optional

List of allowed tool names.

**`never`** object optional

Filter rules defining tools that never require approval.

details
summary
Show properties
**`readOnly`** boolean optional

Indicates whether or not a tool modifies data or is read-only. If an MCP server is annotated with `readOnlyHint`, it will match this filter.

**`toolNames`** array optional

List of allowed tool names.

**MCP tool approval setting** string

Universal approval policy for all tools. Set to `always` to mandate approval for every tool, or `never` to bypass all approval requirements.

**`serverDescription`** string optional

Descriptive text providing additional context about the MCP server's purpose.

**`serverUrl`** string optional

HTTP endpoint for the MCP server. Either `serverUrl` or `connectorId` is required.

**`streamlineTools`** array

Array of Streamline/Flow-Plate automation IDs.

**`system_message`** array optional

Pre-configured system messages or input examples. An array of input message objects with texts, images, or files.

**`context_strategy`** string optional · Defaults to `auto`

Sets the overall thread context management strategy. Values: `full`, `off`, `auto`, `saver`.

**`max_tool_calls`** integer optional · Defaults to `10`

Maximum number of built-in tool calls allowed per response.

**`parallel_tool_calls`** boolean optional · Defaults to `false`

Whether the assistant can execute multiple tool calls simultaneously.

**`reasoning`** object optional

Configuration for reasoning models (o3-preview, o3-mini, gpt-5). Only applicable when using reasoning-capable models.

details
summary
Show reasoning properties
**`effort`** string · Defaults to `medium`

Computational effort for reasoning. Values: `minimal`, `low`, `medium`, `high`.

**`summary`** string · Defaults to `auto`

Request reasoning summaries. Values: `auto`, `concise`, `detailed`.

**`service_tier`** string optional · Defaults to `auto`

Processing tier for requests. Values: `auto`, `default`, `flex`, `priority`.

**`store`** boolean optional · Defaults to `false`

Whether to store generated responses for later retrieval via API.

**`text_configuration`** object optional

Configuration for text response formatting and structured outputs. [Learn more](/docs/documentation/core-concepts/structured-output)

**`top_logprobs`** integer optional

Number of alternative tokens to return at each position with log probabilities (0-20).

**`top_p`** number optional · Defaults to `1.0`

Nucleus sampling probability mass (0.0-1.0). Alternative to temperature for controlling randomness.

**`truncation`** string optional · Defaults to `auto`

Strategy for handling inputs exceeding context window. Values: `auto` (truncate from beginning), `disabled` (fail with error).

**`metadata`** object optional

Custom key-value pairs for organizing and filtering assistants. Max 16 keys, each key ≤ 64 chars, each value ≤ 512 chars.

Minimal

```bash
curl https://api.freddy.aitronos.com/v1/assistants \
  -H "Authorization: Bearer $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Assistant",
    "organization_id": "org_abc123"
  }'
```


```python
import requests

response = requests.post(
    "https://api.freddy.aitronos.com/v1/assistants",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "name": "My Assistant",
        "organization_id": "org_abc123"
    }
)

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


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

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

With Tools

```bash
curl https://api.freddy.aitronos.com/v1/assistants \
  -H "Authorization: Bearer $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research Assistant",
    "organization_id": "org_abc123",
    "description": "AI assistant for research and analysis",
    "model": "gpt-4o",
    "instructions": "You are a research assistant that helps find and analyze information.",
    "tools": [
      {
        "type": "web_search",
        "searchContextSize": "large"
      },
      {
        "type": "code_interpreter"
      }
    ],
    "temperature": 0.3
  }'
```


```python
import requests

response = requests.post(
    "https://api.freddy.aitronos.com/v1/assistants",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Research Assistant",
        "organization_id": "org_abc123",
        "description": "AI assistant for research and analysis",
        "model": "gpt-4o",
        "instructions": "You are a research assistant that helps find and analyze information.",
        "tools": [
            {
                "type": "web_search",
                "searchContextSize": "large"
            },
            {
                "type": "code_interpreter"
            }
        ],
        "temperature": 0.3
    }
)

assistant = response.json()
```


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/assistants', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Research Assistant',
    organization_id: 'org_abc123',
    description: 'AI assistant for research and analysis',
    model: 'gpt-4o',
    instructions: 'You are a research assistant that helps find and analyze information.',
    tools: [
      {
        type: 'web_search',
        searchContextSize: 'large'
      },
      {
        type: 'code_interpreter'
      }
    ],
    temperature: 0.3
  })
});

const assistant = await response.json();
```

## Response

**Returns**

The created [Assistant object](/docs/api-reference/objects/assistant-object) with all configuration details.

201 Created

```json
{
  "id": "asst_abc123",
  "name": "Research Assistant",
  "description": "AI assistant for research and analysis",
  "model": "gpt-4o",
  "instructions": "You are a research assistant that helps find and analyze information.",
  "tools": [
    {
      "type": "web_search",
      "searchContextSize": "large"
    },
    {
      "type": "code_interpreter"
    }
  ],
  "access_mode": "private",
  "is_active": true,
  "temperature": 0.3,
  "max_output_synapses": 4000,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "organization_id": "org_abc123",
  "created_by": "user_abc123"
}
```

Errors

```json
{
  "error": {
    "code": "validation_error",
    "message": "Name is required and must be unique within organization",
    "trace_id": "trace_abc123"
  }
}
```