Create conversation

Available in VPC

LLM generates interactive sentences for user queries.

Request

This section describes the request format. The method and URI are as follows:

Request headers

For information about the headers common to all RAG APIs, see RAG request headers.

Request path parameters

The following describes the parameters.

Request body

You can include the following data in the body of your request:

messages

This is an array of messages that provide context for the conversation.

RETRIEVAL parameter

These are configuration parameters for the document search block (blocks.RETRIEVAL.type = "RETRIEVAL").

filters

GENERATOR parameter

These are configuration parameters for the answer generation block (blocks.GENERATOR.type = "LLM").

Request example

The request example is as follows:

curl --location --request POST 'https://kr-pub-gateway.rag.naverncp.com/api/v1/svc/{serviceId}/conversation' \
--header 'Authorization: Bearer {apiKey}' \
--header 'Content-Type: application/json' \
--header 'Accept: text/event-stream' \
--data '{
  "serviceId": "{serviceId}",
  "messages": [
    {
      "role": "user",
      "content": "I'm curious about NAVER's technology."
    },
    {
      "role": "assistant",
      "content": "NAVER has a special technology that can digitally recreate the look of a city, so photos taken by drones can be shown in three dimensions on your computer as if they were real!"
    },
    {
      "role": "user",
      "content": "What do people call this technology?"
    }
  ],
  "blocks": {
    "RETRIEVAL": {
      "type": "RETRIEVAL",
      "parameters": {
        "k": 1,
        "fileName": "leap-25.docx",
        "chunkSize": 256,
        "overlapSize": 128,
        "filters": [
          {
            "term": {
              "extra.bucket.keyword": {
                "value": "clova-ai"
              }
            }
          },
          {
            "term": {
              "file_name": "leap-25.docx"
            }
          },
          {
            "range": {
              "extra.size": {
                "lte": 1000000
              }
            }
          }
        ]
      }
    },
    "GENERATOR": {
      "type": "LLM",
      "parameters": {
        "chatModel": "HyperClovaX",
        "systemPrompt": "Answer at the level of an elementary school student.",
        "llmParameters": {
          "model": "HCX-005",
          "clovaStudioApiKey": "{clovaStudioApiKey}",
          "temperature": 0.50,
          "topK": 64,
          "topP": 0.50,
          "maxTokens": 1024
        }
      }
    }
  },
  "citation": {
    "enabled": true
  },
  "verbose": true
}

Response

This section describes the response format.

Response headers

The following describes the response headers.

Response body

The response body includes the following data:

data.results

Each element in the array represents a sequential RAG processing step.

RETRIEVAL parameter

data.references

This is the citation information used to generate the answer.

data

Response example

The response example is as follows:

{
    "code": 200,
    "message": null,
    "data": {
        "results": [
            {
                "blockId": "START",
                "value": "What do people call this technology?"
            },
            {
                "blockId": "QUERY_REWRITE",
                "value": "What is the name people use for NAVER's technology?"
            },
            {
                "blockId": "RETRIEVAL",
                "value": [
                    {
                        "docId": "c69cd98c0674e1a8a814",
                        "fileName": "leap-25.docx",
                        "score": 0.04168701171875,
                        "rank": 1,
                        "text": "NAVER has a unique technology that can quickly and accurately create digital twin data for entire megacities. Using aerial photography and photogrammetry, NAVER can quickly and accurately create megacity-scale digital twin data, which is then restored to life-like three-dimensional space using AI technology. In Korea, NAVER already offers a VR service through NAVER Pay that allows users to view real estate listings without having to visit the actual property.",
                        "start_offset": 4025,
                        "end_offset": 4258,
                        "chunk_no": 1,
                        "page_no": 0
                    }
                ]
            },
            {
                "blockId": "CONDITIONAL",
                "value": "branch1"
            },
            {
                "blockId": "GENERATOR",
                "value": "This technology that NAVER has is called Digital Twin. A digital twin is a technology that creates an exact replica of a physical object in the real world in a virtual world so that it can be monitored and controlled in real time. In other words, it is like a twin of a real space in a computer.\n\nFor example, if you create a digital twin of the neighborhood or school building where you live, you can look around the building on your computer screen without actually being there, walk around the streets and check out the surrounding facilities. It can also be used to predict future situations or solve problems by simulating weather changes or traffic conditions.\n\nNAVER is developing new services in various fields using this digital twin technology. For example, a virtual fitting room that lets you try on clothes while shopping online, or a feature that lets you explore the interior of your home in 3D and decorate it.\n\nDigital twin technology is a wonderful tool that makes our daily lives easier and sparks our imagination. As it continues to evolve, we can expect to see it used in even more ways."
            }
        ],
        "references": [
            {
                "name": "RETRIEVAL",
                "data": [
                    {
                        "docId": "c69cd98c0674e1a8a814",
                        "fileName": "leap-25.docx",
                        "text": "NAVER has a unique technology that can quickly and accurately create digital twin data for entire megacities. Using aerial photography and photogrammetry, NAVER can quickly and accurately create megacity-scale digital twin data, which is then restored to life-like three-dimensional space using AI technology. In Korea, NAVER already offers a VR service through NAVER Pay that allows users to view real estate listings without having to visit the actual property.",
                        "startOffset": 4025,
                        "endOffset": 4258,
                        "chunkNo": 1,
                        "pageNo": 0,
                        "extra": {
                            "bucket": "clova-ai",
                            "size": 966060,
                            "last_modified": "2025-07-02T10:17:19+00:00",
                            "key": "leap-25.docx"
                        }
                    }
                ]
            }
        ],
        "rateLimit": {
            "limitRequests": null,
            "remainingRequests": null,
            "resetRequests": null,
            "limitTokens": "60000",
            "remainingTokens": "58324",
            "resetTokens": "59s"
        }
    }
}

