# Create assistant **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. **`default_model_key`** string optional · Defaults to `ftg-3.0-speed` The AI model key 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. **`personality_id`** string optional Style-profile id (`sty_…`, `kind=personality`). Null leaves the column empty; the turn still gets the platform default voice (Witty — `default_personality_id` on [List style profiles](/docs/api-reference/style-profiles/list)) unless a register that is not the factory default is stored. Applying a catalog personality should also copy that row's `settings` onto `personality_settings`. **`personality_settings`** object optional Register modes. Null/omitted keys use defaults (`profanity=avoid`, `lecturing=default`, `adult=avoid`, `candor=cautious`, `dark_humor=off`). Allowed values: `profanity` `avoid` | `when_fitting` | `unrestricted`; `lecturing` `default` | `never`; `adult` `avoid` | `allow`; `candor` `cautious` | `direct`; `dark_humor` `off` | `on`. These compile into the assistant system prefix, not into customer rules. There is no racism/hate toggle. **`vector_store_ids`** array optional Array of vector store IDs for file search capabilities. **`personal_connector_attachments`** array optional Personal connector credentials to attach to this assistant. Each entry has a `credential_id` (must be a connector credential you own), plus optional `allowed_tools` (list of action names, or `{"enabled": [...], "disabled": [...]}`) and `require_approval` (`"always"`, `"never"`, or a per-action dict) to scope what the assistant can do with that connector. Omit or pass an empty array to attach none. **`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 →](/docs/api-reference/assistants/access-management) **`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 · Defaults to `false` Stored and returned as set. No content moderation is applied today: nothing in the backend reads this flag, so `true` and `false` produce the same model behaviour. **`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`. **`skin_mode`** string optional Deprecated: every assistant uses the one skin catalog, so this is always `v2`. Any value sent (`legacy`, `beta` or `v2`) is accepted and stored as `v2`; responses return `v2`. **`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 · Defaults to `medium` Stored and returned as set. Does NOT gate model output today: nothing in the backend reads this value, so `low`, `medium` and `high` produce the same model behaviour. Accepted values: `low`, `medium`, `high` — any other value, including `strict`, is refused with `422 VALIDATION_ERROR`. **`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 **Deprecated and non-functional.** No model provider honors `logit_bias` on the conversation path, so it has no effect. Sending a non-empty value returns a `422 INVALID_REQUEST` error. Omit this field. **`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. **`timezone`** string optional Explicit override of the IANA timezone the assistant's clock runs in, e.g. 'Europe/Vienna'. Null (the default) means nobody chose one. When set, it is used for the current date and time the assistant is given on every turn, and therefore for every opening-hours, 'what is open now' and time-of-day answer, and it takes precedence over the timezone of whoever the assistant is interacting with, including a signed-in user's own profile timezone. Leave it null to let the assistant follow the person it is talking to; when that person's timezone is not known either, the assistant uses its derived default timezone, and UTC only as a last resort. **`kind`** string optional standard (default) or automation: an organisation-owned assistant that runs its own FlowPlate flow, created together with it One of `standard`, `automation`. **`responsible_user_id`** string optional Automation only: the person who answers for it (default: you). Naming someone else needs organisation-management permission. **`home`** object optional The assistant's home (Assistant Home) **`avatar_id`** string optional Predefined avatar identifier from the Aitronos avatar library. [View available avatars →](/assets/list.d669ff9103f000c8666b615b40b07c3fc85c38b5f79c4c450993a9c75eb89d8c.76c3c710.md) **`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 **`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 **`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](/docs/documentation/core-concepts/mcp-tools) details summary 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. 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 **`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 →](/docs/documentation/tools/mcp-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. 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 **`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. details summary 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 as an array of role/content objects. Each entry has exactly two fields: `role` (one of `system`, `user`, `assistant`) and `content` (a plain-text string, max 50,000 characters). Any other keys are rejected. **`locale`** string optional Language of this assistant's streamed [activity labels](/docs/api-reference/responses/create) (`activity.text`): `auto` (the default; `null` means the same and is read back as `auto`), a language tag such as `de` or `pt-BR`, or a language name such as `Swiss German`. Auto follows the language of the person's message, then the language they chose for their account, then English. A request's own `locale` takes precedence. The choices with built-in labels are listed by [List activity label languages](/docs/api-reference/assistants/list-activity-label-languages); any other language is stored and served as Auto until its labels exist. A value that is neither a language tag nor a language name (or the literal `custom`) is rejected with `422`. Affects only the progress labels, never the assistant's answers. **`context_strategy`** string optional · Defaults to `auto` Context management strategy for the thread. **`max_tool_calls`** integer optional · Defaults to `50` Maximum number of built-in tool calls allowed per response (1–250). **`parallel_tool_calls`** boolean optional · Defaults to `true` Whether the assistant can execute multiple tool calls simultaneously. Set to `false` to force one tool call per model round-trip. **`reasoning`** object optional Configuration for reasoning. Only applicable when using reasoning-capable models. details summary Show reasoning properties **`effort`** string · Defaults to `medium` Computational effort for reasoning. Values: `off`, `none`, `minimal`, `low`, `medium`, `high`, `maximum`, `standard`, `extended`. `none` gives the lowest-latency interactions; `minimal` is the lowest non-zero effort. **`summary`** string · Defaults to `auto` Request reasoning summaries. Values: `off`, `auto`, `concise`, `detailed`. **`service_tier`** string optional · Defaults to `auto` Processing tier for requests. Values: `auto`, `default`, `flex`, `priority`. **`speed_tier`** string optional The assistant's default speed tier id, from `GET /v1/models/speed-options` (for example `standard`, `priority` or `fast`). A turn that does not send its own `speed_tier` takes this value as its requested tier; a per-request `speed_tier` still overrides it. `null` means the assistant sets no default, so the model's own default tier applies. At most 32 characters. **`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](/docs/documentation/core-concepts/structured-output) **`top_logprobs`** integer optional **Deprecated and non-functional.** Log probabilities are not returned on the conversation path, so this has no effect. Sending a non-zero value returns a `422 INVALID_REQUEST` error. Omit this field. **`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. ## Body parameters **`deep_search_config`** object optional Configuration for fetching full page content on web_search results. **`delegate_to_whitelist`** array[string] optional The delegate to whitelist. **`advanced_settings_enabled`** boolean optional Whether advanced settings are expanded in the editor UI **`skin_template_id`** string optional The skin template id. **`tool_approval_mode`** string optional The tool approval mode. **`voice_profile_id`** string optional The voice profile id. **`allowed_models`** object optional Per-provider model selection. Keys are provider slugs; each value is either a list of allowed model keys for that provider or `null` to allow all of its models. Example: `{"openai": ["ftg-3.0", "ftg-3.0-speed"], "anthropic": null}`. **`accept_delegations_from`** array[string] optional The accept delegations from. **`slice_ids`** array[string] optional The slice ids. **`knowledge_department_ids`** array[string] optional Departments (`dept_*`) bound as a **live** knowledge source. The assistant searches every knowledge store each bound department shares **at the time of the question**, so a store shared with the department after the assistant was saved is picked up automatically and one removed from it stops being searched immediately. This is a subscription, not a snapshot — the ids are never expanded into `knowledge_store_ids`, and the two lists coexist (the effective scope is their union, plus `slice_ids`). Only non-private, non-space-bound, active stores in the same organization resolve. Binding at least one department turns on the knowledge search tool even when the department currently shares nothing. You may bind a department you belong to; binding one you do not belong to requires `manage_knowledge_slices`, `manage_access_control`, or owner-level permissions and otherwise returns `403 INSUFFICIENT_PERMISSIONS`. An unknown or inactive department id returns `422 DEPARTMENT_NOT_FOUND`. Maximum 100 ids. **`prefer_deep_search`** boolean optional The prefer deep search. **`delegate_to_blacklist`** array[string] optional The delegate to blacklist. **`skill_ids`** array[string] optional The skill ids. **`knowledge_access_mode`** string optional Knowledge access mode: 'user_scoped' (inherit user's accessible stores/slices) or 'fixed' (use assigned IDs) **`pinned`** boolean optional · Defaults to `false` Whether this assistant is pinned to the top of the assistant list. **`image_operations`** string optional Image operations mode: `auto`, `manual`, or `off`. **`behavior_attachments_enabled`** boolean optional · Defaults to `true` Whether file attachments are enabled in the assistant behavior. **`prompt_cache_enabled`** boolean optional · Defaults to `true` Enable prompt caching for this assistant. When true (default), the assistant's turns send a stable cache key so providers reuse the cached system+tools prefix and cut time-to-first-token. Set false to disable caching for this assistant. **`grant_department_access`** array optional Per-department access grants. Each entry grants a department a specific access level (overwrite/write/admin) or any custom access level. On update, this list is treated as the desired state — departments missing from the list have their grants revoked. ## Returns The created [Assistant object](/docs/api-reference/objects/assistant-object) with all configuration details. ## Access & Permissions Creating an assistant requires the **`create_assistants`** capability in the target organization (the `organization_id` in the request body — and, for API-key auth, the key must be scoped to that organization). Without it the request is rejected with `403 INSUFFICIENT_PERMISSIONS`. The caller who creates the assistant automatically becomes its **owner** (`created_by`), the highest of the four access levels (`none` < `view` < `edit` < `owner`). A Classic API key creates it as its person. An API key that acts as the organization (Scoped or service-account) creates an assistant that belongs to the organization: `created_by` is `null` and `created_by_api_key_id` names the key. **Sharing at creation time** additionally requires a sharing capability, matched to the `access_mode` you request: | `access_mode` | Additional capability required | | --- | --- | | `private` (default) | none | | `department` | `share_assistants_department` | | `organization` | `share_assistants_organization` | Setting a non-private `access_mode`, or populating department/user/role access fields, without the matching sharing capability returns `403 INSUFFICIENT_PERMISSIONS`. For the full access model and field reference, see [Assistant Access Management](/docs/api-reference/assistants/access-management). #### API keys Which kind of API key may call this, decided by the operation's class before anything else ([Refusals by operation class](/docs/api-reference/errors/api-key-scope-forbidden#refusals-by-operation-class)). Class: **Content of the organization**. | Key | Answer | | --- | --- | | Classic key (acts as a person) | allowed, as its person | | Scoped key (acts as the organization) | allowed, within its grants | | Service-account key | allowed, within its capabilities | A Classic key restricted by grants, a Scoped key or a service-account key restricted by scopes also needs `write:agents` (a `write:` scope covers its area's reads); without it the answer is `403 API_KEY_SCOPE_FORBIDDEN`, `reason: "scope_not_granted"`. A Scoped or service-account key that holds only `embed:chat` gets `403 API_KEY_SCOPE_FORBIDDEN`, `reason: "embed_operation_not_allowlisted"` instead. The operation's own permission checks apply after this. Minimal ```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" }' ``` ```python Python SDK from aitronos import Aitronos client = Aitronos(api_key="your-api-key") assistant = client.assistants.create_assistant( organization_id="org_12345", name="My Assistant", model="ftg-3.0", instructions="You are a helpful assistant.", ) print(assistant) ``` ```python import os import requests api_key = os.environ["FREDDY_API_KEY"] response = requests.post( "https://api.aitronos.com/v1/assistants", headers={"X-API-Key": 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 apiKey = process.env.FREDDY_API_KEY; const response = await fetch('https://api.aitronos.com/v1/assistants', { method: 'POST', headers: { 'X-API-Key': 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.aitronos.com/v1/assistants \ -H "X-API-Key: $FREDDY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Research Assistant", "organization_id": "org_abc123", "description": "AI assistant for research and analysis", "model": "ftg-3.0", "instructions": "You are a research assistant that helps find and analyze information.", "tools": [ { "type": "web_search", "search_context_size": "large" }, { "type": "code_interpreter" } ], "temperature": 0.3 }' ``` ```python Python SDK from aitronos import Aitronos client = Aitronos(api_key="your-api-key") assistant = client.assistants.create_assistant( organization_id="org_12345", name="My Assistant", model="ftg-3.0", instructions="You are a helpful assistant.", ) print(assistant) ``` ```python import requests api_key = os.environ["FREDDY_API_KEY"] response = requests.post( "https://api.aitronos.com/v1/assistants", headers={"X-API-Key": api_key, "Content-Type": "application/json"}, json={ "name": "Research Assistant", "organization_id": "org_abc123", "description": "AI assistant for research and analysis", "model": "ftg-3.0", "instructions": "You are a research assistant that helps find and analyze information.", "tools": [ {"type": "web_search", "search_context_size": "large"}, {"type": "code_interpreter"}, ], "temperature": 0.3, }, ) assistant = response.json() ``` ```javascript const apiKey = process.env.FREDDY_API_KEY; const response = await fetch('https://api.aitronos.com/v1/assistants', { method: 'POST', headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' }, body: JSON.stringify({ name: 'Research Assistant', organization_id: 'org_abc123', description: 'AI assistant for research and analysis', model: 'ftg-3.0', 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(); ``` All Parameters ```bash curl https://api.aitronos.com/v1/assistants \ -H "X-API-Key: $FREDDY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Advanced Research Assistant", "organization_id": "org_abc123", "description": "Comprehensive AI assistant with full feature set", "model": "ftg-3.0", "allowed_model_providers": ["openai", "anthropic", "aitronos"], "instructions": "You are an advanced research assistant that helps users find, analyze, and synthesize information from multiple sources.", "tools": [ { "type": "web_search", "search_context_size": "large" }, { "type": "code_interpreter" }, { "type": "function", "function": { "name": "get_weather", "description": "Get current weather for a location", "parameters": { "type": "object", "properties": { "location": {"type": "string"} }, "required": ["location"] } } } ], "vector_store_ids": ["vs_abc123", "vs_def456"], "access_mode": "organization", "temperature": 0.7, "max_output_synapses": 8000, "avatar_id": "avatar_research_001", "tool_configurations": { "systemTools": { "web_search": { "mode": "auto", "sources": true }, "code_interpreter": { "mode": "on", "outputs": true }, "file_search": { "mode": "auto", "results": true }, "imageGeneration": { "mode": "auto", "provider": "openai" }, "fileRetrieval": { "mode": "on" } }, "mcpTools": [ { "server_label": "google-drive", "type": "mcp", "connector_id": "connector_googledrive", "allowed_tools": ["list_files", "read_file"], "require_approval": { "always": { "toolNames": ["delete_file", "update_file"] }, "never": { "readOnly": true } }, "server_description": "Google Drive integration for file access" } ], "streamlineTools": ["flow_abc123", "flow_def456"] }, "system_message": [ { "role": "system", "content": "You are a helpful research assistant." }, { "role": "user", "content": "Example query: What is the latest research on AI?", "images": [{"url": "https://example.com/diagram.jpg"}] } ], "context_strategy": "auto", "max_tool_calls": 20, "parallel_tool_calls": true, "reasoning": { "effort": "high", "summary": "detailed" }, "service_tier": "priority", "store": true, "text_configuration": { "output_mode": "json_schema", "json_schema": { "id": "research_response_v1", "strict": true, "schema": { "type": "object", "properties": { "summary": {"type": "string"}, "sources": { "type": "array", "items": {"type": "string"} }, "confidence": {"type": "number", "minimum": 0, "maximum": 1} }, "required": ["summary", "sources"] } } }, "top_p": 0.9, "truncation": "auto", "metadata": { "category": "research", "department": "engineering", "version": "2.0", "tags": "ai,research,advanced" } }' ``` ```python Python SDK from aitronos import Aitronos client = Aitronos(api_key="your-api-key") assistant = client.assistants.create_assistant( organization_id="org_12345", name="My Assistant", model="ftg-3.0", instructions="You are a helpful assistant.", ) print(assistant) ``` ```python import requests api_key = os.environ["FREDDY_API_KEY"] response = requests.post( "https://api.aitronos.com/v1/assistants", headers={"X-API-Key": api_key, "Content-Type": "application/json"}, json={ "name": "Advanced Research Assistant", "organization_id": "org_abc123", "description": "Comprehensive AI assistant with full feature set", "model": "ftg-3.0", "allowed_model_providers": ["openai", "anthropic", "aitronos"], "instructions": "You are an advanced research assistant that helps users find, analyze, and synthesize information from multiple sources.", "tools": [ {"type": "web_search", "search_context_size": "large"}, {"type": "code_interpreter"}, { "type": "function", "function": { "name": "get_weather", "description": "Get current weather for a location", "parameters": { "type": "object", "properties": {"location": {"type": "string"}}, "required": ["location"], }, }, }, ], "vector_store_ids": ["vs_abc123", "vs_def456"], "access_mode": "organization", "temperature": 0.7, "max_output_synapses": 8000, "avatar_id": "avatar_research_001", "tool_configurations": { "systemTools": { "web_search": {"mode": "auto", "sources": True}, "code_interpreter": {"mode": "on", "outputs": True}, "file_search": {"mode": "auto", "results": True}, "imageGeneration": {"mode": "auto", "provider": "openai"}, "fileRetrieval": {"mode": "on"}, }, "mcpTools": [ { "server_label": "google-drive", "type": "mcp", "connector_id": "connector_googledrive", "allowed_tools": ["list_files", "read_file"], "require_approval": { "always": {"toolNames": ["delete_file", "update_file"]}, "never": {"readOnly": True}, }, "server_description": "Google Drive integration for file access", } ], "streamlineTools": ["flow_abc123", "flow_def456"], }, "system_message": [ {"role": "system", "content": "You are a helpful research assistant."}, { "role": "user", "content": "Example query: What is the latest research on AI?", "images": [{"url": "https://example.com/diagram.jpg"}], }, ], "context_strategy": "auto", "max_tool_calls": 20, "parallel_tool_calls": True, "reasoning": {"effort": "high", "summary": "detailed"}, "service_tier": "priority", "store": True, "text_configuration": { "output_mode": "json_schema", "json_schema": { "id": "research_response_v1", "strict": True, "schema": { "type": "object", "properties": { "summary": {"type": "string"}, "sources": {"type": "array", "items": {"type": "string"}}, "confidence": {"type": "number", "minimum": 0, "maximum": 1}, }, "required": ["summary", "sources"], }, }, }, "top_p": 0.9, "truncation": "auto", "metadata": { "category": "research", "department": "engineering", "version": "2.0", "tags": "ai,research,advanced", }, }, ) assistant = response.json() print(f"Created assistant: {assistant['id']}") ``` ```javascript const apiKey = process.env.FREDDY_API_KEY; const response = await fetch('https://api.aitronos.com/v1/assistants', { method: 'POST', headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' }, body: JSON.stringify({ name: 'Advanced Research Assistant', organization_id: 'org_abc123', description: 'Comprehensive AI assistant with full feature set', model: 'ftg-3.0', allowed_model_providers: ['openai', 'anthropic', 'aitronos'], instructions: 'You are an advanced research assistant that helps users find, analyze, and synthesize information from multiple sources.', tools: [ { type: 'web_search', searchContextSize: 'large' }, { type: 'code_interpreter' }, { type: 'function', function: { name: 'get_weather', description: 'Get current weather for a location', parameters: { type: 'object', properties: { location: { type: 'string' } }, required: ['location'] } } } ], vector_store_ids: ['vs_abc123', 'vs_def456'], access_mode: 'organization', temperature: 0.7, max_output_synapses: 8000, avatar_id: 'avatar_research_001', tool_configurations: { systemTools: { webSearch: { mode: 'auto', sources: true }, codeInterpreter: { mode: 'on', outputs: true }, fileSearch: { mode: 'auto', results: true }, imageGeneration: { mode: 'auto', provider: 'openai' }, fileRetrieval: { mode: 'on' } }, mcpTools: [ { serverLabel: 'google-drive', type: 'mcp', connectorId: 'connector_googledrive', allowedTools: ['list_files', 'read_file'], requireApproval: { always: { toolNames: ['delete_file', 'update_file'] }, never: { readOnly: true } }, serverDescription: 'Google Drive integration for file access' } ], streamlineTools: ['flow_abc123', 'flow_def456'] }, system_message: [ { role: 'system', texts: [{ text: 'You are a helpful research assistant.' }] }, { role: 'user', texts: [{ text: 'Example query: What is the latest research on AI?' }], images: [{ url: 'https://example.com/diagram.jpg' }] } ], context_strategy: 'auto', max_tool_calls: 20, parallel_tool_calls: true, reasoning: { effort: 'high', summary: 'detailed' }, service_tier: 'priority', store: true, text_configuration: { outputMode: 'json_schema', jsonSchema: { id: 'research_response_v1', strict: true, schema: { type: 'object', properties: { summary: { type: 'string' }, sources: { type: 'array', items: { type: 'string' } }, confidence: { type: 'number', minimum: 0, maximum: 1 } }, required: ['summary', 'sources'] } } }, top_p: 0.9, truncation: 'auto', metadata: { category: 'research', department: 'engineering', version: '2.0', tags: 'ai,research,advanced' } }) }); const assistant = await response.json(); console.log(`Created assistant: ${assistant.id}`); ``` **Response:** 200 OK ```json { "id": "asst_abc123", "name": "My Assistant", "description": "A helpful assistant", "organization_id": "org_abc123", "model": "ftg-3.0", "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" } ``` 422 Validation Error ```json { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Input should be 'low', 'medium' or 'high'", "system_message": "Request validation failed", "type": "validation_error", "status": 422, "details": { "fields": [ { "field": "safety_level", "message": "Input should be 'low', 'medium' or 'high'", "type": "literal_error" } ] }, "trace_id": "req_xyz789", "timestamp": "2025-11-11T10:30:00Z" } } ``` 401 Unauthorized ```json { "success": false, "error": { "code": "AUTHENTICATION_REQUIRED", "message": "Please sign in to continue.", "system_message": "Authentication required. Provide either x-api-key, api-key, X-API-Key, or API-Key header, or Bearer ***", "type": "authentication_error", "status": 401, "details": {}, "trace_id": "req_abc123", "timestamp": "2025-11-11T10:30:00Z" } } ``` 403 Forbidden ```json { "success": false, "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "You don't have permission to perform this action.", "system_message": "Missing required capability: create_assistants", "type": "authorization_error", "status": 403, "details": { "required_capability": "create_assistants", "user_id": "usr_abc123" }, "trace_id": "req_def456", "timestamp": "2025-11-11T10:30:00Z" } } ``` 429 Rate Limit ```json { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests. Please wait a moment and try again.", "system_message": "Rate limit exceeded for endpoint", "type": "rate_limit_error", "status": 429, "details": { "retry_after": 60, "limit": 100, "remaining": 0, "reset_at": "2025-11-11T10:31:00Z" }, "trace_id": "req_ghi789", "timestamp": "2025-11-11T10:30:00Z" } } ``` 500 Server Error ```json { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong. Please try again later.", "system_message": "An unexpected error occurred", "type": "server_error", "status": 500, "details": {}, "trace_id": "req_jkl012", "timestamp": "2025-11-11T10:30:00Z" } } ``` ## Related Resources - [Assistant Access Management](/docs/api-reference/assistants/access-management) — Access levels and sharing capabilities - [List Assistants](/docs/api-reference/assistants/list) — Retrieve all assistants - [Retrieve Assistant](/docs/api-reference/assistants/retrieve) — Get a specific assistant - [Update Assistant](/docs/api-reference/assistants/update) — Modify assistant configuration - [Delete Assistant](/docs/api-reference/assistants/delete) — Remove an assistant - [Assistant Object](/docs/api-reference/objects/assistant-object) — Field reference - [List style profiles](/docs/api-reference/style-profiles/list) — Character catalog for `personality_id`