Hindsight API - Hindsight Docs

Overview

The Hindsight API provides access to competitive intelligence, win-loss insights, and deal data through two integration methods:

REST API - Hindsight’s AI handles multiple tool calls and returns contextual text responses with citations
Model Context Protocol (MCP) - Individual tools for AI assistants like Claude to orchestrate directly

When to Use Each

REST API: For Glean, Slack bots, custom applications that need complete answers
MCP (Coming Soon): For Claude Desktop, Cursor, or other MCP-compatible AI assistants that orchestrate tools themselves

Authentication

All API requests require authentication using an API key in the header:

Authorization: Bearer YOUR_API_KEY

Get your API keys from the Hindsight dashboard.

REST API

The REST API is designed for applications that need complete, synthesized answers with citations. Hindsight’s AI automatically orchestrates multiple searches and returns formatted responses. Best for: Glean, Slack bots, search interfaces, custom applications

Endpoint

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

Request Format

{
  "messages": [
    {
      "role": "user",
      "content": "What security objections have we encountered with Enterprise customers?"
    }
  ],
  "stream": false
}

Response Format

{
  "message": {
    "role": "assistant",
    "content": "Based on security discussions in enterprise deals, here are the main objections:\n\n1. **Data Encryption** - Multiple customers asked about encryption at rest and in transit [Acme Corp Deal](https://app.usehindsight.com/deals/abc123), [TechCo Deal](https://app.usehindsight.com/deals/def456)\n\n2. **Compliance Certifications** - SOC2 and ISO 27001 certifications were requested in 8 deals [Enterprise RFP Analysis](https://app.usehindsight.com/docs/xyz789)...",
    "citations": [
      {
        "document_id": "doc_abc123",
        "document_name": "Acme Corp - Security Requirements.pdf",
        "deal_id": "deal_abc123",
        "deal_name": "Acme Corp Deal",
        "url": "https://app.usehindsight.com/deals/abc123/documents/doc_abc123",
        "excerpt": "Customer requires end-to-end encryption for all data..."
      }
    ]
  },
  "tool_calls": [
    "search_across_deals",
    "search_deal_documents"
  ]
}

Streaming Support

Enable streaming for real-time responses:

{
  "messages": [...],
  "stream": true
}

Stream format follows SSE (Server-Sent Events):

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

Document Upload API

Upload documents to your Hindsight knowledge base or associate them with specific deals.

Upload to Knowledge Base

Upload competitive intelligence documents, assets, and other files to your library.

POST https://app.usehindsight.com/api/v1/documents/library

Request Format

Send as multipart/form-data:

file_name=Competitor X Pricing Guide.pdf
file_url=https://example.com/document.pdf
content_type=application/pdf
type=asset
competitor_id=comp_123
source=drive

Parameters

Parameter	Type	Required	Description
`file_name`	string	Yes	Name of the file
`file_url`	string	Yes*	URL to download the file from
`file`	binary	Yes*	Binary file content (alternative to `file_url`)
`content_type`	string	Yes	MIME type (e.g., `application/pdf`, `text/markdown`)
`type`	string	Yes	Document type: `"asset"` or `"intel"`
`competitor_id`	string	Yes**	Hindsight competitor ID
`competitor_name`	string	Yes**	Competitor name (resolved to ID automatically)
`source`	string	No	Source application: `"drive"`, `"notion"`, `"confluence"`, `"onedrive"`, `"sharepoint"`, `"vanta"`, `"url"`, `"zapier"`, `"api"`

*Either file_url or file is required
**Either competitor_id or competitor_name is required

Response

{
  "document": {
    "id": "doc_abc123",
    "file_name": "Competitor X Pricing Guide.pdf",
    "status": "processing",
    "url": "https://app.usehindsight.com/documents/viewer/[doc_id]",
    "created_at": "2026-02-10T12:00:00Z"
  },
  "run_id": "run_xyz789"
}

Upload to Deal

Associate documents with specific deals for win-loss analysis.

POST https://app.usehindsight.com/api/v1/deals/documents

Request Format

Send as multipart/form-data:

file_name=Discovery Call Notes.pdf
file_url=https://example.com/document.pdf
content_type=application/pdf
deal_id=deal_123
source=gong

Parameters

