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 key 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://api.hindsight.com/api/v1/responses

Request Format

{
  "messages": [
    {
      "role": "user",
      "content": "What security objections have we encountered with Enterprise customers?"
    }
  ],
  "org_id": "your_org_id",
  "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.hindsight.com/deals/abc123), [TechCo Deal](https://app.hindsight.com/deals/def456)\n\n2. **Compliance Certifications** - SOC2 and ISO 27001 certifications were requested in 8 deals [Enterprise RFP Analysis](https://app.hindsight.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.hindsight.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://api.hindsight.com/api/v1/documents/library

Request Format

{
  "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",
  "folder_id": "folder_123"
}

Parameters

Parameter	Type	Required	Description
`file_name`	string	Yes	Name of the file
`file_url`	string	Yes*	URL to download the file from
`file_base64`	string	Yes*	Base64-encoded 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"`
`folder_id`	string	No	Folder ID to organize the document

*Either file_url or file_base64 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.hindsight.com/library/doc_abc123",
    "created_at": "2026-02-10T12:00:00Z"
  },
  "workflow_id": "run_xyz789"
}

Upload to Deal

Associate documents with specific deals for win-loss analysis.

POST https://api.hindsight.com/api/v1/documents/deals

Request Format

{
  "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_base64`	string	Yes*	Base64-encoded 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_base64 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.hindsight.com/deals/deal_123/documents/doc_def456",
    "created_at": "2026-02-10T12:00:00Z"
  },
  "workflow_id": "run_abc123"
}

Model Context Protocol (MCP) Integration

Individual Hindsight tools are available exclusively through the Model Context Protocol. This allows AI assistants like Claude to directly call Hindsight functions and orchestrate their own workflows. Best for: Claude Desktop, Cursor, Cline, and other MCP-compatible AI assistants

Quick Setup

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "hindsight": {
      "command": "npx",
      "args": ["-y", "@hindsight/mcp-server"],
      "env": {
        "HINDSIGHT_API_KEY": "your_api_key",
        "HINDSIGHT_ORG_ID": "your_org_id"
      }
    }
  }
}

Once configured, Claude will have access to all Hindsight tools and can call them as needed.

Available MCP Tools

1. search_knowledge_base

Search across all uploaded competitive intelligence documents. MCP Tool Name: search_knowledge_base

{
  "query": "competitor pricing strategy",
  "org_id": "your_org_id",
  "limit": 10
}

Returns:

{
  "results": [
    {
      "chunk_id": "chunk_123",
      "document_id": "doc_456",
      "document_name": "Q4 Competitive Analysis.pdf",
      "content": "Competitor X has adopted a value-based pricing model...",
      "similarity_score": 0.89,
      "metadata": {
        "page": 5,
        "section": "Pricing Strategy"
      }
    }
  ]
}

2. select_deal

Find deals based on stage, amount, competitor, product, or other filters. MCP Tool Name: select_deal

{
  "org_id": "your_org_id",
  "filters": {
    "status": ["Closed Won", "Closed Lost"],
    "amount": {
      "min": 100000,
      "max": 500000
    },
    "competitors": ["competitor_id_123"],
    "date_range": {
      "start": "2024-01-01",
      "end": "2024-12-31"
    }
  },
  "limit": 20
}

Returns:

{
  "deals": [
    {
      "id": "deal_123",
      "name": "Acme Corp Enterprise Deal",
      "status": "Closed Won",
      "amount": 250000,
      "close_date": "2024-06-15",
      "client": {
        "name": "Acme Corp",
        "industry": "Financial Services"
      },
      "competitors": ["Competitor X"],
      "summary": "Enterprise deployment with custom security requirements..."
    }
  ],
  "total_count": 45
}

3. search_across_deals

Perform semantic vector search across all deal documents to find relevant content. MCP Tool Name: search_across_deals

{
  "query": "integration objections",
  "org_id": "your_org_id",
  "limit": 15,
  "include_deal_metadata": true
}

Returns:

{
  "results": [
    {
      "deal_id": "deal_123",
      "deal_name": "Acme Corp Deal",
      "deal_stage": "Closed Lost",
      "document_id": "doc_456",
      "document_name": "Sales Call Notes - Final.pdf",
      "content": "Customer expressed concerns about Salesforce integration timeline...",
      "similarity_score": 0.92,
      "created_at": "2024-03-15"
    }
  ]
}

4. search_deal_documents

Deep search within specific identified deals. MCP Tool Name: search_deal_documents

{
  "deal_ids": ["deal_123", "deal_456"],
  "query": "pricing objections",
  "org_id": "your_org_id",
  "document_types": ["email", "meeting"],
  "limit": 30
}

