> ## Documentation Index
> Fetch the complete documentation index at: https://hadiqio.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Search

> Run semantic search across your connected knowledge base.

The search endpoint retrieves documents semantically relevant to a query. It is part of the public API and can be called directly without creating a chat session.

<Note>
  This endpoint searches chat session history, not the document index. To search your connected documents and knowledge sources, use the chat API with a search-enabled agent. The admin search endpoint (`POST /api/admin/search`) provides direct document search for administrative use.
</Note>

***

## Search chat sessions

```
GET /api/chat/search
```

Searches through the authenticated user's chat sessions by query text, grouped by time period.

### Query parameters

<ParamField query="query" type="string">
  The search query. If omitted, returns the most recent sessions.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number (1-indexed).
</ParamField>

<ParamField query="page_size" type="integer" default="10">
  Number of results per page.
</ParamField>

### Response

<ResponseField name="groups" type="array">
  Sessions grouped by recency.

  <Expandable title="group fields">
    <ResponseField name="title" type="string">
      Label for this time group: `Today`, `Yesterday`, `This Week`, `This Month`, or `Older`.
    </ResponseField>

    <ResponseField name="chats" type="array">
      Sessions in this group.

      <Expandable title="chat summary fields">
        <ResponseField name="id" type="string (UUID)">
          Session identifier.
        </ResponseField>

        <ResponseField name="name" type="string">
          Session name or description.
        </ResponseField>

        <ResponseField name="persona_id" type="integer">
          Agent used in the session.
        </ResponseField>

        <ResponseField name="time_created" type="string (ISO 8601)">
          When the session was created.
        </ResponseField>

        <ResponseField name="shared_status" type="string">
          Sharing state: `private` or `public`.
        </ResponseField>

        <ResponseField name="current_alternate_model" type="string">
          Override model in use, if any.
        </ResponseField>

        <ResponseField name="current_temperature_override" type="number">
          Temperature override, if set.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="has_more" type="boolean">
  Whether more results are available on the next page.
</ResponseField>

<ResponseField name="next_page" type="integer">
  The next page number if `has_more` is `true`, otherwise `null`.
</ResponseField>

<CodeGroup>
  ```bash curl theme={null}
  curl "https://cloud.hadiq.io/api/chat/search?query=vacation+policy&page=1&page_size=10" \
    -H "Authorization: Bearer hadiqk-..."
  ```

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

  resp = requests.get(
      "https://cloud.hadiq.io/api/chat/search",
      headers={"Authorization": "Bearer hadiqk-..."},
      params={"query": "vacation policy", "page": 1, "page_size": 10},
  )
  data = resp.json()
  for group in data["groups"]:
      print(group["title"])
      for chat in group["chats"]:
          print("  ", chat["id"], chat["name"])
  ```
</CodeGroup>

***

## Admin document search

```
POST /api/admin/search
```

Searches the document index directly. Requires admin or curator role.

### Request body

<ParamField body="query" type="string" required>
  The search query string.
</ParamField>

<ParamField body="filters" type="object" required>
  Search filters.

  <Expandable title="filter fields">
    <ParamField body="source_type" type="array">
      Restrict to specific connector source types (e.g. `["confluence", "slack"]`).
    </ParamField>

    <ParamField body="document_set" type="array">
      Restrict to specific document set names.
    </ParamField>

    <ParamField body="time_cutoff" type="string (ISO 8601)">
      Only return documents updated after this timestamp.
    </ParamField>

    <ParamField body="tags" type="array">
      Filter by document tags.
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="documents" type="array">
  Matching documents ordered by relevance.

  <Expandable title="document fields">
    <ResponseField name="document_id" type="string">
      Unique document identifier.
    </ResponseField>

    <ResponseField name="semantic_identifier" type="string">
      Human-readable title shown in the UI.
    </ResponseField>

    <ResponseField name="link" type="string">
      URL to the source document, if available.
    </ResponseField>

    <ResponseField name="source_type" type="string">
      Connector source type (e.g. `confluence`, `slack`).
    </ResponseField>

    <ResponseField name="score" type="number">
      Relevance score for ranking.
    </ResponseField>

    <ResponseField name="blurb" type="string">
      Short excerpt of matching content.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://cloud.hadiq.io/api/admin/search \
    -H "Authorization: Bearer haidqk-..." \
    -H "Content-Type: application/json" \
    -d '{
      "query": "onboarding checklist",
      "filters": {
        "source_type": ["confluence", "google_drive"]
      }
    }'
  ```

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

  resp = requests.post(
      "https://cloud.hadiq.io/api/admin/search",
      headers={"Authorization": "Bearer hadiqk-..."},
      json={
          "query": "onboarding checklist",
          "filters": {
              "source_type": ["confluence", "google_drive"]
          },
      },
  )
  for doc in resp.json()["documents"]:
      print(doc["semantic_identifier"], doc["link"])
  ```
</CodeGroup>

***

## Error codes

| Status | Cause                                        |
| ------ | -------------------------------------------- |
| `401`  | Missing or invalid API key.                  |
| `403`  | Insufficient role for admin search endpoint. |