Create a model response

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
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Provide text or image inputs to generate text or JSON outputs. Have the model call your own custom code or use built-in tools like web search or file search.

Request Body

Core Parameters

organization_id string optional

The unique identifier of the organization to which this request belongs. All API requests must be scoped to an organization for billing, access control, and resource management. Find your organization ID in Freddy → Settings → Organization.

assistant_id string optional

ID of the assistant to use for this response. When provided, automatically applies the assistant's configured rules, instructions, and settings. Enables consistent AI behavior across conversations with priority-based rule application and context management. Learn more about assistants

disable_rules boolean optional · Defaults to false

Disable all rule application for this response. When true, no rules will be applied regardless of other rule settings. This parameter is only available when using API keys and cannot be used with bearer tokens (user authentication). Learn more about rules

skill_ids array optional

Target a specific set of skills for this single request. When provided, ONLY these skills are injected into the system prompt — overrides both the user's full library and any skills attached to the assistant. Accepts personal skill IDs (skill_...), organization skill IDs (skill_...), and platform skill names (platform-...). Skills the user cannot access are silently skipped. Pass an empty list to inject no skills. Unset/null preserves the default resolution (assistant attachments → full library).

model string optional · Defaults to ftg-3.0

The AI model to use for generating the response. Aitronos supports various models with different capabilities, performance characteristics, and pricing. Choose based on your task requirements: reasoning models for complex problems, fast models for simple queries, or vision models for image understanding. View available models →

auto_generate_name boolean optional

When true, the backend auto-generates a concise title for the thread after the turn completes — but only while the thread is still unnamed (it never overwrites a user-set title).

usage_context object optional

Attribution context for billing. Lets a usage/cost line be traced back to its product origin (source), sub-feature, AI mode, and the entity/field it acted on.

voice_lean boolean optional

Enable low-latency lean mode. Trims the system prompt to its essentials and keeps only a few core tools loaded up front (the rest stay reachable on demand) to reduce time-to-first-token. Off by default.

inputs array required

Array of input message objects. Each message contains a role and content (text string or structured content blocks), with optional file attachments. View full object →

Thread and Context

thread_id string optional

The ID of the thread that this response belongs to. Items from this thread are prepended to inputs for this response request. Input items and output items from this response are automatically added to this thread after completion. Learn more

If no thread_id is provided, a new thread is automatically created for this request. The response will include the new thread ID, which can be used in subsequent requests to maintain conversation context and history. This enables seamless multi-turn conversations without manual thread management. For stateless multi-turn conversations, use previous_response_id instead.

store boolean optional · Defaults to true

Controls whether the created thread is visible in the user's thread list. When true (default), the thread appears in the list threads API and is visible in the user interface. When false, the thread is hidden from the list threads API but remains accessible by direct thread ID lookup. This is useful for internal operations, background tasks, or temporary threads that shouldn't clutter the user's conversation history. Learn more

space_id string optional

ID of the space to associate the thread with. When provided, new threads are automatically added to the specified space. The space's dedicated vector store and any additional attached vector stores are merged into the conversation's knowledge sources, enabling shared context across all threads in the space. This is idempotent — passing the same space_id on subsequent messages to the same thread has no effect. Learn more about spaces

instructions string optional

System-level instructions that define the model's behavior and capabilities. These instructions override any previous system messages when continuing from a prior response, allowing you to dynamically adjust the model's context without carrying over old system prompts.

Response Delivery

stream boolean optional · Defaults to false

Enable streaming mode to receive response data incrementally as it's generated, using server-sent events (SSE). When enabled, the model sends partial outputs in real-time rather than waiting for the complete response. Ideal for user-facing applications requiring immediate feedback. Learn more

suppress_assistant boolean optional · Defaults to false

When true, the posted user message is persisted and fanned out to everyone present on the thread (via the message.created live event) but no assistant turn runs — no model call, no response, no SSE stream. Use it for a human-to-human @user aside in a shared/group thread: every participant sees the message, but the assistant does not reply. The flag wins even when stream is true. The endpoint returns a small JSON acknowledgement { id, thread_id, created_by_user_id, mention_user_ids, suppressed: true } instead of a response. When false (default), behaviour is unchanged and a normal assistant turn runs.

mention_user_ids array optional

User IDs this message is addressed to (the @user mention targets). Stored on the message and echoed on the message.created live event and on the fetched message object (see List Messages) so clients can render a "→ to {name}" affordance. An empty or omitted list means no mention (normal addressing). This does not by itself suppress the assistant — pair it with suppress_assistant: true for a human-only aside.

output_mode string optional · Defaults to text

Controls the format of the model's response output. Determines how the response content is structured and returned.

include array optional

Specify additional data to include in the response. Each value expands specific parts of the output with extra information. Learn more

Limits and Controls

max_output_synapses integer optional

Maximum number of synapses the model can generate in the response, including both visible output and internal reasoning synapses. Use this to control response length and computational cost. Learn more

metadata object optional

Custom key-value pairs (up to 16) for attaching structured information to the response. Useful for tracking, categorization, or filtering responses in your application. Keys must be ≤64 characters, values ≤512 characters.

previous_response_id string optional

Reference a previous response to create multi-turn conversations while maintaining context. The model will use the outputs and state from the referenced response as the starting point for this new response. Cannot be used together with thread. Learn more

vector_store_ids array optional

Vector store IDs for file search/RAG. Enables searching uploaded files to answer queries.

edit_message_id string optional

