POST /v1/assistants - Create a new AI assistant with custom configuration, tools, and behavior rules.
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.
default_model_key string optional · Defaults to gpt-4o
The AI model key to use for this assistant. 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 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 →
vector_store_ids array optional
Array of vector store IDs for file search capabilities.
access_mode string optional · Defaults to private
Base visibility mode for the assistant. Values: private (explicit access only), organization (all org members can view), public (everyone can view). Learn more about access control →
access_departments array optional
Array of department IDs that have view access to the assistant.
access_users array optional
Array of user IDs that have view access to the assistant.
editable_by_users array optional
Array of user IDs that can edit the assistant configuration.
editable_by_roles array optional
Array of role IDs that can edit the assistant configuration.
visible_to_roles array optional
Array of role IDs that have view access to the assistant.
visible_in_chat_to_users array optional
Array of user IDs that can see the assistant in chat (view-only access).
temperature number optional · Defaults to 0.7
Controls randomness in responses (0.0 to 2.0).
max_completion_tokens integer optional
Maximum number of tokens to generate in the completion.
avatar_id string optional
Predefined avatar identifier from the Aitronos avatar library. View available avatars →
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.
Show tool configurations
systemTools object
Built-in Aitronos tools configuration.
web_search object · mode: on/off/auto, sources: boolean
code_interpreter object · mode: on/off/auto, outputs: boolean
file_search 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
Show properties
server_label 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.
allowed_tools array or object optional
Specify permitted tools either as a string array or filter configuration object.
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.
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.
connector_id string optional
Service connector identifier for pre-integrated platforms. Either server_url or connector_id is required.
Examples: connector_googledrive, connector_gmail
View all supported connectors →
headers object optional
Custom HTTP headers transmitted to the MCP server for authentication or additional metadata.
require_approval object or string optional · Defaults to always
Define approval requirements for MCP server tools.
Show possible types
MCP tool approval filter object
Configure tool-specific approval policies using always, never, or conditional filter rules.
Show properties
always object optional
Filter rules defining tools that always require approval.
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.
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.
server_description string optional
Descriptive text providing additional context about the MCP server's purpose.
server_url string optional
HTTP endpoint for the MCP server. Either server_url or connector_id 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.
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_responses boolean optional · Defaults to true
Whether to store generated responses for later retrieval via API.
text_config object optional
Configuration for text response formatting and structured outputs. Learn more
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 boolean optional · Defaults to true
Auto-truncate messages exceeding context window.
assistant_metadata object optional
Custom key-value pairs for organizing and filtering assistants. Can also be passed as metadata.
The created Assistant object with all configuration details.
- Bash
- Python
- JavaScript
curl https://api.aitronos.com/v1/assistants \
-H "X-API-Key: $FREDDY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "My Assistant",
"organization_id": "org_abc123"
}'Response:
{
"id": "asst_abc123",
"name": "My Assistant",
"description": "A helpful assistant",
"organization_id": "org_abc123",
"model": "gpt-4o",
"instructions": "You are a helpful assistant.",
"tools": [],
"is_active": true,
"access_mode": "private",
"created_at": "2025-11-11T10:30:00Z",
"updated_at": "2025-11-11T10:30:00Z"
}