---
title: "Create a response"
method: POST
path: "/responses"
tags: ["Chat"]
---

# Create a response

`POST /responses`

## Request

- Base URL: `https://app.usehindsight.com/api/v1`
- URL: `https://app.usehindsight.com/api/v1/responses`
- Auth: HTTP bearer

Send a message and receive an AI-generated response with citations from your competitive intelligence data.
Hindsight automatically orchestrates multiple searches across deals, competitors, and knowledge base to provide comprehensive answers.

## Request body

- ChatCompletionRequest
  - `messages` Message[], required: The conversation messages
    - `role` 'user' | 'assistant' | 'system', required: The role of the message author
    - `content` string, required: The content of the message
  - `stream` boolean: Whether to stream the response using Server-Sent Events

## Response `200`

Successful response

- ChatCompletionResponse
  - `message` object
    - `role` 'assistant'
    - `content` string: The AI-generated response with inline citations
    - `citations` Citation[]: Source documents referenced in the response
      - `document_id` string: Unique identifier for the source document
      - `document_name` string: Name of the source document
      - `deal_id` string, nullable: Associated deal ID, if applicable
      - `deal_name` string, nullable: Associated deal name, if applicable
      - `url` string, uri: URL to view the document in Hindsight
      - `excerpt` string: Relevant excerpt from the document
  - `tool_calls` string[]: The internal tools that were called to generate the response

## Other responses

- `400`: Bad request - invalid parameters
- `401`: Unauthorized - invalid or missing API key
- `429`: Too many requests - rate limit or applicable usage quota exceeded
- `500`: Internal server error

---

[API](https://skmtc.dev/usehindsight/apis/hindsight-api.md) - [All operations](https://skmtc.dev/usehindsight/apis/hindsight-api/llms.txt) - [OpenAPI document](https://skmtc.dev/usehindsight/apis/hindsight-api/revisions/97371a7da857?raw)