# Create a response

:::::::::operation{method="POST" path="/api/2.0/genie/one/responses" md="/genie-one/v1/create-response.md"}

Sends a question to Genie One and streams the response over Server-Sent Events
(SSE). Omit `conversation_id` to start a conversation, or provide it to continue
an existing Genie One conversation. The workspace must have Genie One API access
enabled.

Save the `response.id` and `response.conversation_id` from `response.created`.
Use them to [get the response](/api/genie-one/v1/get-response) if the stream
disconnects. Disconnecting does not cancel an accepted response. Repeating a
POST can create another response.

API scopes: `genie`

## Request body

Send only the fields listed below. Unknown request fields return
`INVALID_PARAMETER_VALUE`.

::::::::attribute{name="input" type="string or array of object" required}
The question. Send a nonblank string, or an array containing exactly one user
message. In the array form, set `role` to `"user"`; the message's `type` can be
omitted or set to `"message"`.

The message's `content` can be a nonblank string or an array of one or more
`{"type": "input_text", "text": "..."}` parts. Each text part must be
nonblank. The combined text must not exceed 25,000 UTF-8 bytes. Other message
roles and content types are not supported.
::::::::

::::::::attribute{name="conversation_id" type="string"}
An existing Genie One conversation to continue. Omit to create a conversation.
The caller must be allowed to add responses to it. The ID can contain ASCII
letters, digits, hyphens, and underscores, up to 128 bytes.
::::::::

::::::::attribute{name="warehouse_id" type="string"}
The SQL warehouse to use if Genie One runs a query. If omitted, Genie One
resolves the warehouse.
::::::::

::::::::attribute{name="user_timezone" type="string"}
An IANA time zone, such as `America/Los_Angeles`. The value must not exceed 255
UTF-8 bytes.
::::::::

::::::::attribute{name="enable_viz" type="boolean" default="false"}
Omit this field or set it to `false`. Requests with `true` are rejected;
visualization payloads are not available through this API.
::::::::

## Response events

A successful request returns `text/event-stream`. Each JSON event has a `type`
matching the SSE `event` name and a `sequence_number` that increases from zero.
Output item events also have a zero-based `output_index`. A terminal response
event is followed by `data: [DONE]`. Commentary can stream before completion.
Final answer item events can arrive just before the terminal response event.

::::::::attribute{name="response.created" type="event"}
The response has been accepted. `data.response.status` is `"in_progress"` and
`data.response.output` is empty. Save its response and conversation IDs.
::::::::

::::::::attribute{name="response.output_item.added" type="event"}
A public assistant message is added. `data.item` is the message and
`data.output_index` is its position in the response output.
::::::::

::::::::attribute{name="response.output_item.updated" type="event"}
A subsequent snapshot of an existing public assistant message. The item has the
same shape as `response.output_item.added`. Replace the previous item at its
`output_index` rather than appending its text.
::::::::

::::::::attribute{name="response.output_item.done" type="event"}
A public assistant message reaches its final state. The item appears in the
terminal response's `output` array.
::::::::

::::::::attribute{name="response.completed" type="event"}
Terminal success. `data.response.status` is `"completed"` and its `output`
contains the public assistant messages.
::::::::

::::::::attribute{name="response.failed" type="event"}
Terminal failure after the response was accepted. `data.response.status` is
`"failed"`. A sanitized `error` object is included when failure details are
available.
::::::::

::::::::attribute{name="response.incomplete" type="event"}
The response stopped without completing. `data.response.status` is
`"incomplete"`.
::::::::

## Response

