Skip to content
/
Create assistant
Last updated

Create assistant

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

POSThttps://api.aitronos.com/v1/assistants

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.

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.

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.

context_window integer optional

Maximum context window size for the assistant in tokens.

frequency_penalty number optional

Penalty applied to reduce repetition of frequent tokens (-2.0 to 2.0).

presence_penalty number optional

Penalty applied to encourage exploring new topics (-2.0 to 2.0).

is_active boolean optional · Defaults to true

Whether the assistant is active and available for use.

is_default boolean optional

Whether this assistant is the default for the organization.

api_enabled boolean optional

Whether the assistant is accessible via API.

public_enabled boolean optional

Whether the assistant is publicly accessible.

memory_enabled boolean optional

Whether the assistant has memory capabilities across conversations.

moderation_enabled boolean optional

Whether content moderation is enabled for this assistant.

streaming boolean optional · Defaults to true

Whether the assistant uses streaming responses by default.

output_mode string optional

The output mode for assistant responses. Values: text, json.

response_format object optional

Structured response format configuration.

json_schemas array optional

Array of JSON schema definitions for structured output validation.

safety_level string optional

Safety filtering level for assistant responses.

preset_prompts array optional

Array of preset prompt IDs to attach to this assistant.

rule_ids array optional

Array of rule IDs to apply to this assistant's behavior.

icon_type string optional

Icon type for the assistant. Values: avatar, icon, custom.

icon_id string optional

Predefined icon identifier from the icon library.

icon_data string optional

Base64-encoded custom icon image data.

logit_bias object optional

Token ID to bias value mapping (-100 to 100) to adjust token probabilities.

seed integer optional

Random seed for deterministic outputs.

stop_sequences array optional

Array of sequences where the assistant will stop generating further tokens.

instructions_thread_id string optional

Thread ID containing additional instructions for the assistant.

avatar_id string optional

Predefined avatar identifier from the Aitronos avatar library. View available avatars →

tool_configurations object optional

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

Show tool configurations

system_tools 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

computer_use_preview object · mode: on/off/auto, imageUrl: boolean

image_generation object · mode: on/off/auto, provider: openai/clipdrop

file_retrieval object · mode: on/off/auto

mcp_tools 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

read_only boolean optional

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

tool_names 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

read_only 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.

tool_names array optional

List of allowed tool names.

never object optional

Filter rules defining tools that never require approval.

Show properties

read_only 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.

tool_names 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.

streamline_tools 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.

metadata object optional

Custom key-value pairs for organizing and filtering assistants.

Returns

The created Assistant object with all configuration details.

Bash
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",
  "created_by": "usr_abc123",
  "default_model_key": "gpt-4o",
  "instructions": "You are a helpful assistant.",
  "tool_configurations": null,
  "is_active": true,
  "access_mode": "private",
  "temperature": 0.7,
  "streaming": true,
  "store_responses": true,
  "created_at": 1731318600,
  "updated_at": 1731318600,
  "deleted_at": null
}
Previous page
Next page