Hindsight API

Overview

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

REST API - either receive a complete, cited AI response or call supported Hindsight tools directly
Model Context Protocol (MCP) - Individual tools your AI assistant orchestrates directly

This page covers the REST API. Direct REST tool calls and MCP calls use the same authorization, validation, limits, and underlying tool execution.

When to Use Each

REST API responses: For Glean, Slack bots, and search interfaces that want a finished, synthesized answer
REST API tools: For server-side applications that need structured search or retrieval results without an LLM-generated response
MCP: For Claude, ChatGPT, Cursor, or other MCP clients 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 has two surfaces. Use Responses when you want Hindsight’s AI to orchestrate multiple searches and return a synthesized, cited answer. Use Tools when your application needs structured results and controls the workflow itself. 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"}

Direct Tool API

Direct tool endpoints accept JSON input and return structured JSON. They are useful when you know the retrieval step you need and want to compose the workflow in your own service. The recommended deal-research flow is:

Call select-deal to filter and triage analyzed deals.
Pass the returned deal_id values to get-deal for summaries and competitor positioning.

Endpoint	Use it for
`POST /tools/select-deal`	Finding analyzed deals by name, competitor, stage, amount, date, owner, and other filters. Returns lean, paginated rows.
`POST /tools/get-deal`	Getting full details for one to ten known deal IDs.

See the Direct Tool API reference for the complete list of available deal research, competitive intelligence, web research, and data-analysis tools. For a client-side AI assistant that should choose and sequence tools itself, use MCP instead.

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_competitive_intel 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

All API and MCP calls are limited per organization, not per user, API key, or endpoint. The per-minute limit is shared across the organization’s API and MCP traffic and uses a 60-second sliding window.

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

select-deal and get-deal each consume one read from the shared monthly reads bucket after authorization and input validation succeed. That bucket is also shared with other read-class Hindsight tools, whether called over REST or MCP. Organization-specific allowances may differ from the plan defaults. Successful direct-tool responses include these headers:

Header	Meaning
`X-RateLimit-Limit`	Requests allowed in the current 60-second window.
`X-RateLimit-Remaining`	Requests remaining in that window.
`X-RateLimit-Reset`	Unix timestamp in milliseconds when the rate-limit window resets.
`X-Usage-Used`	Reads used in the current calendar month.
`X-Usage-Limit`	Monthly read allowance.
`X-Usage-Remaining`	Reads remaining this month.
`X-Usage-Period-End`	ISO timestamp for the next monthly reset.

On a 429, inspect the same headers and retry after the stated reset time. A rate-limited call does not consume monthly usage.

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 or monthly usage quota exceeded)
500 - Internal Server Error

Next Steps

Get API Key

Generate your API key from the dashboard

MCP Setup Guide

Detailed MCP configuration and the full tool reference

AI Responses

Full reference for the responses endpoint

Direct Tool API

Browse every structured-search and analysis tool

Platform Overview

How the verified deal layer is built

Overview

Get Started

MCP

REST API

Integrations

Release Notes

Overview

When to Use Each

Authentication

REST API

Endpoint

Request Format

Response Format

Streaming Support

Direct Tool API

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

AI Responses

Direct Tool API

Platform Overview

​Overview

​When to Use Each

​Authentication

​REST API

​Endpoint

​Request Format

​Response Format

​Streaming Support

​Direct Tool API

​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

AI Responses

Direct Tool API

Platform Overview

Overview

When to Use Each

Authentication

REST API

Endpoint

Request Format

Response Format

Streaming Support

Direct Tool API

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