> ## 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.

# Upload to Knowledge Base

> Upload competitive intelligence documents, assets, and other files to your library.
Documents are automatically processed, chunked, and indexed for search.


Upload competitive intelligence documents, assets, and battlecards to your library.

> [accordion] Copy for AI context
>
> ```text theme={null}
> POST https://app.usehindsight.com/api/v1/documents/library
> Authorization: Bearer YOUR_API_KEY
> Content-Type: multipart/form-data
>
> Request fields (multipart/form-data):
>   file_name: string (required)
>   file_url: string (uri) — URL to fetch file from
>   file: binary — binary file content (alternative to file_url)
>   content_type: string (required) — MIME type, e.g. application/pdf
>   type: asset | intel (required)
>   competitor_id: string — Hindsight competitor ID
>   competitor_name: string — resolved to competitor_id automatically
>   source: drive | notion | confluence | onedrive | sharepoint | vanta | url | zapier | api
>
> 200 Response:
> {
>   "document": {
>     "id": "doc_abc123",
>     "file_name": "Competitor X Pricing Guide.pdf",
>     "status": "processing | ready | failed",
>     "type": "asset | intel",
>     "url": "https://app.usehindsight.com/deals/deal_123/documents/viewer/doc_abc123",
>     "created_at": "2026-02-10T12:00:00Z"
>   },
>   "run_id": "run_xyz789"
> }
>
> Rate limits: Organization-wide and per-API-key limits apply. Uploads may consume a separate usage quota.
> ```

## Document Types

| Type | Description |
| - | - |
| `asset` | Sales enablement content like battlecards, one-pagers, guides |
| `intel` | Competitive intelligence gathered from external sources |

## Source Options

The `source` field determines the icon displayed in the Hindsight UI:

| Source | Description |
| - | - |
| `drive` | Google Drive |
| `notion` | Notion |
| `confluence` | Confluence |
| `onedrive` | OneDrive |
| `sharepoint` | SharePoint |
| `vanta` | Vanta |
| `url` | Web URL |
| `zapier` | Zapier automation |
| `api` | API upload |

```bash cURL theme={null}
curl -X POST https://app.usehindsight.com/api/v1/documents/library \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file_name=Competitor X Pricing Guide.pdf" \
  -F "file_url=https://example.com/document.pdf" \
  -F "content_type=application/pdf" \
  -F "type=asset" \
  -F "competitor_name=Competitor X" \
  -F "source=drive"
```

```javascript Node.js theme={null}
const formData = new FormData();
formData.append('file_name', 'Competitor X Pricing Guide.pdf');
formData.append('file_url', 'https://example.com/document.pdf');
formData.append('content_type', 'application/pdf');
formData.append('type', 'asset');
formData.append('competitor_name', 'Competitor X');
formData.append('source', 'drive');

const response = await fetch('https://app.usehindsight.com/api/v1/documents/library', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`
  },
  body: formData
});

const data = await response.json();
console.log(`Document uploaded: ${data.document.id}`);
```

```python Python theme={null}
import requests

response = requests.post(
    'https://app.usehindsight.com/api/v1/documents/library',
    headers={'Authorization': f'Bearer {API_KEY}'},
    data={
        'file_name': 'Competitor X Pricing Guide.pdf',
        'file_url': 'https://example.com/document.pdf',
        'content_type': 'application/pdf',
        'type': 'asset',
        'competitor_name': 'Competitor X',
        'source': 'drive'
    }
)

