# Assistant Object

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


Represents a pre-configured AI assistant with specific instructions, tool configurations, and behavior settings. Assistants enable consistent AI behavior across conversations with reusable configurations.

## Properties

**`id`** string

Unique identifier for the assistant. Format: `asst_` followed by alphanumeric characters.

**`organization_id`** string

The organization this assistant belongs to.

**`created_by`** string

User ID of the person who created this assistant.

**`created_at`** integer

Unix timestamp (seconds) when the assistant was created.

**`updated_at`** integer

Unix timestamp (seconds) when the assistant was last modified.

**`deleted_at`** integer optional

Unix timestamp (seconds) when the assistant was deleted. Null if the assistant is not deleted.

**`name`** string

Human-readable name for the assistant. Used for identification in lists and UI.

**`avatar_id`** string optional

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

**`icon_type`** string optional

Type of icon used for the assistant. Values: `default`, `upload`, `emoji`, `icon`.

**`icon_data`** string optional

Icon data based on icon_type. Can be base64 image data, emoji character, or icon identifier from the Aitronos icon library.

**`is_default`** boolean

Whether this assistant is the default assistant for the organization. Only one assistant per organization can be the default.

**`default_model_key`** string

The default AI model key used by this assistant. Example: `gpt-4o`, `gpt-5`, `o3-preview`, `claude-3-5-sonnet`, `ftg-3.0-pro`, `ftg-3.0`. [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

System-level instructions that define the assistant's behavior, personality, and capabilities. These instructions are automatically included in every conversation with this assistant.

**`instructions_thread_id`** string optional

Thread ID used for AI-assisted instruction generation and management. Allows the assistant to maintain context when generating or refining its own instructions.

**`tool_configurations`** object

Configuration for built-in system tools and external integrations available to the assistant.

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

Built-in Aitronos tools configuration.

details
summary
Show system tools
**`webSearch`** object optional

Web search tool configuration. [Learn more about Web Search →](/docs/documentation/tools/web-search)

details
summary
Show properties
    **`mode`** string · Defaults to `auto`

    Tool availability mode. Values: `on` (always available), `off` (disabled), `auto` (model decides when to use).

    **`sources`** boolean · Defaults to `true`

    Include source URLs and metadata in search results.

**`codeInterpreter`** object optional

Python code execution tool configuration. [Learn more about Code Interpreter →](/docs/documentation/tools/code-interpreter)

details
summary
Show properties
    **`mode`** string · Defaults to `auto`

    Tool availability mode. Values: `on`, `off`, `auto`.

    **`outputs`** boolean · Defaults to `true`

    Include execution outputs and generated files in responses.

**`fileSearch`** object optional

Document search tool configuration. [Learn more about File Search →](/docs/documentation/tools/file-search)

details
summary
Show properties
    **`mode`** string · Defaults to `auto`

    Tool availability mode. Values: `on`, `off`, `auto`.

    **`results`** boolean · Defaults to `true`

    Include matched document chunks and relevance scores.

**`computerUsePreview`** object optional

Experimental computer control tool configuration. [Learn more about Computer Use →](/docs/documentation/tools/computer-use)

details
summary
Show properties
    **`mode`** string · Defaults to `off`

    Tool availability mode. Values: `on`, `off`, `auto`.

    **`imageUrl`** boolean · Defaults to `true`

    Include screenshot URLs from computer interactions.

**`imageGeneration`** object optional

AI image generation tool configuration. [Learn more about Image Generation →](/docs/documentation/tools/image-generation)

details
summary
Show properties
    **`mode`** string · Defaults to `off`

    Tool availability mode. Values: `on`, `off`, `auto`.

    **`provider`** string · Defaults to `openai`

    Image generation provider. Values: `openai`, `clipdrop`.

**`fileRetrieval`** object optional

File retrieval and processing tool configuration. [Learn more about File Retrieval →](/docs/documentation/tools/file-retrieval)

details
summary
Show properties
    **`mode`** string · Defaults to `auto`

    Tool availability mode. Values: `on`, `off`, `auto`.

**`mcpTools`** array optional

Remote tool integrations using Model Context Protocol (MCP) servers. These connections allow the assistant to interact with third-party services and APIs. [Learn more about MCP](/docs/documentation/core-concepts/mcp-tools)

details
summary
Show MCP tool structure
Each MCP tool configuration:

**`serverLabel`** string required

Display name for the MCP server, referenced when invoking tools.

**`type`** string required

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

**`allowedTools`** array or object optional

Tool access control via string list or filter criteria.

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

Collection of tool names granted access.

**MCP tool filter** object

Criteria-based tool access control.

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

Filters tools based on data modification capability. Applies to MCP servers with `readOnlyHint` annotation.

**`toolNames`** array optional

Specific tool names granted access.

**`authorization`** string optional

OAuth token for MCP server authentication. Supports both custom server URLs and service connector integrations.

**`connectorId`** string optional

Pre-configured service integration identifier. Provide either `serverUrl` or `connectorId`.

Examples: `connector_dropbox`, `connector_microsoftteams`

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

**`headers`** object optional

Additional HTTP request headers sent with MCP server communications. Useful for custom authentication schemes.

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

Approval policy configuration for tool execution.

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

Granular approval controls using policy strings (`always`/`never`) or conditional filters.

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

Conditions for tools requiring mandatory 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

Conditions for tools exempt from 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

Blanket approval policy applied to all tools. Use `always` for universal approval requirements or `never` to disable all approvals.

**`serverDescription`** string optional

Human-readable explanation of the MCP server's functionality and purpose.

**`serverUrl`** string optional

Network address of the MCP server. Provide either `serverUrl` or `connectorId`.

**`streamlineTools`** array optional

Array of Streamline/Flow-Plate automation IDs available to the assistant. Each ID references a workflow automation that the assistant can trigger.

**`system_message`** array optional

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

details
summary
Show structure

```json
"system_message": [
  {
    "texts": ["You are a helpful assistant specialized in customer support."],
    "images": [],
    "audio": [],
    "files": []
  },
  {
    "texts": ["Always be polite and professional."],
    "images": ["https://example.com/brand-guidelines.png"],
    "audio": [],
    "files": []
  }
]
```

See [Input message object](/docs/api-reference/objects/input-message) for full structure details.

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

Sets the overall thread context management strategy. Values:

- `full` - Keep all conversation history
- `off` - No context retention
- `auto` - Intelligent context management (default)
- `saver` - Minimal context to save neurons


**`context_window`** integer optional

Context window size override (model dependent). Allows overriding the default context window size for the selected model.

**`max_tool_calls`** integer

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

**`parallel_tool_calls`** boolean

Whether the assistant can execute multiple tool calls simultaneously.

**`reasoning`** object optional

Configuration options 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`

Constrains effort on reasoning for reasoning models. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response.

- `minimal` - Fastest responses with minimal reasoning tokens
- `low` - Quick reasoning for simple tasks
- `medium` - Balanced reasoning for most use cases (default)
- `high` - Deep reasoning for complex problems, uses more tokens and time


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

A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process.

- `auto` - Automatically determine summary level (default)
- `concise` - Brief summary of reasoning steps
- `detailed` - Comprehensive explanation of the reasoning process


**`service_tier`** string

Processing tier for requests. Values: `auto`, `default`, `flex`, `priority`. The actual tier used may differ from requested.

**`store_responses`** boolean

Whether to store generated responses for later retrieval via API. When enabled, conversation threads are saved and accessible to users. When disabled, threads are saved in the background but not accessible.

**`temperature`** number

Sampling temperature (0.0-2.0). Higher values increase randomness and creativity. Lower values produce more focused, deterministic outputs.

**`frequency_penalty`** number optional

Penalty for token frequency (-2.0 to 2.0). Positive values reduce repetition of tokens based on their frequency in the text so far.

**`presence_penalty`** number optional

Penalty for token presence (-2.0 to 2.0). Positive values encourage the model to talk about new topics by penalizing tokens that have already appeared.

**`logit_bias`** object or integer optional

Logit bias adjustments for token generation. Can be an object mapping token IDs to bias values (e.g., `{"50256": -100}`) or `0` for no bias. Bias values range from -100 to 100.

**`json_schemas`** array optional

Array of JSON schema objects that define structured output formats. Each schema includes `id`, `name`, `description`, and `schemaObject`. [View JSON Schema Object →](/docs/api-reference/objects/json-schema-object)

**`top_logprobs`** integer

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

**`top_p`** number

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

**`output_mode`** string · Defaults to `text`

Response output format mode. Values:

- `text` - Natural language responses (default)
- `json_object` - Structured JSON output
- `json_schema` - JSON output validated against a schema


**`response_format`** string · Defaults to `auto`

Response format mode that controls how the model structures its output. Values:

- `auto` - Model automatically chooses appropriate format
- `text` - Plain text responses
- `json_object` - Structured JSON object
- `json_schema` - JSON validated against provided schema


**`seed`** integer optional

Random seed for deterministic outputs. When provided, the model will attempt to generate the same output for identical inputs (if supported by the model).

**`stopSequences`** array optional

Custom stop sequences to halt generation. Array of strings that will stop the model's output when encountered.

**`max_completion_tokens`** integer optional

Maximum tokens in completion (distinct from maxTokens). Some providers use this parameter separately from the general token limit.

**`access_mode`** string

Legacy access control mode for the assistant. Values: `private` (only creator), `restricted` (users in `access_users`), `department` (users in `access_departments`), `organization` (all org members), `global`, `public` (anyone). [Learn more about access management →](/docs/documentation/core-concepts/access-management)

**`access_departments`** array optional

Array of department names that have access to this assistant when `access_mode` is `department`. Example: `["Engineering", "Sales"]`.

**`access_users`** array optional

Array of user IDs that can view/use this assistant when `access_mode` is `restricted`. Example: `["uid_123", "uid_456"]`.

**`editable_by_users`** array optional

Array of user IDs that have permission to edit this assistant (regardless of access mode). Creator is always included implicitly. Example: `["uid_test1", "uid_test2"]`.

**`visible_in_chat_to_users`** array optional

Array of user IDs that can see this assistant in chat/configuration interfaces. Controls UI visibility. Example: `["uid_test3", "uid_test4"]`.

**`editable_by_roles`** array optional

Array of role names that have permission to edit this assistant. Common roles: `admin`, `manager`, `member`, `viewer`. Example: `["admin", "manager"]`.

**`visible_to_roles`** array optional

Array of role names that can view this assistant. Example: `["member", "viewer", "admin"]`. [Learn more about access management →](/docs/documentation/core-concepts/access-management)

**`vector_store_ids`** array optional

Array of vector store IDs for file search capabilities.

**`api_enabled`** boolean

Whether the assistant is accessible via API key authentication. When false, only bearer token (JWT) authentication works. When true, both bearer token and API key authentication work.

**`public_enabled`** boolean

Whether a public website is generated and enabled for this assistant. Public assistants can be accessed by anyone with the link, without authentication.

**`is_active`** boolean

Whether the assistant is active and available for use. Soft-deleted assistants have `is_active` set to false.

**`streaming`** boolean

Whether streaming responses are enabled. When true, the model delivers tokens in real-time as they are generated.

**`memory_enabled`** boolean

Whether conversation memory is enabled across sessions. When true, the assistant maintains context from previous conversations.

**`moderation_enabled`** boolean

Whether content moderation is enabled for inputs and outputs. Helps ensure safe and appropriate content.

**`safety_level`** string

Content safety filtering level. Values:

- `low` - Minimal filtering
- `medium` - Balanced safety (default)
- `high` - Strict filtering


**`preset_prompts`** array optional

Array of preset prompt suggestions displayed to users. These are quick-start prompts that help users get started with the assistant.

**`tool_capabilities`** object optional

Flat object indicating which tool capabilities are enabled for this assistant (used in LIST endpoint for performance). Properties:

- `webSearch` (boolean)
- `fileSearch` (boolean)
- `codeInterpreter` (boolean)
- `imageGeneration` (boolean)
- `dataAnalysis` (boolean)
- `functionCalling` (boolean)
- `computerUse` (boolean)
- `computerUsePreview` (boolean)


**`metadata`** object optional

Custom key-value pairs for organizing and filtering assistants.

**`text_config`** object optional

Text configuration options for structured outputs. Can include formatting preferences and output structure specifications.

**`rule_ids`** array optional

Array of rule IDs attached to this assistant. Rules are content policies, behavior guidelines, or constraints applied during conversation.

## Example Assistant

Customer Support

```json
{
  "id": "asst_customer_support_001",
  "organization_id": "org_xyz789",
  "created_by": "user_abc123",
  "created_at": 1728057600,
  "updated_at": 1728057600,
  "deleted_at": null,
  "name": "Customer Support Assistant",
  "avatar_id": "avt_support_green",
  "icon_type": "emoji",
  "icon_data": "💬",
  "default_model_key": "gpt-4o",
  "allowed_model_providers": ["openai", "anthropic"],
  "instructions": "You are a helpful customer support assistant. Always be polite, empathetic, and solution-oriented. Prioritize customer satisfaction and provide clear, actionable guidance.",
  "tool_configurations": {
    "systemTools": {
      "webSearch": {
        "mode": "auto",
        "sources": true
      },
      "fileSearch": {
        "mode": "on",
        "results": true
      },
      "codeInterpreter": {
        "mode": "off"
      }
    },
    "mcpTools": [],
    "streamlineTools": ["automation_abc123", "automation_def456"]
  },
  "system_message": null,
  "context_strategy": "auto",
  "max_tool_calls": 10,
  "parallel_tool_calls": true,
  "reasoning": null,
  "service_tier": "default",
  "store_responses": true,
  "temperature": 0.7,
  "frequency_penalty": 0.0,
  "presence_penalty": 0.0,
  "text_config": null,
  "top_logprobs": 0,
  "top_p": 1.0,
  "access_mode": "organization",
  "access_departments": [],
  "access_users": [],
  "editable_by_users": [],
  "visible_in_chat_to_users": [],
  "editable_by_roles": ["admin", "manager"],
  "visible_to_roles": ["member", "admin"],
  "vector_store_ids": ["vs_abc123", "vs_def456"],
  "api_enabled": true,
  "is_active": true,
  "metadata": {
    "department": "customer_success",
    "version": "2.1"
  },
  "rule_ids": [
    "rule_professional_tone",
    "rule_safety_guidelines"
  ]
}
```

Code Assistant

```json
{
  "id": "asst_code_helper_001",
  "organization_id": "org_xyz789",
  "created_by": "user_def456",
  "created_at": 1728057650,
  "updated_at": 1728057700,
  "deleted_at": null,
  "name": "Senior Developer Assistant",
  "avatar_id": "avt_robot_blue",
  "icon_type": "emoji",
  "icon_data": "👨‍💻",
  "default_model_key": "gpt-5",
  "allowed_model_providers": ["openai", "anthropic", "aitronos"],
  "instructions": "You are an expert software engineer specializing in full-stack development. Provide clear, well-documented code examples with best practices. Explain complex concepts in simple terms.",
  "tool_configurations": {
    "systemTools": {
      "webSearch": {
        "mode": "on",
        "sources": true
      },
      "codeInterpreter": {
        "mode": "on",
        "outputs": true
      },
      "fileSearch": {
        "mode": "auto",
        "results": true
      }
    },
    "mcpTools": [
      {
        "configurationId": "mcp_github_integration",
        "serverLabel": "GitHub",
        "connectorId": "connector_github"
      }
    ],
    "streamlineTools": ["automation_abc123", "automation_def456"]
  },
  "system_message": "Always include code examples and explain your reasoning.",
  "context_strategy": "full",
  "max_tool_calls": 20,
  "parallel_tool_calls": true,
  "reasoning": {
    "effort": "high",
    "summary": "detailed"
  },
  "service_tier": "priority",
  "store_responses": true,
  "temperature": 0.3,
  "frequency_penalty": 0.5,
  "presence_penalty": 0.3,
  "text_config": {
    "format": "markdown"
  },
  "top_logprobs": 0,
  "top_p": 0.95,
  "access_mode": "private",
  "access_departments": [],
  "access_users": [],
  "editable_by_users": ["uid_test1"],
  "visible_in_chat_to_users": [],
  "editable_by_roles": ["admin", "developer"],
  "visible_to_roles": ["admin"],
  "vector_store_ids": [],
  "api_enabled": true,
  "is_active": true,
  "metadata": {
    "team": "engineering",
    "specialty": "fullstack"
  },
  "rule_ids": [
    "rule_technical_docs_style"
  ]
}
```

Reasoning Assistant

```json
{
  "id": "asst_reasoning_001",
  "organization_id": "org_xyz789",
  "created_by": "user_ghi789",
  "created_at": 1728057800,
  "updated_at": 1728057800,
  "deleted_at": null,
  "name": "Research & Analysis Assistant",
  "avatar_id": "avt_research_purple",
  "icon_type": "emoji",
  "icon_data": "🔬",
  "default_model_key": "o3-preview",
  "allowed_model_providers": ["openai"],
  "instructions": "You are a research assistant specializing in deep analysis and problem-solving. Take time to think through complex problems step by step. Provide thorough, well-reasoned answers with supporting evidence.",
  "tool_configurations": {
    "systemTools": {
      "webSearch": {
        "mode": "on",
        "sources": true
      },
      "fileSearch": {
        "mode": "on",
        "results": true
      },
      "codeInterpreter": {
        "mode": "auto",
        "outputs": true
      }
    },
    "mcpTools": [],
    "streamlineTools": ["automation_abc123", "automation_def456"]
  },
  "system_message": null,
  "context_strategy": "full",
  "max_tool_calls": 15,
  "parallel_tool_calls": false,
  "reasoning": {
    "effort": "high",
    "summary": "detailed"
  },
  "service_tier": "priority",
  "store_responses": true,
  "temperature": 0.2,
  "frequency_penalty": 0.0,
  "presence_penalty": 0.0,
  "text_config": null,
  "top_logprobs": 5,
  "top_p": 1.0,
  "access_mode": "department",
  "access_departments": ["dept_research", "dept_analytics"],
  "access_users": [],
  "editable_by_users": [],
  "visible_in_chat_to_users": ["uid_test2"],
  "editable_by_roles": ["admin"],
  "visible_to_roles": ["member", "viewer", "admin"],
  "vector_store_ids": ["vs_research_papers", "vs_datasets"],
  "api_enabled": false,
  "is_active": true,
  "metadata": {
    "use_case": "research",
    "domain": "scientific"
  },
  "rule_ids": null
}
```

## Related

- [Access Management Guide](/docs/documentation/core-concepts/access-management) - Complete guide to access control
- [Create assistant](/docs/api-reference/assistants/create) - Create a new assistant
- [Update assistant](/docs/api-reference/assistants/update) - Modify assistant configuration
- [Attach rule](/docs/api-reference/assistants/attach-rule) - Add rules to assistant
- [Response object](/docs/api-reference/objects/response-object) - Model response format