---
title: "Create Response"
method: POST
path: "/v1/responses"
tags: ["responses-harmonized.openapi_other"]
---

# Create Response

`POST /v1/responses`

Creates a model response, optionally interacting with custom tools via the Model Context Protocol (MCP). This endpoint supports conversational continuation and streaming.

Explore our cookbooks for detailed examples:

- [Basic MCP Usage](https://github.com/fw-ai/cookbook/blob/main/learn/response-api/fireworks_mcp_examples.ipynb)
- [Streaming with MCP](https://github.com/fw-ai/cookbook/blob/main/learn/response-api/fireworks_mcp_with_streaming.ipynb)
- [Conversational History with `previous_response_id`](https://github.com/fw-ai/cookbook/blob/main/learn/response-api/fireworks_previous_response_cookbook.ipynb)
- [Basic Streaming](https://github.com/fw-ai/cookbook/blob/main/learn/response-api/fireworks_streaming_example.ipynb)
- [Controlling Response Storage](https://github.com/fw-ai/cookbook/blob/main/learn/response-api/mcp_server_with_store_false_argument.ipynb)

## Request body

- CreateResponse — Request model for creating a new response. This model defines all the parameters needed to create a new model response, including model configuration, input data, tool definitions, and conversation continuation.
  - `model` string, required — The model to use for generating the response. Example: `accounts/<ACCOUNT_ID>/models/<MODEL_ID>`.
  - `input` union, required — The input to the model. Can be a simple text string or a list of message objects for complex inputs with multiple content types.
    - string
    - object[]
  - `previous_response_id` string, nullable — The ID of a previous response to continue the conversation from. When provided, the conversation history from that response will be automatically loaded.
  - `instructions` string, nullable — System instructions that guide the model's behavior throughout the conversation. Similar to a system message.
  - `max_output_tokens` integer, nullable — The maximum number of tokens that can be generated in the response. Must be at least 1. If not specified, the model will generate up to its maximum context length.
  - `max_tool_calls` integer, nullable — The maximum number of tool calls allowed in a single response. Useful for controlling costs and limiting tool execution. Must be at least 1.
  - `metadata` object, nullable — Set of up to 16 key-value pairs that can be attached to the response. Useful for storing additional information in a structured format.
  - `parallel_tool_calls` boolean, nullable — Whether to enable parallel function calling during tool use. When true, the model can call multiple tools simultaneously. Default is True.
  - `reasoning` object, nullable — Configuration for reasoning output. When enabled, the model will return its reasoning process along with the response.
  - `store` boolean, nullable — Whether to store the response. When set to false, the response will not be stored and will not be retrievable via the API. This is useful for ephemeral or sensitive data. See an example in our [Controlling Response Storage cookbook](https://github.com/fw-ai/cookbook/blob/main/learn/response-api/mcp_server_with_store_false_argument.ipynb). Default is True.
  - `stream` boolean, nullable — Whether to stream the response back as Server-Sent Events (SSE). When true, tokens are sent incrementally as they are generated. Default is False.
  - `temperature` number, nullable — The sampling temperature to use, between 0 and 2. Higher values like 0.8 make output more random, while lower values like 0.2 make it more focused and deterministic. Default is 1.0.
  - `text` object, nullable — Text generation configuration parameters. Used for advanced text generation settings.
  - `tool_choice` union — Controls which (if any) tool the model should use. Can be 'none' (never call tools), 'auto' (model decides), 'required' (must call at least one tool), or an object specifying a particular tool to call. Default is 'auto'.
    - string
    - object
  - `tools` object[], nullable — A list of MCP tools the model may call. See our cookbooks for examples on [basic MCP usage](https://github.com/fw-ai/cookbook/blob/main/learn/response-api/fireworks_mcp_examples.ipynb) and [streaming with MCP](https://github.com/fw-ai/cookbook/blob/main/learn/response-api/fireworks_mcp_with_streaming.ipynb).
  - `top_p` number, nullable — An alternative to temperature sampling, called nucleus sampling, where the model considers the results of tokens with top_p probability mass. So 0.1 means only tokens comprising the top 10% probability mass are considered. Default is 1.0. We generally recommend altering this or temperature but not both.
  - `truncation` string, nullable — The truncation strategy to use for the context when it exceeds the model's maximum length. Can be 'auto' (automatically truncate) or 'disabled' (return error if context too long). Default is 'disabled'.
  - `user` string, nullable — A unique identifier representing your end-user, which can help Fireworks to monitor and detect abuse. This can be a username, email, or any other unique identifier.

## Response `200`

Successful Response

- Response — Represents a response object returned from the API. A response includes the model output, token usage, configuration parameters, and metadata about the conversation state.
  - `id` string, nullable — The unique identifier of the response. Will be None if store=False.
  - `object` string — The object type, which is always 'response'.
  - `created_at` integer, required — The Unix timestamp (in seconds) when the response was created.
  - `status` string, required — The status of the response. Can be 'completed', 'in_progress', 'incomplete', 'failed', or 'cancelled'.
  - `model` string, required — The model used to generate the response (e.g., `accounts/<ACCOUNT_ID>/models/<MODEL_ID>`).
  - `output` union[], required — An array of output items produced by the model. Can contain messages, tool calls, and tool outputs.
    - union
      - Message — Represents a message in a conversation.
        - `id` string, required — The unique identifier of the message.
        - `type` string — The object type, always 'message'.
        - `role` string, required — The role of the message sender. Can be 'user', 'assistant', or 'system'.
        - `content` MessageContent[], required — An array of content parts that make up the message. Each part has a type and associated data.
          - `type` string, required — The type of the content part. Can be 'input_text', 'output_text', 'image', etc.
          - `text` string, nullable — The text content, if applicable.
        - `status` string, required — The status of the message. Can be 'in_progress' or 'completed'.
      - ToolCall — Represents a tool call made by the model.
        - `id` string, required — The unique identifier of the tool call.
        - `type` string, required — The type of tool call. Can be 'function_call' or 'mcp_call'.
        - `call_id` string, nullable — The call ID for function calls, used to match with function_call_output.
        - `name` string, nullable — The name of the function to call (for function_call type).
        - `arguments` string, nullable — The arguments for the function call as a JSON string (for function_call type).
        - `status` string, nullable — The status of the tool call. Can be 'in_progress', 'completed', or 'incomplete'.
        - `function` object, nullable — The function definition for function tool calls. Contains 'name' and 'arguments' keys. Deprecated for function_call type.
        - `mcp` object, nullable — The MCP (Model Context Protocol) tool call definition for MCP tool calls.
      - ToolOutput — Represents the output/result of a tool call.
        - `type` string — The object type, always 'tool_output'.
        - `tool_call_id` string, required — The ID of the tool call that this output corresponds to.
        - `output` string, required — The output content from the tool execution.
  - `previous_response_id` string, nullable — The ID of the previous response in the conversation, if this response continues a conversation.
  - `usage` object, nullable — Token usage information for the request. Contains 'prompt_tokens', 'completion_tokens', and 'total_tokens'.
  - `error` object, nullable — Error information if the response failed. Contains 'type', 'code', and 'message' fields.
  - `incomplete_details` object, nullable — Details about why the response is incomplete, if status is 'incomplete'. Contains 'reason' field which can be 'max_output_tokens', 'max_tool_calls', or 'content_filter'.
  - `instructions` string, nullable — System instructions that guide the model's behavior. Similar to a system message.
  - `max_output_tokens` integer, nullable — The maximum number of tokens that can be generated in the response. Must be at least 1.
  - `max_tool_calls` integer, nullable — The maximum number of tool calls allowed in a single response. Must be at least 1.
  - `parallel_tool_calls` boolean — Whether to enable parallel function calling during tool use. Default is True.
  - `reasoning` object, nullable — Reasoning output from the model, if reasoning is enabled. Contains 'content' and 'type' fields.
  - `store` boolean, nullable — Whether to store this response for future retrieval. If False, the response will not be persisted and previous_response_id cannot reference it. Default is True.
  - `temperature` number — The sampling temperature to use, between 0 and 2. Higher values like 0.8 make output more random, while lower values like 0.2 make it more focused and deterministic. Default is 1.0.
  - `text` object, nullable — Text generation configuration parameters, if applicable.
  - `tool_choice` union — Controls which (if any) tool the model should use. Can be 'none', 'auto', 'required', or an object specifying a particular tool. Default is 'auto'.
    - string
    - object
  - `tools` object[] — A list of tools the model may call. Each tool is defined with a type and function specification following the OpenAI tool format. Supports 'function', 'mcp', 'sse', and 'python' tool types.
  - `top_p` number — An alternative to temperature sampling, called nucleus sampling, where the model considers the results of tokens with top_p probability mass. So 0.1 means only tokens comprising the top 10% probability mass are considered. Default is 1.0.
  - `truncation` string — The truncation strategy to use for the context. Can be 'auto' or 'disabled'. Default is 'disabled'.
  - `user` string, nullable — A unique identifier representing your end-user, which can help Fireworks to monitor and detect abuse.
  - `metadata` object, nullable — Set of up to 16 key-value pairs that can be attached to the response. Useful for storing additional information about the response in a structured format.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/fireworks/apis/fireworks-ai-anthropic-compatible-messages-api.md) · [All operations](https://skmtc.net/fireworks/apis/fireworks-ai-anthropic-compatible-messages-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fireworks/fireworks-ai-anthropic-compatible-messages-api/versions/954d6bc5d922/schema)