Response stream

Server-Sent Events (SSE) provides real-time streaming responses. Each SSE message consists of the following format. (Events are separated by blank lines.)

event: [event_type]
data: [json_data]

The Create conversation API supports five event types: step, ping, token, result, and error.

• step: Output of block-by-block processing results before generating answers (if verbose = true).
• ping: Output data to prevent read timeouts while waiting before generating the answer (every second until the answer is generated).
• token: Output the token of the answer being generated in real time.
• result: Output the final answer.
• error: Output when an error occurs during answer generation.

Response headers

The following describes the response headers.

Response body

The response body differs depending on the event type.

step event

The following describes the step events.

RETRIEVAL parameter

ping, token, result events

The following describes the ping, token, and result events.

references

data

error event

The following describes the error events.

Response status codes

For information about the HTTP status codes common to all RAG APIs, see RAG response status codes.

Response example

The response example is as follows:

event: step
data: {
    "blockName": "START",
    "blockResult": "What do people call this technology?"
}

event: step
data: {
    "blockName": "QUERY_REWRITE",
    "blockResult": "What is the name people use for NAVER's technology?"
}

event: step
data: {
    "blockName": "RETRIEVAL",
    "blockResult": [
        {
            "docId": "{docId}",
            "fileName": "leap-25.docx",
            "score": 0.04168701171875,
            "rank": 1,
            "text": "NAVER has a unique technology that can quickly and accurately create digital twin data for entire megacities. Using aerial photography and photogrammetry, NAVER can quickly and accurately create megacity-scale digital twin data, which is then restored to life-like three-dimensional space using AI technology. In Korea, NAVER already offers a VR service through NAVER Pay that allows users to view real estate listings without having to visit the actual property.",
            "start_offset": 4025,
            "end_offset": 4258,
            "chunk_no": 1,
            "page_no": 0
        }
    ]
}

event: step
data: {
    "blockName": "CONDITIONAL",
    "blockResult": "branch1"
}

event: ping
data: {
    "message": {
        "role": "assistant",
        "content": "",
        "totalContent": ""
    },
    "status": "IN_PROGRESS",
    "references": [],
    "rateLimit": null,
    "metadata": {}
}

...

event: token
data: {
    "message": {
        "role": "assistant",
        "content": " Digital",
        "totalContent": "This technology that NAVER has is called Digital Twin. Digital"
    },
    "status": "IN_PROGRESS",
    "references": [],
    "rateLimit": null,
    "metadata": {}
}

...

event: result
data: {
    "message": {
        "role": "assistant",
        "content": "This technology that NAVER has is called Digital Twin.[†1] A digital twin is an exact replica of a physical object in the real world in the virtual world, which allows us to perform various simulations and analyses to help us make decisions.\n\nFor example, if we draw a house on a piece of paper, we draw a picture that looks exactly like the house we will build. Then we can plan and experiment with different things on it, like if we want to know how water flows when it rains, we can make it rain on the drawing and observe the results.\n\nThis virtual world can help us save time and money by allowing us to test different situations before we build a real building or city. It can also help us manage real buildings. For example, we can monitor whether the machines in the building are working properly or using energy efficiently, so we can take action before something goes wrong.\n\nNAVER is utilizing this digital twin technology to recreate various regions of Korea in the virtual world and develop various services based on them.[†1] This means that we will be able to see and experience information about the region on our computers or smartphones without having to go there. It's really exciting, right?",
        "totalContent": "This technology that NAVER has is called Digital Twin.[†1] A digital twin is an exact replica of a physical object in the real world in the virtual world, which allows us to perform various simulations and analyses to help us make decisions.\n\nFor example, if we draw a house on a piece of paper, we draw a picture that looks exactly like the house we will build. Then we can plan and experiment with different things on it, like if we want to know how water flows when it rains, we can make it rain on the drawing and observe the results.\n\nThis virtual world can help us save time and money by allowing us to test different situations before we build a real building or city. It can also help us manage real buildings. For example, we can monitor whether the machines in the building are working properly or using energy efficiently, so we can take action before something goes wrong.\n\nNAVER is utilizing this digital twin technology to recreate various regions of Korea in the virtual world and develop various services based on them.[†1] This means that we will be able to see and experience information about the region on our computers or smartphones without having to go there. It's really exciting, right?"
    },
    "status": "COMPLETE",
    "references": [
        {
            "name": "RETRIEVAL",
            "data": [
                {
                    "docId": "12345",
                    "fileName": "leap-25.docx",
                    "text": "NAVER has a unique technology that can quickly and accurately create digital twin data for entire megacities. Using aerial photography and photogrammetry, NAVER can quickly and accurately create megacity-scale digital twin data, which is then restored to life-like three-dimensional space using AI technology. In Korea, NAVER already offers a VR service through NAVER Pay that allows users to view real estate listings without having to visit the actual property.",
                    "startOffset": 4025,
                    "endOffset": 4258,
                    "chunkNo": 1,
                    "pageNo": 0,
                    "extra": {
                        "bucket": "clova-ai",
                        "size": 966060,
                        "last_modified": "2025-07-02T10:17:19+00:00",
                        "key": "leap-25.docx"
                    }
                }
            ]
        }
    ],
    "rateLimit": {
        "limitRequests": null,
        "remainingRequests": null,
        "resetRequests": null,
        "limitTokens": "60000",
        "remainingTokens": "56648",
        "resetTokens": "28s"
    },
    "metadata": {
        "chatModel": "HyperClovaX",
        "modelName": "HCX-005",
        "inputTokens": 267,
        "outputTokens": 262,
        "totalTokens": 529
    }
}