---
title: "Create Response"
method: POST
path: "/responses"
tags: ["responses"]
---

# Create Response

`POST /responses`

Create a response. This will generate an LLM or agentic response. At this time the only supported model is `deep-search`. Responses may be streamed or returned synchronously. The `retrieve` tool is currently the only supported tool, more tools will be added in the future. A single partition may be provided in the retrieve tool. If omitted the `default` partition is used.

## Request body

- Request
  - `input` string, required — The text used to generate the response. Generally a question or a query.
  - `instructions` string, nullable — The instructions inserted in the prompt. For this agent, the instructions are injected during search related steps.
  - `tools` Tool[] — The tools available to the agent. Currently the only tool is retrieve. The `default` partition is used by default unless an other partition is specified.
    - `type` 'retrieve', required
    - `partitions` string[], required
  - `model` 'deep-search' — The model to use for the agent. Currently the only model is deep-search.
  - `reasoning` Reasoning
    - `effort` 'low' | 'medium' | 'high', required
    - `summary` unknown
  - `stream` boolean — Whether to stream the response

## Response `200`

Successful Response

- Response
  - `id` string, required
  - `object` 'response'
  - `created_at` integer, required
  - `status` 'completed' | 'failed' | 'in_progress' | 'cancelled', required
  - `error` string, nullable
  - `incomplete_details` unknown
  - `instructions` string, nullable
  - `max_output_tokens` unknown
  - `model` 'deep-search'
  - `output` union[], required
    - union
      - ResponseOutputMessage
        - `type` 'message'
        - `id` string, required
        - `role` 'assistant'
        - `content` ResponseContent[], required
          - `type` 'text'
          - `text` string, required
          - `annotations` object[]
      - ReasoningOutput
        - `id` string, required — The unique ID of the reasoning output.
        - `summary` ReasoningSummary[], required — The summary of the reasoning.
          - `summary` string, required — The summary of the reasoning.
          - `type` 'summary'
        - `type` 'reasoning'
        - `content` ReasoningText[], required — The content of the reasoning.
          - `text` string, required — The text of the reasoning.
          - `type` 'reasoning_text'
        - `encrypted_content` string, required — The encrypted content of the reasoning output.
        - `status` 'in_progress' | 'completed' | 'incomplete'
      - CodeInterpreterOutput
        - `id` string, required — The unique ID of the code interpreter tool call.
        - `code` string, required — The code executed by the code interpreter.
        - `container_id` string, required — The ID of the container used to run the code.
        - `outputs` CodeInterpreterOutputLogs[], required — The outputs generated by the code interpreter, such as logs or images.
          - `logs` string, required — The logs output from the code interpreter.
          - `type` 'logs'
        - `type` 'code_interpreter_output'
        - `status` 'in_progress' | 'interpreting' | 'completed' | 'incomplete' | 'failed'
      - FileSearchOutput
        - `id` string, required
        - `queries` string[], required — The queries used to search for files.
        - `status` 'in_progress' | 'searching' | 'incomplete' | 'completed' | 'failed'
        - `type` 'file_search_call', required
        - `results` FileSearchResult[], required — The results of the file search tool call.
          - `file_id` string, required — The unique ID of the document.
          - `filename` string, required — The name of the document.
          - `score` number, required — The relevance score of the chunk - a value between 0 and 1.
          - `text` string, required — The text content of the chunk.
          - `attributes` object, required — The attributes of the chunk.
  - `output_parsed` FinalAnswer
    - `text` string, required — The final answer to the question.
    - `evidence` union[] — The evidence used to derive the answer.
      - union
        - CodeInterpreterEvidence
          - `type` 'code_interpreter'
          - `text` string, required
          - `code` string, required — The code that was executed.
          - `code_issue` string, required — The issue that the code was written to solve.
          - `code_result` string, required — The result of the code that was executed.
        - RagieEvidence
          - `type` 'ragie'
          - `text` string, required
          - `id` string, required — The chunk id of the evidence.
          - `index` integer, required — The index of the chunk in the document.
          - `document_id` string, required — The document id of the document containing the chunk being used as evidence.
          - `document_name` string, required — The name of the document that contains the chunk being used as evidence.
          - `metadata` object — The metadata of the chunk being used as evidence.
          - `document_metadata` object — The metadata of the document that contains the evidence.
          - `links` object — The links to the evidence.
    - `steps` union[] — The steps that led to the answer.
      - union
        - AnswerStep
          - `type` 'answer'
          - `think` string, required
          - `current_question` string, required
          - `errored` boolean
          - `other_resolved_question_ids` string[] — A list of question ids that are no longer relevant to the current answer referenced by their IDs.
          - `answer` Answer, required
            - `text` string, required — An answer to a question.
            - `evidence` string[] — The evidence used to derive the answer.
        - SearchStep
          - `type` 'base_search'
          - `think` string, required
          - `current_question` string, required
          - `errored` boolean
          - `search` Search, required
            - `search_requests` string[], required
        - SearchStepWithQueryDetails
          - `type` 'search'
          - `think` string, required
          - `current_question` string, required
          - `errored` boolean
          - `search` Search, required
            - `search_requests` string[], required
          - `query_details` QueryDetails[]
            - `query` string, required
            - `search_effort` 'low' | 'medium' | 'high', required
            - `metadata_filter` object, required
            - `search_results` RagieEvidence[], required
              - …
          - `search_log` string — A log of the search results you found.
        - PlanStep
          - `type` 'plan'
          - `think` string, required
          - `current_question` string, required
          - `errored` boolean
          - `questions_to_answer` string[] — The questions that need to be answered to answer the original question.
        - CodeStep
          - `type` 'code'
          - `think` string, required
          - `current_question` string, required
          - `errored` boolean
          - `code_issue` string, required — The natural language description of the code issue you need to solve.
          - `code` string — The code you generated to solve the code issue.
          - `code_result` string — The result of the code you generated after executing it.
        - SurrenderStep
          - `type` 'surrender'
          - `think` string, required
          - `current_question` string, required
          - `errored` boolean
          - `partial_answer` Answer, required
            - `text` string, required — An answer to a question.
            - `evidence` string[] — The evidence used to derive the answer.
        - EvaluatedAnswerStep
          - `type` 'evaluated_answer'
          - `think` string, required
          - `current_question` string, required
          - `errored` boolean
          - `answer` Answer, required
            - `text` string, required — An answer to a question.
            - `evidence` string[] — The evidence used to derive the answer.
          - `other_resolved_question_ids` string[] — A list of questions ids that are no longer relevant to the current answer referenced by their IDs.
          - `eval_passed` boolean, required
          - `eval_reason` string, required
        - FailedStep
          - `type` 'failed'
          - `think` string, required
          - `current_question` string, required
          - `errored` boolean
    - `usage` AgentHoppsModelsModelsUsage
      - `models` ModelUsage[]
        - `model_name` string, required
        - `input_tokens` integer, required
        - `output_tokens` integer, required
  - `tools` Tool[], required
    - `type` 'retrieve', required
    - `partitions` string[], required
  - `reasoning` Reasoning, required
    - `effort` 'low' | 'medium' | 'high', required
    - `summary` unknown
  - `parallel_tool_calls` boolean
  - `store` boolean
  - `temperature` number
  - `previous_response_id` string, nullable
  - `tool_choice` 'auto'
  - `top_p` number
  - `truncation` 'disabled'
  - `usage` RagieApiSchemaResponseUsage, required
    - `input_tokens` integer, required
    - `input_token_details` InputTokenDetails
      - `cached_tokens` integer
    - `output_tokens` integer, required
    - `output_token_details` OutputTokenDetails
      - `reasoning_tokens` integer
    - `total_tokens` integer, required
  - `user` unknown
  - `metadata` object

## Other responses

- `401` — Unauthorized
- `402` — Payment Required
- `422` — Validation Error
- `429` — Too Many Requests
- `500` — Internal Server Error

---

[API](https://skmtc.net/ragie/apis/ragie-api.md) · [All operations](https://skmtc.net/ragie/apis/ragie-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ragie/ragie-api/versions/ffdf960539ca/schema)