---
title: "Create"
method: POST
path: "/v1/chat"
tags: ["v1", "chat"]
---

# Create

`POST /v1/chat`

Create a chat completion using the Agent framework.

This endpoint provides a vendor-agnostic chat completion API that works with
100+ LLM providers via the Agent framework. It supports both single and
multi-model routing, client-side and server-side tool execution, and
integration with MCP (Model Context Protocol) servers.

Features:
    - Cross-vendor compatibility (OpenAI, Anthropic, Cohere, etc.)
    - Multi-model routing with intelligent agentic handoffs
    - Client-side tool execution (tools returned as JSON)
    - Server-side MCP tool execution with automatic billing
    - Streaming and non-streaming responses
    - Advanced agent attributes for routing decisions
    - Automatic usage tracking and billing

Args:
    request: Chat completion request with messages, model, and configuration
    http_request: FastAPI request object for accessing headers and state
    background_tasks: FastAPI background tasks for async billing operations
    user: Authenticated user with validated API key and sufficient balance

Returns:
    ChatCompletion: OpenAI-compatible completion response with usage data

Raises:
    HTTPException:
        - 401 if authentication fails or insufficient balance
        - 400 if request validation fails
        - 500 if internal processing error occurs

Billing:
    - Token usage billed automatically based on model pricing
    - MCP tool calls billed separately using credits system
    - Streaming responses billed after completion via background task

Example:
    Basic chat completion:
    ```python
    import dedalus_labs

    client = dedalus_labs.Client(api_key="your-api-key")

    completion = client.chat.create(
        model="gpt-4",
        input=[{"role": "user", "content": "Hello, how are you?"}],
    )

    print(completion.choices[0].message.content)
    ```

    With tools and MCP servers:
    ```python
    completion = client.chat.create(
        model="gpt-4",
        input=[{"role": "user", "content": "Search for recent AI news"}],
        tools=[
            {
                "type": "function",
                "function": {
                    "name": "search_web",
                    "description": "Search the web for information",
                },
            }
        ],
        mcp_servers=["dedalus-labs/brave-search"],
    )
    ```

    Multi-model routing:
    ```python
    completion = client.chat.create(
        model=["gpt-4o-mini", "gpt-4", "claude-3-5-sonnet"],
        input=[{"role": "user", "content": "Analyze this complex data"}],
        agent_attributes={"complexity": 0.8, "accuracy": 0.9},
    )
    ```

    Streaming response:
    ```python
    stream = client.chat.create(
        model="gpt-4",
        input=[{"role": "user", "content": "Tell me a story"}],
        stream=True,
    )

    for chunk in stream:
        if chunk.choices[0].delta.content:
            print(chunk.choices[0].delta.content, end="")
    ```

## Request body

- ChatCompletionRequest — Request model for chat completions. Validates incoming chat requests with support for multimodality, multi-model routing, and agent-enhanced features. Compatible with OpenAI API format while extending functionality for advanced use cases. This model supports both the OpenAI-standard 'messages' field and the Dedalus-specific 'input' field for maximum compatibility. The 'input' field can handle various modalities beyond text messages. Key Features: - Multi-model routing with intelligent handoffs - MCP (Model Context Protocol) server integration - Advanced agent attributes for routing decisions - Client-side and server-side tool execution - Streaming and non-streaming responses - Automatic usage tracking and billing Examples: Basic chat completion: ```python request = ChatCompletionRequest( model="gpt-4", input=[ {"role": "user", "content": "Hello, how are you?"} ] ) ``` Multi-model routing with attributes: ```python request = ChatCompletionRequest( model=["gpt-4o-mini", "gpt-4", "claude-3-5-sonnet"], input=[ {"role": "user", "content": "Analyze this complex problem"} ], agent_attributes={ "complexity": 0.8, "accuracy": 0.9 }, model_attributes={ "gpt-4": {"intelligence": 0.9, "cost": 0.8}, "claude-3-5-sonnet": {"intelligence": 0.95, "cost": 0.7} } ) ``` With tools and MCP servers: ```python request = ChatCompletionRequest( model="gpt-4", input=[ {"role": "user", "content": "Search for AI news"} ], tools=[ { "type": "function", "function": { "name": "search_web", "description": "Search the web" } } ], mcp_servers=["dedalus-labs/brave-search"], temperature=0.7, max_tokens=1000 ) ```
  - `input` object[], nullable — Input to the model - can be messages, images, or other modalities. Supports OpenAI chat format with role/content structure. For multimodal inputs, content can include text, images, or other media types.
  - `model` union — Model(s) to use for completion. Can be a single model ID or a list for multi-model routing. Single model: 'gpt-4', 'claude-3-5-sonnet-20241022', 'gpt-4o-mini'. Multi-model routing: ['gpt-4o-mini', 'gpt-4', 'claude-3-5-sonnet'] - agent will choose optimal model based on task complexity.
    - string
    - string[]
  - `tools` object[], nullable — List of tools available to the model in OpenAI function calling format. Tools are executed client-side and returned as JSON for the application to handle. Use 'mcp_servers' for server-side tool execution.
  - `tool_choice` union — Controls which tool is called by the model. Options: 'auto' (default), 'none', 'required', or specific tool name. Can also be a dict specifying a particular tool.
    - string
    - object
  - `mcp_servers` string[], nullable — MCP (Model Context Protocol) server addresses to make available for server-side tool execution. Can be URLs (e.g., 'https://mcp.example.com') or slugs (e.g., 'dedalus-labs/brave-search'). MCP tools are executed server-side and billed separately.
  - `temperature` number, nullable — Sampling temperature (0 to 2). Higher values make output more random, lower values make it more focused and deterministic. 0 = deterministic, 1 = balanced, 2 = very creative.
  - `top_p` number, nullable — Nucleus sampling parameter (0 to 1). Alternative to temperature. 0.1 = only top 10% probability mass, 1.0 = consider all tokens.
  - `n` integer, nullable — Number of completions to generate. Note: only n=1 is currently supported.
  - `stream` boolean, nullable — Whether to stream back partial message deltas as Server-Sent Events. When true, partial message deltas will be sent as chunks in OpenAI format.
  - `stop` string[], nullable — Up to 4 sequences where the API will stop generating further tokens. The model will stop as soon as it encounters any of these sequences.
  - `max_tokens` integer, nullable — Maximum number of tokens to generate in the completion. Does not include tokens in the input messages.
  - `presence_penalty` number, nullable — Presence penalty (-2 to 2). Positive values penalize new tokens based on whether they appear in the text so far, encouraging the model to talk about new topics.
  - `frequency_penalty` number, nullable — Frequency penalty (-2 to 2). Positive values penalize new tokens based on their existing frequency in the text so far, decreasing likelihood of repeated phrases.
  - `logit_bias` object, nullable — Modify likelihood of specified tokens appearing in the completion. Maps token IDs (as strings) to bias values (-100 to 100). -100 = completely ban token, +100 = strongly favor token.
  - `user` string, nullable — Unique identifier representing your end-user. Used for monitoring and abuse detection. Should be consistent across requests from the same user.
  - `guardrails` object[], nullable — Guardrails to apply to the agent for input/output validation and safety checks. Reserved for future use - guardrails configuration format not yet finalized.
  - `handoff_config` object, nullable — Configuration for multi-model handoffs and agent orchestration. Reserved for future use - handoff configuration format not yet finalized.
  - `model_attributes` object, nullable — Attributes for individual models used in routing decisions during multi-model execution. Format: {'model_name': {'attribute': value}}, where values are 0.0-1.0. Common attributes: 'intelligence', 'speed', 'cost', 'creativity', 'accuracy'. Used by agent to select optimal model based on task requirements.
  - `agent_attributes` object, nullable — Attributes for the agent itself, influencing behavior and model selection. Format: {'attribute': value}, where values are 0.0-1.0. Common attributes: 'complexity', 'accuracy', 'efficiency', 'creativity', 'friendliness'. Higher values indicate stronger preference for that characteristic.
  - `max_turns` integer, nullable — Maximum number of turns for agent execution before terminating (default: 10). Each turn represents one model inference cycle. Higher values allow more complex reasoning but increase cost and latency.