Returns:

{
  "results": [
    {
      "deal_id": "deal_123",
      "deal_name": "Acme Corp Deal",
      "document_id": "doc_789",
      "document_name": "Pricing Discussion Email.eml",
      "document_type": "email",
      "content": "Prospect mentioned our pricing is 20% higher than Competitor X...",
      "similarity_score": 0.88,
      "metadata": {
        "sender": "[email protected]",
        "date": "2024-03-10"
      }
    }
  ]
}

5. search_deals

Find deals using AI embeddings to understand conceptual similarity. MCP Tool Name: search_deals

{
  "query": "enterprise security requirements deals",
  "org_id": "your_org_id",
  "limit": 10
}

Returns:

{
  "deals": [
    {
      "id": "deal_123",
      "name": "Acme Corp Enterprise Deal",
      "similarity_score": 0.91,
      "summary": "Large enterprise with strict security and compliance requirements...",
      "status": "Closed Won",
      "amount": 450000,
      "semantic_match_reasons": [
        "security requirements",
        "enterprise deployment",
        "compliance needs"
      ]
    }
  ]
}

6. search_competitors

Search competitive intelligence database for specific competitor information. MCP Tool Name: search_competitors

{
  "query": "pricing strategy and discounting",
  "competitor_id": "comp_123",
  "org_id": "your_org_id",
  "source": "g2",
  "limit": 20
}

Parameters:

source (optional): Filter by source - "g2", "linkedin", "x", "reddit", "discord", "slack"

Returns:

{
  "competitor": {
    "id": "comp_123",
    "name": "Competitor X",
    "website": "https://competitorx.com"
  },
  "results": [
    {
      "chunk_id": "chunk_789",
      "document_id": "doc_comp_123",
      "document_name": "Competitor X Battlecard.pdf",
      "content": "Competitor X typically offers 15-20% discounts for multi-year contracts...",
      "similarity_score": 0.87,
      "source": "g2",
      "metadata": {
        "section": "Pricing",
        "last_updated": "2024-09-15"
      }
    }
  ],
  "battlecard_url": "https://app.hindsight.com/competitors/comp_123/battlecard"
}

7. get_documents

Search for specific documents by name or keyword. MCP Tool Name: get_assets

{
  "keyword_query": "clozd",
  "org_id": "your_org_id",
}

Returns:

{
  "documents": [
    {
      "id": "doc_123",
      "file_name": "Objection Handling Guide.pdf",
      "created_at": "2024-08-20",
      "competitor_id": "comp_12345",
      "url": "https://app.hindsight.com/assets/doc_123"
    }
  ]
}

MCP Setup Instructions

Installation

The @hindsight/mcp-server package automatically handles:

Authentication with your API key
Tool registration with your AI assistant
Request/response formatting
Error handling and retries

Configuration for Claude Desktop

Open your Claude Desktop config file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Add the Hindsight MCP server:

{
  "mcpServers": {
    "hindsight": {
      "command": "npx",
      "args": ["-y", "@hindsight/mcp-server"],
      "env": {
        "HINDSIGHT_API_KEY": "your_api_key_here",
        "HINDSIGHT_ORG_ID": "your_org_id_here"
      }
    }
  }
}

Restart Claude Desktop
Verify the connection by asking Claude: “What Hindsight tools do you have access to?”

Configuration for Other MCP Clients

The same configuration works for other MCP-compatible clients like Cursor, Cline, and Zed. Consult your client’s documentation for where to place the MCP configuration.

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://api.hindsight.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?"}],
    "org_id": "your_org_id"
  }'

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://api.hindsight.com/api/v1/responses', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      messages: [{ role: 'user', content: message.text }],
      org_id: ORG_ID
    })
  });
  
  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/day
Free	10	100
Professional	60	10,000
Enterprise	300	Unlimited

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

Endpoints

​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

​Model Context Protocol (MCP) Integration

​Quick Setup

​Available MCP Tools

​1. search_knowledge_base

​2. select_deal

​3. search_across_deals

​4. search_deal_documents

​5. search_deals

​6. search_competitors

​7. get_documents

​MCP Setup Instructions

​Installation

​Configuration for Claude Desktop

​Configuration for Other MCP Clients

​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

Model Context Protocol (MCP) Integration

Quick Setup

Available MCP Tools

1. search_knowledge_base

2. select_deal

3. search_across_deals

4. search_deal_documents

5. search_deals

6. search_competitors

7. get_documents

MCP Setup Instructions

Installation

Configuration for Claude Desktop

Configuration for Other MCP Clients

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