Question GET list

GET /questions

Returns a list of published questions. By default, all published questions are returned, ordered by their last activity (descending). A combination of filters, search queries and ordering criteria can be applied to the list, as documented below.

When a query parameter is provided, only questions that match the given query are returned. If no sort parameter is specified, then the questions that are most relevant for the given query are returned first. If sort is specified, then the output will be sorted according to the specified sort criteria (which might deliver less meaningful results first). Consult the Concepts section for more technical details about search.

Parameter Type Default Required Description
limit int 10 Limits the number of returned question
offset int 0 Offset for pagination.
filter string (comma-separated filters) Filter the list of questions using a predefined filter. Allowed filters are:
  • solved Show solved questions
  • unsolved Show unsolved questions
  • my-questions Show questions you have posed
  • my-solutions Show question you have contributed a solution to
  • following Show question you are currently following
  • flagged Show questions that have been flagged
  • trending Show questions that are trending in the network
  • accepted Show questions that have been accepted
  • verified Show questions that have been verified
Combining multiple filters is possible by specifying a comma-separated list (my-questions,unsolved). They are combined using a logical AND condition. Joining incompatible filters may lead to an empty result.

Using the trending filter automatically sorts the questions by how trending they are, overriding the sort parameter.
tags string (comma-separated tag labels) - Specify a comma separated list of tag labels by which the questions are filtered. The tags are checked using a logical AND condition - that means only questions with all the specified tags will be returned.
tag_filter_default_operator string AND When the tags parameter consist of several tags, this parameter defines how these tags are combined during the search:
  • AND only returns questions that contain ALL the tags.
  • OR returns questions that contain AT LEAST one of the tags.
sort string (comma-separated criteria) last_activity.desc Specify the criteria the result is sorted by. The allowed sort criteria are last_activity, solution_count, date_published, view_count, id, interest, activity_and_interest.
The format is CRITERION.DIRECTION,CRITERION.DIRECTION.
Combining multiple sort criteria is possible by specifying a comma-separated list (solution_count.desc,last_activity.desc)
The criterion views is deprecated in favour of view_count to reflect naming of response parameter.

This parameter overrules the result ordering of the query parameter.
query string - Query to search by. The resulting questions are sorted by relevance for the given search query (unless a sort parameter overrides this behaviour).
query_default_operator string OR When the query parameter consist of several words, this parameter defines how these words are combined during the search:
  • AND only returns questions where all words in the query are matched. Moreover, they must all be matched within the same field: e.g. a question where one word is only found in the title and another word is only found in a solution, will not be returned. Similar questions (more info) will not be considered when using the AND operator.
  • OR also returns questions where only some of the words in the search query are matched. Also with this option, in the list of search results, questions where all words in the query are matched will generally appear above questions where only some words are matched.
If the parameter is missing or if an invalid value is specified, the OR operator will be used.

Warning: in the future, additional functionality will be added to give further control over which words in a search query must be matched and which words are optional. Afterwards, this parameter may be removed again from the API at relatively short notice.
query_fields string - (all fields) A comma-separated list of fields names, where each field name is one of the following:
  • title
  • description
  • tags
  • solutions
  • comments
  • attachments
If a list of field names is specified, then the question search will only match the provided query in those parts of each question. Invalid field names are ignored. If no query_fields parameter is specified, then all fields will be included.

Similar questions (more info) will only be considered if the fields title, description, tags and solutions are all included, since the similarity algorithm depends on all of these fields.
include_deleted boolean false If set to true and the user has the required permission, the response will include deleted questions.
category string all NOTE: To be deprecated in favour of categories and include_uncategorized

Filter the list of questions by a specific category. Possible values are:
  • uncategorised only returns questions which have no category assigned to them.
  • all returns all questions, no matter what category they belong to.
  • `category-id` only returns questions which are assigned to that specific category (more info).
categories string (comma-separated category ids) all Filter the list of questions matching any of the categories. List is joined by a logical OR. Only returns questions which are assigned to these categories (more info). When used in conjunction with include_uncategorized uncategorized questions can be included as well.
include_uncategorized boolean false Filter the list of questions by being uncategorized. Only returns questions without a category assigned. Can be used with categories.
language_id string (comma-separated language ids) user's content languages Filter the list of questions by a language supported by Starmind. If unspecified, the user's content languages are used.
log_query_type manual|autocomplete|url|tag null If defined and if offset == 0 and query is defined, the query will be logged and a search_query_id will be added to the response.
knowledge_space int knowledge space id Filters the list of questions to those assigned to the provided knowledge space. For a private knowledge space, the filtering will be performed only if the user is a member of the space.
translations string (comma-separated language ids) - x If defined, the response will include question translations in requested languages. Else, the response will include translations in the content language of the user. This is only available for networks with automatic translations enabled. Only Starmind supported languages and automatic translation enabled languages for given network are considered. Languages matching the original language of a question as well as unsupported languages are ignored.