data = response.json()
print(f"Document uploaded: {data['document']['id']}")
```


## OpenAPI

````yaml POST /documents/library
openapi: 3.1.0
info:
  title: Hindsight API
  description: >
    Integrate Hindsight competitive intelligence, win-loss insights, and deal
    data into your applications.


    ## Authentication

    All API requests require a Bearer token in the Authorization header:

    ```

    Authorization: Bearer YOUR_API_KEY

    ```


    Get your API key from the [Hindsight
    dashboard](https://app.usehindsight.com/settings/keys).

    Newly created API keys begin with `hs_`; existing keys remain supported
    until they

    are rotated or expire.


    ## Rate Limits


    Hindsight applies both organization-wide and per-API-key request limits.
    Per-key

    defaults are approximately one-third of the organization plan limit, with a
    minimum

    of 5 requests per minute. Expensive operations may also consume separate
    usage quotas.

    On `429 Too Many Requests`, use `X-RateLimit-Limit`,
    `X-RateLimit-Remaining`, and

    `X-RateLimit-Reset` (Unix milliseconds). These public headers represent the
    active

    response limit; separate per-key response headers are not currently
    provided.
  version: 1.0.0
  contact:
    name: Hindsight Support
    url: https://usehindsight.com/support
    email: support@hindsight.com
servers:
  - url: https://app.usehindsight.com/api/v1
    description: Production server
security:
  - bearerAuth: []
tags:
  - name: Chat
    description: AI-powered chat completions with competitive intelligence
  - name: Deals
    description: Access and export deal data
  - name: Documents
    description: Upload and manage documents
  - name: Interviews
    description: Create and manage win-loss interview requests
  - name: Tools
    description: Structured Hindsight tool calls for application-controlled workflows
paths:
  /documents/library:
    post:
      tags:
        - Documents
      summary: Upload document to knowledge base
      description: >
        Upload competitive intelligence documents, assets, and other files to
        your library.

        Documents are automatically processed, chunked, and indexed for search.
      operationId: uploadLibraryDocument
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/LibraryDocumentUploadRequest'
            examples:
              withUrl:
                summary: Upload from URL
                value:
                  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
              withFile:
                summary: Upload binary file
                value:
                  file_name: Battlecard.md
                  file: <binary file content>
                  content_type: text/markdown
                  type: asset
                  competitor_name: Competitor X
                  source: notion
      responses:
        '200':
          description: Document upload initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentUploadResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    LibraryDocumentUploadRequest:
      type: object
      required:
        - file_name
        - content_type
        - type
      properties:
        file_name:
          type: string
          description: Name of the file
          example: Competitor X Pricing Guide.pdf
        file_url:
          type: string
          format: uri
          description: URL to download the file from (provide either file_url or file)
          example: https://example.com/document.pdf
        file:
          type: string
          format: binary
          description: Binary file content (provide either file or file_url)
        content_type:
          type: string
          description: MIME type of the file
          example: application/pdf
          enum:
            - application/pdf
            - text/markdown
            - text/plain
            - >-
              application/vnd.openxmlformats-officedocument.wordprocessingml.document
            - >-
              application/vnd.openxmlformats-officedocument.presentationml.presentation
            - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
        type:
          type: string
          description: Document type
          enum:
            - asset
            - intel
        competitor_id:
          type: string
          description: >-
            Hindsight competitor ID (provide either competitor_id or
            competitor_name)
          example: comp_123
        competitor_name:
          type: string
          description: Competitor name - will be resolved to competitor_id automatically
          example: Competitor X
        source:
          type: string
          description: Source application where the document originated
          enum:
            - drive
            - notion
            - confluence
            - onedrive
            - sharepoint
            - vanta
            - url
            - zapier
            - api
          example: drive
    DocumentUploadResponse:
      type: object
      properties:
        document:
          type: object
          properties:
            id:
              type: string
              description: Unique identifier for the document
              example: doc_abc123
            file_name:
              type: string
              description: Name of the uploaded file
              example: Competitor X Pricing Guide.pdf
            status:
              type: string
              description: Processing status of the document
              enum:
                - processing
                - ready
                - failed
              example: processing
            type:
              type: string
              description: Document type
              enum:
                - asset
                - intel
              example: asset
            url:
              type: string
              format: uri
              description: URL to view the document in Hindsight
              example: >-
                https://app.usehindsight.com/deals/deal_123/documents/viewer/doc_abc123
            created_at:
              type: string
              format: date-time
              description: Timestamp when the document was created
              example: '2026-02-10T12:00:00Z'
        run_id:
          type: string
          description: ID to track the document processing run
          example: run_xyz789
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code
              example: unauthorized
            message:
              type: string
              description: Human-readable error message
              example: Invalid API key
            details:
              type: object
              description: Additional error details
              additionalProperties: true
  responses:
    BadRequest:
      description: Bad request - invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: bad_request
              message: Invalid parameters
              details:
                missing_fields:
                  - file_name
    Unauthorized:
      description: Unauthorized - invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: unauthorized
              message: Invalid API key
    RateLimitExceeded:
      description: Too many requests - rate limit or applicable usage quota exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rate_limit_exceeded
              message: >-
                Rate limit exceeded. Please retry after the reset time in the
                response headers.
      headers:
        X-RateLimit-Limit:
          schema:
            type: integer
          description: Requests allowed in the current 60-second window.
        X-RateLimit-Remaining:
          schema:
            type: integer
          description: Requests remaining in the current 60-second window.
        X-RateLimit-Reset:
          schema:
            type: integer
            format: int64
          description: Unix timestamp in milliseconds when the rate-limit window resets.
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: internal_error
              message: An unexpected error occurred
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key from Hindsight Settings → API keys. Use `Authorization: Bearer
        YOUR_API_KEY`. Newly created keys begin with `hs_`; existing keys remain
        supported until rotated or expired.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.