## Response `200`

Successful Response

- ChatCompletion
  - `id` string, required
  - `choices` Choice[], required
    - `finish_reason` 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'function_call', required
    - `index` integer, required
    - `logprobs` ChoiceLogprobs
      - `content` ChatCompletionTokenLogprob[], nullable
        - `token` string, required
        - `bytes` integer[], nullable
        - `logprob` number, required
        - `top_logprobs` TopLogprob[], required
          - `token` string, required
          - `bytes` integer[], nullable
          - `logprob` number, required
      - `refusal` ChatCompletionTokenLogprob[], nullable
        - `token` string, required
        - `bytes` integer[], nullable
        - `logprob` number, required
        - `top_logprobs` TopLogprob[], required
          - `token` string, required
          - `bytes` integer[], nullable
          - `logprob` number, required
    - `message` ChatCompletionMessage, required
      - `content` string, nullable
      - `refusal` string, nullable
      - `role` 'assistant', required
      - `annotations` Annotation[], nullable
        - `type` 'url_citation', required
        - `url_citation` AnnotationURLCitation, required
          - `end_index` integer, required
          - `start_index` integer, required
          - `title` string, required
          - `url` string, required
      - `audio` ChatCompletionAudio
        - `id` string, required
        - `data` string, required
        - `expires_at` integer, required
        - `transcript` string, required
      - `function_call` FunctionCall
        - `arguments` string, required
        - `name` string, required
      - `tool_calls` ChatCompletionMessageToolCall[], nullable
        - `id` string, required
        - `function` Function, required
          - `arguments` string, required
          - `name` string, required
        - `type` 'function', required
  - `created` integer, required
  - `model` string, required
  - `object` 'chat.completion', required
  - `service_tier` 'auto' | 'default' | 'flex' | 'scale' | 'priority', nullable
  - `system_fingerprint` string, nullable
  - `usage` CompletionUsage
    - `completion_tokens` integer, required
    - `prompt_tokens` integer, required
    - `total_tokens` integer, required
    - `completion_tokens_details` CompletionTokensDetails
      - `accepted_prediction_tokens` integer, nullable
      - `audio_tokens` integer, nullable
      - `reasoning_tokens` integer, nullable
      - `rejected_prediction_tokens` integer, nullable
    - `prompt_tokens_details` PromptTokensDetails
      - `audio_tokens` integer, nullable
      - `cached_tokens` integer, nullable

## Other responses

- `422` — Validation Error

## Changes

- **2025-08-18** `f788f74915ca` — 1 info
  - endpoint added
- **2025-08-18** `7e70f823f200` — 1 breaking
  - api path removed without deprecation
- **2025-08-18** `f788f74915ca` — 1 info
  - endpoint added
- **2025-08-18** `107fbf0e4f3e` — 1 breaking
  - api path removed without deprecation
- **2025-08-18** `f788f74915ca` — 1 info
  - endpoint added

[Full history](https://skmtc.dev/dedalus-labs/apis/dedalus-api/changes/v1/chat/post.md)

---

[API](https://skmtc.dev/dedalus-labs/apis/dedalus-api.md) · [All operations](https://skmtc.dev/dedalus-labs/apis/dedalus-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/dedalus-labs/dedalus-api/revisions/f788f74915ca/schema)