Response

If a query is specified in the request, then every item in the response will have an additional field search_metadata. The search_metadata object contains:

  • score
  • is_relevant if the item is determined to be significantly relevant to the user query
  • highlighting object if highlighting can be applied

Score

The score of a question is a positive floating-point value that expresses how well the question fits the given search query, with better matches having a higher score. If no other sort parameter is specified in the request, then the results will be sorted by this score in descending order.

The scores of the results of any query are always roughly centred around 1.0. Questions that contain the search query in their title will generally score clearly higher than 1.0. Question where the search query is only found in some comment or attachment will generally score clearly lower than 1.0. As such, a value around 1.0 could be useful as a threshold to keep only highly relevant search results.

Highlighting

The highlighting object of a question is defined by the properties query_field, id, fragment, start, and end, which correspond to the element of the question that best matches the provided search query. If no highlighting can be applied to a question, then the question will not have a highlighting object. The query_field is the field name of the highlighted element, which is one of those included in the query_fields parameter or any of them if the parameter is not specified in the query. The relation between query_field and id is defined as follows:

query_field id
title The id of the question
description The id of the question
tags The id of the question
solutions The id of the best matching solution
comments The id of the best matching comment
attachments The id of the best matching attachment

The property fragment contains a fragment of the text, in which the matched words from the search query are surrounded by <em> tags. Apart from the <em> tags, the highlighted fragment is HTML encoded, so this string can be used without risk of HTML injections. If the best matching query_field is the title, then the fragment always contains the entire title.

The properties start and end are boolean values that define the position of the fragment in the full text. start is true for those fragments that start at the beginning of the text, and end is true for those that end at the end of the text. Additionally, this means that if start and end are both true, then the whole fragment covers the full text, and if startand end are both false, then the fragment is in the middle. These values may be used to decide whether to add an ellipsis (...) in front of and/or after the fragment when displaying the fragment to the user.

Logging

If the parameter log_query_type is not defined, the response will not contain search_query_id.

If the parameter log_query_type is defined and offset == 0 and query is defined:

  • The query will be logged.
  • The response will include a non-null integer search_query_id.

Warning: Logging should only be enabled when the query and the ensuing clicks may be used for learning about the user's interest and for optimising the ranking of results on future search queries. It is advised that integrations don’t use this parameter and (if required) implement their own logging instead.

{
  "search_query_id": 123,
  "total": 1,
  "_links": {
    "self": {
      "href": "/api/v1/questions?tags=sherlock&query=holmes&offset=0&limit=10&log_query_type=manual"
    }
  },
  "items": [
    {
      "description": null,
      "solution_count": 1,
      "slug": "is-there-a-study-in-scarlet",
      "id": 21,
      "updated": "2015-02-02T11:36:05.000Z",
      "content_updated": "2015-02-02T11:36:05.000Z",
      "last_activity": "2015-02-02T11:41:08.000Z",
      "image": "https://cdn.example.com/avatar/default/2d/1b84215e2f035a22f6fec213d3b1d9.jpg",
      "language": "en",
      "tag_relations": [
        {
          "tag": "Study",
          "is_auto": true
        }
      ],
      "title": "Is there a Study in Scarlet?",
      "attachments": "/questions/21/attachments",
      "is_published": true,
      "published": "2015-02-02T11:36:05.000Z",
      "created": "2015-02-02T11:31:05.000Z",
      "is_deleted": false,
      "view_count": 28,
      "search_metadata": {
        "highlighting": {
          "query_field": "solutions",
          "fragment": "Dr Watson, Sherlock <em>Holmes</em> partner Astrid Farnsworth",
          "id": 1092,
          "start": true,
          "end": false
        },
        "score": 5.8311359538639,
        "is_relevant": true
      },
      "upvote_count": 23,
      "translations": [
        {
          "language": "fr",
          "title": "Y a-t-il une étude à Scarlet?",
          "description": null
        }
      ]
    }
  ]
}