Run a global search

Searches Mindtickle learning site content across entities and returns results ranked by semantic relevance.

Prerequisites

Authentication and setup: A valid access token.

Endpoint

POST /v1/global-search

Base URL: the API3 host for your region, not the standard REST host. See Base URLs.

Headers: Authorization: Bearer ACCESS_TOKEN, Content-Type: application/json. Both are required.

Request

Parameter	Type	Required	Description
`username`	string	Required	User initiating the request.
`search_text`	string	Required	Search term entered by the user.
`entities`	array	Required	List of entities to search, with optional filters. Each entity object can include the fields below.
`entities.entity_type`	string	Not specified	Type of entity to search, for example `MODULES` or `COURSES`.
`entities.module_filters`	object	Optional	Module filters that refine search results, for example `module_types` and `module_tags`.
`entities.rank_entity_docs`	boolean	Optional	Determines whether the entity documents are included for this entity type. See Notes.
`pagination`	object	Optional	Pagination options. See Pagination and sorting before requesting subsequent pages.
`pagination.size`	integer	Not specified	Number of results to return, up to 50.

Request example

{
  "username": "john.doe@example.com",
  "search_text": "sales onboarding",
  "entities": [
    {
      "entity_type": "MODULES",
      "module_filters": {
        "module_types": ["COURSE", "MISSION"],
        "module_tags": ["onboarding", "sales"]
      },
      "rank_entity_docs": true
    }
  ],
  "pagination": {
    "size": 25
  }
}

Response

Field	Type	Description
`entities`	array	Array of matched entities with metadata.
`entity_total_count`	array	Count of matched entities per type.
`page_response`	object	Pagination data and next cursor if available.

Response example

{
  "entities": [
    {
      "entity_type": "MODULES",
      "entity_id": "1234567890123456101",
      "entity_name": "Sales Onboarding 101",
      "type": "COURSE",
      "media_type": "UNDEFINED_CONTENT_TYPE",
      "score": 0.987
    }
  ],
  "entity_total_count": [
    {
      "entity_type": "MODULES",
      "count": 10
    }
  ],
  "page_response": {
    "total_hits": 10,
    "next_cursor": "cursor_abc123"
  }
}

Errors

Status	Error	Message	Reason
`400`	`INVALID_REQUEST`	Missing required parameter	Required field missing or invalid.
`401`	`UNAUTHORIZED`	Invalid or expired token	Token missing, invalid, or expired.
`429`	`RATE_LIMIT_EXCEEDED`	Too many requests	Exceeded API rate limits.
`500`	`INTERNAL_ERROR`	Internal server error	Unexpected server-side failure.

Notes

Ranking: When rank_entity_docs is true, matching documents are included for ranking and pagination. When it is false, only the count is included, and the documents are excluded from the ranked results.
Rate limits: 600 requests per minute and 3,000 requests per hour.
Limits: Maximum 50 results per page.
Pagination and sorting: Use pagination.size to limit results. Before implementing subsequent pages or custom sorting, confirm the continuation request field and sorting parameters with Mindtickle Support. Do not assume that the response field page_response.next_cursor is also a request field.
Entities: For what each entity type searches, see Searchable entities.