> ## Documentation Index > Fetch the complete documentation index at: https://docs.usehindsight.com/llms.txt > Use this file to discover all available pages before exploring further. # Hindsight API > Integrate Hindsight intelligence into your AI agents, MCP servers, and custom applications ## Overview The Hindsight API provides access to competitive intelligence, win-loss insights, and deal data through two integration methods: 1. **REST API** - Hindsight's AI handles multiple tool calls and returns contextual text responses with citations 2. **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: ```bash theme={null} Authorization: Bearer YOUR_API_KEY ``` Get your API keys from the [Hindsight dashboard](https://app.usehindsight.com/settings/keys). API Keys *** ## 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 ```json theme={null} { "messages": [ { "role": "user", "content": "What security objections have we encountered with Enterprise customers?" } ], "stream": false } ``` ### Response Format ```json theme={null} { "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: ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "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:** ```bash theme={null} 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:** ```javascript theme={null} 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: ```json theme={null} { "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 Generate your API key from the dashboard Detailed MCP configuration instructions Connect Hindsight to Glean REST API examples and MCP usage patterns