> ## Documentation Index
> Fetch the complete documentation index at: https://docs.co-mind.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Postman Collection

The co-mind.ai API ships with a complete Postman collection and environment for interactive testing. This guide walks you through setup and common workflows.

## Files

| File                                                     | Description                                |
| -------------------------------------------------------- | ------------------------------------------ |
| `comind-Private-AI-Platform-API.postman_collection.json` | Complete API collection (130+ endpoints)   |
| `comind-Private-AI-Platform.postman_environment.json`    | Environment variables with auto-population |

## Setup

<Steps>
  <Step title="Import the Collection">
    1. Open Postman
    2. Click **Import**
    3. Select `comind-Private-AI-Platform-API.postman_collection.json`
    4. Click **Import**
  </Step>

  <Step title="Import the Environment">
    1. Click **Import** again
    2. Select `comind-Private-AI-Platform.postman_environment.json`
    3. Click **Import**
  </Step>

  <Step title="Configure Environment Variables">
    1. Select **"comind Private AI Platform - Local"** environment (top-right dropdown)
    2. Click the eye icon to view/edit variables
    3. Update these values:

    ```
    base_url:       http://localhost:3001  (or your server URL)
    user_email:     your-email@example.com
    user_password:  your-password
    ```
  </Step>

  <Step title="Authenticate">
    Choose one of these options:

    <Tabs>
      <Tab title="Option A: Create a PAT (Recommended)">
        1. Run **"Login"** request in the **"1. Authentication"** folder
        2. Run **"Create API Token"** in the **"2. API Tokens (PAT)"** folder
        3. The PAT is automatically saved to `pat_token` — all requests will use it
      </Tab>

      <Tab title="Option B: Set PAT Directly">
        If you already have a PAT:

        1. Edit environment variables
        2. Set `pat_token` to your token value (e.g., `cmnd_abc123.sk_xxxx`)
      </Tab>
    </Tabs>

    <Info>
      The collection uses `pat_token` as the default auth for all requests. Auth endpoints and PAT management endpoints override this to use JWT or no auth as appropriate.
    </Info>
  </Step>
</Steps>

## Example Workflows

### PAT Token Setup

```text theme={null}
1. Login                    → POST /v1/auth/login
                              → Saves: access_token, refresh_token, user_id

2. Create API Token (PAT)   → POST /v1/api-tokens (uses JWT)
                              → Saves: pat_token, pat_token_id
                              → Token value shown only once!

3. All subsequent requests use pat_token automatically
```

### RAG Chat Workflow

<Steps>
  <Step title="Check Available Models">
    Run `GET /v1/models` to see what's available.
  </Step>

  <Step title="Create Knowledge Base">
    Run `POST /v1/knowledgebases` — the KB ID is saved automatically.
  </Step>

  <Step title="Upload Documents">
    Run `POST /v1/knowledgebases/{kb_id}/files` — upload PDF, DOCX, TXT, CSV files.
  </Step>

  <Step title="Query Knowledge Base">
    Run `POST /v1/knowledgebases/query` — test with "What are the main topics?"
  </Step>

  <Step title="Chat with Knowledge Base">
    Run `POST /v1/knowledgebase/chat/completions` — ask questions about your documents.
  </Step>
</Steps>

### Stateful Chat Session

```text theme={null}
1. Create Chat Session       → POST /v1/chat/sessions
                               → Saves: session_id

2. Send Messages             → POST /v1/chat/sessions/{id}/messages
                               → Server manages history

3. Get Message History       → GET /v1/chat/sessions/{id}/messages

4. Clear or Delete Session   → POST /v1/chat/sessions/{id}/clear
                             → DELETE /v1/chat/sessions/{id}
```

## Environment Variables

| Variable        | Description                 | Auto-populated?                |
| --------------- | --------------------------- | ------------------------------ |
| `base_url`      | API server URL              | No                             |
| `user_email`    | Your email                  | No                             |
| `user_password` | Your password               | No                             |
| `pat_token`     | Personal Access Token       | Yes — from Create API Token    |
| `pat_token_id`  | PAT token ID                | Yes — from Create API Token    |
| `access_token`  | JWT access token            | Yes — from Login               |
| `refresh_token` | JWT refresh token           | Yes — from Login               |
| `user_id`       | Your user ID                | Yes — from Login               |
| `kb_id`         | Last created KB ID          | Yes — from Create KB           |
| `file_id`       | Last uploaded file ID       | Yes — from Upload File         |
| `session_id`    | Last session ID             | Yes — from Create Chat Session |
| `echo_job_id`   | Last transcription job ID   | Yes — from Async Transcribe    |
| `tenant_id`     | Tenant/org ID for admin ops | No                             |

## API Endpoint Categories

The collection is organized into these folders:

| Folder                    | Endpoints | Description                                       |
| ------------------------- | --------- | ------------------------------------------------- |
| Authentication            | 13        | Login, SSO, refresh, registration, password reset |
| API Tokens (PAT)          | 6         | Create, list, revoke, rotate tokens, list scopes  |
| Knowledge Base Management | 4         | Create, list, get, delete knowledge bases         |
| File Management           | 3         | Upload, list, delete files in KBs                 |
| AI Models & Inference     | 6         | Models, chat, completions, embeddings             |
| Query & Chat (RAG)        | 3         | KB queries, KB-enhanced chat, vision+RAG          |
| Chat Sessions             | 8         | Stateful chat with server-managed history         |
| Discovery                 | 3         | Backends, capabilities, health checks             |
| Echo Engine               | 16        | Transcription, recordings, TTS                    |
| Sanitizer Admin           | 4         | Security policy management                        |
| Document Analyzer         | 19        | Document extraction and review                    |
| Researcher                | 24        | Search, research, analysis, synthesis             |
| Directory Admin           | 8         | LDAP/AD configuration                             |
| Entra Admin               | 6         | Azure AD configuration                            |
| Tenant Admin              | 14        | Tenant and sub-org management                     |
| Audit Logs                | 1         | Query audit logs                                  |

## Supported File Types

**Documents:** PDF, Word (.docx, .doc), Text (.txt)
**Spreadsheets:** Excel (.xlsx, .xls), CSV (.csv)
**Presentations:** PowerPoint (.pptx)
**Images:** JPG, PNG, GIF, BMP

## Troubleshooting

<AccordionGroup>
  <Accordion title="'Unauthorized' error">
    * Check that `pat_token` or `access_token` is set in the environment
    * If using JWT, it may be expired — run the **Refresh Token** request
    * If using PAT, check it hasn't been revoked or expired
  </Accordion>

  <Accordion title="'Knowledge base not found'">
    * Run **"Create Knowledge Base"** first
    * Check `kb_id` is set in the environment variables
  </Accordion>

  <Accordion title="File upload fails">
    * Check file format is supported (see list above)
    * Verify `kb_id` is correct
  </Accordion>

  <Accordion title="No results from query">
    * Wait for file processing to complete (status: `"completed"`)
    * Lower `min_score` (try `0.1`)
    * Try different query terms
  </Accordion>
</AccordionGroup>