The `response.created` and terminal events carry a
[Response object](/api/genie-one/v1/response#object). That page describes its
nested message, citation, and error fields.

::::::::attribute{name="object" type="string" enum="response"}
Always `"response"`.
::::::::

::::::::attribute{name="id" type="string"}
Opaque response ID.
::::::::

::::::::attribute{name="model" type="string" enum="genie-one"}
Always `"genie-one"`.
::::::::

::::::::attribute{name="status" type="string" enum="in_progress,completed,failed,incomplete"}
The response status.
::::::::

::::::::attribute{name="output" type="array of object"}
Public assistant messages, in output order. Each item has `type: "message"`, an
opaque `id`, `role: "assistant"`, a `phase` of `"commentary"` or
`"final_answer"`, and `content`. A message can also have a `status`,
`create_time`, and `complete_time`. The timestamps are RFC 3339 strings.

Each `content` part has `type: "output_text"`, Markdown-capable `text`, and an
`annotations` array. Supported source annotations have `type: "asset"`,
`title`, `asset_type`, `identifier`, and a one-based citation `index`.
An `identifier` can be an asset ID, volume path, or source URL. The citation
`index` is a marker number, not a character offset or an array position; gaps
are possible when unsupported citations are omitted.

Internal reasoning, tool calls, tool result items, and visualization payloads
are not output items. An answer can include a Markdown table.
::::::::

::::::::attribute{name="conversation_id" type="string"}
The conversation containing this response.
::::::::

::::::::attribute{name="create_time" type="string"}
The response creation time as an RFC 3339 timestamp, when available.
::::::::

::::::::attribute{name="previous_response_id" type="string"}
The preceding response ID, when this response follows another response.
::::::::

::::::::attribute{name="error" type="object"}
Sanitized failure information on a failed response. When present, it has `type`
and `message`, and can include `code` and `retryable`.
::::::::

## Errors

Requests rejected before streaming return a JSON error with an HTTP status.
After a response is accepted, execution failures appear in the SSE stream as
`response.failed`, even though the HTTP status is `200`.

| HTTP status | Error code | Description |
|---|---|---|
| `400` | `INVALID_PARAMETER_VALUE` | The request body is malformed or uses an unknown field, unsupported input, or unsupported option. |
| `401` | `UNAUTHENTICATED` | An authenticated identity is required. |
| `403` | `PERMISSION_DENIED` | The caller cannot add a response to the conversation. |
| `404` | `NOT_FOUND` | The API is not enabled for the workspace, or the conversation or specified warehouse is unavailable. |
| `409` | `ALREADY_EXISTS` | Another response is active in the conversation. Retry after it finishes. |
| `429` | `RESOURCE_EXHAUSTED` | The request was rate limited. |
| `500` | `INTERNAL_ERROR` | An unexpected server error occurred. |

:::sample{label="Request" language="json"}
```json
{
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "How did revenue change last quarter?"
        }
      ]
    }
  ]
}
```
:::

:::sample{label="Response" language="text"}
```text
event: response.created
data: {"type":"response.created","sequence_number":0,"response":{"object":"response","id":"9f7c84c6d3af4ae8ac5cc43590a15366","model":"genie-one","status":"in_progress","output":[],"conversation_id":"6a34b9a50cb4435da7c463130c9d42c1","create_time":"2026-10-19T10:01:00Z"}}

event: response.output_item.added
data: {"type":"response.output_item.added","sequence_number":1,"output_index":0,"item":{"type":"message","id":"2b6aa43956be4fe89ff68ccb565a214d","role":"assistant","status":"in_progress","phase":"final_answer","create_time":"2026-10-19T10:01:01Z","content":[{"type":"output_text","text":"Revenue increased 12% last quarter.","annotations":[]}]}}

event: response.output_item.done
data: {"type":"response.output_item.done","sequence_number":2,"output_index":0,"item":{"type":"message","id":"2b6aa43956be4fe89ff68ccb565a214d","role":"assistant","status":"completed","phase":"final_answer","create_time":"2026-10-19T10:01:01Z","complete_time":"2026-10-19T10:01:06Z","content":[{"type":"output_text","text":"Revenue increased 12% last quarter.","annotations":[]}]}}

event: response.completed
data: {"type":"response.completed","sequence_number":3,"response":{"object":"response","id":"9f7c84c6d3af4ae8ac5cc43590a15366","model":"genie-one","status":"completed","output":[{"type":"message","id":"2b6aa43956be4fe89ff68ccb565a214d","role":"assistant","status":"completed","phase":"final_answer","create_time":"2026-10-19T10:01:01Z","complete_time":"2026-10-19T10:01:06Z","content":[{"type":"output_text","text":"Revenue increased 12% last quarter.","annotations":[]}]}],"conversation_id":"6a34b9a50cb4435da7c463130c9d42c1","create_time":"2026-10-19T10:01:00Z"}}

data: [DONE]
```
:::

:::::::::