Parameter	Type	Required	Description
`file_name`	string	Yes	Name of the file
`file_url`	string	Yes*	URL to download the file from
`file`	binary	Yes*	Binary file content (alternative to `file_url`)
`content_type`	string	Yes	MIME type (e.g., `application/pdf`, `audio/mpeg`)
`deal_id`	string	Yes**	Hindsight deal ID
`salesforce_id`	string	Yes**	Salesforce Opportunity ID
`hubspot_id`	string	Yes**	HubSpot Deal ID
`source`	string	No	Source application: `"gong"`, `"clari"`, `"fathom"`, `"fireflies"`, `"avoma"`, `"outreach"`, `"gmail"`, `"Salesforce"`, `"Hubspot"`, `"api"`

*Either file_url or file is required
**One of deal_id, salesforce_id, or hubspot_id is required

Supported File Types

Documents: PDF, Word, PowerPoint, Excel, Markdown, plain text
Audio: MP3, WAV, M4A (automatically transcribed)
Video: MP4 (automatically transcribed)

Response

{
  "document": {
    "id": "doc_def456",
    "file_name": "Discovery Call Notes.pdf",
    "status": "processing",
    "deal_id": "deal_123",
    "url": "https://app.usehindsight.com/deals/deal_123/documents/viewer/doc_def456",
    "created_at": "2026-02-10T12:00:00Z"
  },
  "run_id": "run_abc123"
}

Example Usage

Once configured, you can ask Claude questions like:

“Find deals where we lost to Competitor X in the last quarter”
“What are the top security objections we’ve encountered?”
“Search for pricing discussions in enterprise deals”
“Show me competitor intel on Salesforce’s integration strategy”

Claude will automatically call the appropriate Hindsight tools and synthesize the results

Common Use Cases

Use Case 1: Glean Integration

Integrate Hindsight as a data source in Glean to answer competitive intelligence and win-loss questions. REST API Example:

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 are common objections to our enterprise tier?"}]
  }'

Best for: When you want comprehensive, cited answers in Glean search results.

Use Case 2: Claude Desktop for Sales Prep

Use Claude with Hindsight tools to prepare for sales calls, analyze deals, and get competitive intel. Example Conversation:

You: "I have a call with a prospect considering Salesforce. Help me prepare."

Claude: [Uses search_competitors and search_across_deals tools]
"Here's what I found about competing with Salesforce..."

Best for: Sales reps preparing for calls, analyzing win/loss patterns, researching competitors.

Use Case 3: Custom Slack Bot

Build a Slack bot that answers team questions about deals and competitors. REST API Example:

app.message(async ({ message, say }) => {
  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: message.text }]
    })
  });
  
  const data = await response.json();
  await say(data.message.content);
});

Best for: Team-wide access to competitive intelligence and deal insights.

Rate Limits

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

Error Handling

All errors follow this format:

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

Error Codes

400 - Bad Request (invalid parameters)
401 - Unauthorized (invalid API key)
403 - Forbidden (insufficient permissions)
404 - Not Found (resource doesn’t exist)
429 - Too Many Requests (rate limit exceeded)
500 - Internal Server Error

Next Steps

Get API Key

Generate your API key from the dashboard

MCP Setup Guide

Detailed MCP configuration instructions

Glean Integration

Connect Hindsight to Glean

Example Code

REST API examples and MCP usage patterns

Overview

MCP

Endpoints

Documentation Index

​Overview

​When to Use Each

​Authentication

​REST API

​Endpoint

​Request Format

​Response Format

​Streaming Support

​Document Upload API

​Upload to Knowledge Base

​Request Format

​Parameters

​Response

​Upload to Deal

​Request Format

​Parameters

​Supported File Types

​Response

​Example Usage

​Common Use Cases

​Use Case 1: Glean Integration

​Use Case 2: Claude Desktop for Sales Prep

​Use Case 3: Custom Slack Bot

​Rate Limits

​Error Handling

​Error Codes

​Next Steps

Get API Key

MCP Setup Guide

Glean Integration

Example Code

Overview

When to Use Each

Authentication

REST API

Endpoint

Request Format

Response Format

Streaming Support

Document Upload API

Upload to Knowledge Base

Request Format

Parameters

Response

Upload to Deal

Request Format

Parameters

Supported File Types

Response

Example Usage

Common Use Cases

Use Case 1: Glean Integration

Use Case 2: Claude Desktop for Sales Prep

Use Case 3: Custom Slack Bot

Rate Limits

Error Handling

Error Codes

Next Steps