Message ID to edit. Soft-deletes this message and all subsequent messages, then creates a new branch.

previous_message_id string optional

Message ID to branch from. Soft-deletes all messages after this message (keeping it), then continues from that point.

workflow_id string optional

Workflow/Flow ID from FlowPlate. Used to associate threads with specific workflow automations.

Skills

Skills are reusable, named instruction blocks (summarize, translate, review-code, etc.). All skill execution happens through this endpoint — there is no separate "execute skill" endpoint. There are two ways a skill can run during a response:

1. Catalog + autonomous invocation (default). The server injects a compact skill catalog (one line per skill) into the system prompt. The model sees the catalog and can call the invoke_skill system tool when the conversation matches a skill's purpose. The tool resolves the skill and returns its instructions as a tool result.
2. Forced server-side injection. Set force_skill_id to make the server resolve and inject a specific skill's content as a system message for this turn. Strict: invalid IDs return HTTP 422. Use this when the client knows exactly which skill should run (e.g. a user clicked a "Use this skill" button or typed a slash command in your UI).

Skills with disable_model_invocation: true are hidden from path 1 (the catalog) — they only run via path 2 (explicit force_skill_id).

skill_ids array optional

Explicit list of skill IDs to scope the catalog for this request. When set, only these skills appear in the catalog and are valid targets for invoke_skill. Accepts personal or org skill IDs (skill_*) and platform skill names (platform-*). Unknown or inaccessible IDs are silently skipped (permissive). An empty list [] opts out of skill injection entirely. Omit (null) to fall back to the assistant's attached skills, then the user's full library.

force_skill_id string optional

When set, the server resolves this skill (with empty arguments) and injects its content as a system message for this turn only, forcing the model to follow the skill's instructions. Accepts a personal or org skill ID (skill_*) or a platform skill name (platform-*). Strict: an invalid or inaccessible ID returns HTTP 422. Works alongside skill_ids — you can force one skill AND scope the catalog to a subset.

Reasoning

reasoning object optional

Unified reasoning configuration that works across all reasoning-capable models (OpenAI GPT-5/O-series, Anthropic Claude). Controls how much computational effort the model dedicates to internal chain-of-thought processing before generating the final output. The API automatically maps your effort level to provider-specific parameters. Learn more

Tools

tools array optional

Array of custom tools the model can invoke during response generation. Supports custom function calls, personal connectors, and MCP server tools. Tool usage can be controlled via the tool_choice parameter. For built-in capabilities like web search, file search, and code execution, use the system_tools parameter instead. Learn more

["search_documents", "list_files", "get_file_content"]

{
  "include": ["search_*", "get_*"],
  "exclude": ["delete_*", "update_*"]
}

System Tools

system_tools object optional

Configuration for built-in system tools provided by Aitronos. These extend model capabilities beyond the custom tools in the tools array. System tools are enabled/disabled via mode settings rather than being defined inline.

Example:

{
  "inputs": [{"role": "user", "content": "Generate an image of a sunset over mountains"}],
  "model": "ftg-3.0",
  "system_tools": {
    "image_operations": {"mode": "on"}
  }
}

Output Format

Response Parameters

temperature number optional

Controls output randomness and creativity. Values range from 0.0 to 1.0. Lower values (e.g., 0.2) produce focused, deterministic outputs ideal for factual tasks. Higher values (e.g., 0.8) generate more varied, creative responses suited for brainstorming. Adjust either temperature or top_p, not both.

top_p number optional · Defaults to 1.0

Alternative to temperature for controlling randomness via nucleus sampling. Only the top cumulative probability mass up to top_p is considered. For example, 0.9 means only the top 90% probability mass is used. Values range from 0.0 to 1.0. Adjust either top_p or temperature, not both.

Body parameters

assistant_name string optional

The assistant name.

frequency_penalty number optional

The frequency penalty.

deep_search_config object optional

The deep search config.

partial_context object optional

Partial state from an interrupted stream, sent by the frontend to enable recovery.

parallel_tool_calls boolean optional

The parallel tool calls.

service_tier string optional

The service tier.

thread_context_mode string optional

The thread context mode.

assistant_instructions string optional

The assistant instructions.

assistant_description string optional

The assistant description.

max_completion_tokens integer optional

The max completion tokens.

slice_ids array[string] optional

The slice ids.

prefer_deep_search boolean optional

The prefer deep search.

max_tool_calls integer optional

The max tool calls.

is_incognito boolean optional

Enable incognito mode. Thread will not be saved, personal memories will not be extracted or used. Ignored if thread_id references an existing thread.

presence_penalty number optional

The presence penalty.

Returns

Non-streaming (stream: false): Returns a complete Response object after generation finishes.

Streaming (stream: true): Returns Streaming event objects as Server-Sent Events (SSE). Each event contains a specific event type and data payload showing the model's progress, tool calls, and generated content in real-time.

curl https://api.aitronos.com/v1/model/response \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "org_abc123",
    "model": "ftg-3.0",
    "inputs": [
      {
        "role": "user",
        "content": "What is the capital of France?"
      }
    ]
  }'

Response:

{
  "success": true,
  "thread_id": "thrd_xyz789",
  "response": [
    {
      "type": "text",
      "text": "The capital of France is Paris. It is located in the north-central part of the country and is known for its art, culture, and iconic landmarks like the Eiffel Tower."
    }
  ],
  "response_id": "resp_abc123",
  "is_summarized": false,
  "stop_reason": "end_turn"
}