Assistant Object

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

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 →

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 →

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.

system_message array optional

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

"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": []
  }
]

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.

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 →

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 →

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 →

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

{
  "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"
  ]
}