Create Response

POST

responses

curl -X POST https://app.usehindsight.com/api/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What security objections have we encountered with Enterprise customers?"
      }
    ],
    "stream": false
  }'

const response = await fetch('https://app.usehindsight.com/api/v1/responses', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    messages: [{ role: 'user', content: 'What security objections have we encountered?' }],
    stream: false
  })
});

const data = await response.json();
console.log(data.message.content);

import requests

response = requests.post(
    'https://app.usehindsight.com/api/v1/responses',
    headers={
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    },
    json={
        'messages': [{'role': 'user', 'content': 'What security objections have we encountered?'}],
        'stream': False
    }
)

data = response.json()
print(data['message']['content'])

{
  "message": {
    "role": "assistant",
    "content": "<string>",
    "citations": [
      {
        "document_id": "<string>",
        "document_name": "<string>",
        "deal_id": "<string>",
        "deal_name": "<string>",
        "url": "https://app.usehindsight.com/deals/deal_123/documents/viewer/doc_abc123",
        "excerpt": "<string>"
      }
    ]
  },
  "tool_calls": [
    "search_across_deals",
    "search_deal_documents"
  ]
}

{
  "error": {
    "code": "bad_request",
    "message": "Invalid parameters",
    "details": {
      "missing_fields": [
        "file_name"
      ]
    }
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after the reset time in the response headers."
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred"
  }
}

Copy for AI context

POST https://app.usehindsight.com/api/v1/responses
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request body:
{
  "messages": [
    { "role": "user | assistant | system", "content": "string" }
  ],
  "stream": false
}

200 Response:
{
  "message": {
    "role": "assistant",
    "content": "AI-generated response with inline citations",
    "citations": [
      {
        "document_id": "string",
        "document_name": "string",
        "deal_id": "string | null",
        "deal_name": "string | null",
        "url": "https://app.usehindsight.com/deals/deal_123/documents/viewer/doc_abc123",
        "excerpt": "string"
      }
    ]
  },
  "tool_calls": ["search_across_deals", "search_deal_documents"]
}

Rate limits: 10 req/min (Essentials), 60 req/min (Growth), 300 req/min (Enterprise)
           10,000/mo (Essentials), 30,000/mo (Growth), 100,000/mo (Enterprise)

Overview

The Responses endpoint is the highest-level way to use Hindsight. Send a natural-language question and Hindsight’s AI orchestrates the underlying tools server-side — searching across deals, deal documents, competitive intel, and your knowledge base — then returns a single synthesized answer with inline citations. Use it when you want a complete, cited answer rather than raw tool output. It’s the right fit for Glean, Slack bots, search interfaces, and any app that should hand the user a finished response. If instead you want your own model to decide which tools to call, use the MCP integration.

POST https://app.usehindsight.com/api/v1/responses

Request Body

Field	Type	Required	Description
`messages`	array	Yes	Conversation messages, oldest first. Each has a `role` and `content`. Include prior turns to give the AI context.
`messages[].role`	string	Yes	One of `user`, `assistant`, or `system`.
`messages[].content`	string	Yes	The message text.
`stream`	boolean	No	Stream the response as Server-Sent Events. Defaults to `false`.

Response

Field	Type	Description
`message.role`	string	Always `assistant`.
`message.content`	string	The AI-generated answer, with inline citation markers.
`message.citations`	array	Source documents referenced in the answer (see Citations).
`tool_calls`	array	Names of the internal tools Hindsight called to produce the answer.

Citations

Each entry in message.citations traces a claim back to a source document:

Field	Type	Description
`document_id`	string	Unique ID for the source document.
`document_name`	string	Human-readable document name.
`deal_id`	string \| null	Associated deal ID, if the document belongs to a deal.
`deal_name`	string \| null	Associated deal name, if applicable.
`url`	string	Link to view the document in Hindsight.
`excerpt`	string	The relevant passage the answer draws from.

Streaming

Set stream: true to receive the answer incrementally as Server-Sent Events. This is recommended for chat UIs where you want to render tokens as they arrive.

{
  "messages": [{ "role": "user", "content": "..." }],
  "stream": true
}

Events follow the SSE format:

data: {"type": "content_delta", "content": "Based on security"}
data: {"type": "content_delta", "content": " discussions"}
data: {"type": "citation", "citation": { "...": "..." }}

Rate Limits

Plan	Requests / minute	Requests / month
Essentials	10	10,000
Growth	60	30,000
Enterprise	300	100,000

A 429 is returned when a limit is exceeded — back off and retry. See Error Handling for the full error format and codes.

curl -X POST https://app.usehindsight.com/api/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What security objections have we encountered with Enterprise customers?"
      }
    ],
    "stream": false
  }'

const response = await fetch('https://app.usehindsight.com/api/v1/responses', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    messages: [{ role: 'user', content: 'What security objections have we encountered?' }],
    stream: false
  })
});

const data = await response.json();
console.log(data.message.content);

import requests

response = requests.post(
    'https://app.usehindsight.com/api/v1/responses',
    headers={
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    },
    json={
        'messages': [{'role': 'user', 'content': 'What security objections have we encountered?'}],
        'stream': False
    }
)

data = response.json()
print(data['message']['content'])

Authorizations

Authorization

string

header

required

API key from Hindsight dashboard

Body

application/json

messages

object[]

required

The conversation messages

Minimum array length: 1

Show child attributes

stream

boolean

default:false

Whether to stream the response using Server-Sent Events

Response

Successful response

message

object

Show child attributes

tool_calls

string[]

The internal tools that were called to generate the response

Example:

[
  "search_across_deals",
  "search_deal_documents"
]

curl -X POST https://app.usehindsight.com/api/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What security objections have we encountered with Enterprise customers?"
      }
    ],
    "stream": false
  }'

const response = await fetch('https://app.usehindsight.com/api/v1/responses', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    messages: [{ role: 'user', content: 'What security objections have we encountered?' }],
    stream: false
  })
});

const data = await response.json();
console.log(data.message.content);

import requests

response = requests.post(
    'https://app.usehindsight.com/api/v1/responses',
    headers={
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    },
    json={
        'messages': [{'role': 'user', 'content': 'What security objections have we encountered?'}],
        'stream': False
    }
)

data = response.json()
print(data['message']['content'])

{
  "message": {
    "role": "assistant",
    "content": "<string>",
    "citations": [
      {
        "document_id": "<string>",
        "document_name": "<string>",
        "deal_id": "<string>",
        "deal_name": "<string>",
        "url": "https://app.usehindsight.com/deals/deal_123/documents/viewer/doc_abc123",
        "excerpt": "<string>"
      }
    ]
  },
  "tool_calls": [
    "search_across_deals",
    "search_deal_documents"
  ]
}

{
  "error": {
    "code": "bad_request",
    "message": "Invalid parameters",
    "details": {
      "missing_fields": [
        "file_name"
      ]
    }
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after the reset time in the response headers."
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred"
  }
}

Overview

Get Started

MCP

REST API

Integrations

Release Notes

Overview

Request Body

Response

Citations

Streaming

Rate Limits

Authorizations

Body

Response

​Overview

​Request Body

​Response

​Citations

​Streaming

​Rate Limits

Authorizations

Body

Response

Overview

Request Body

Response

Citations

Streaming

Rate Limits