Semantic Search

Semantic search improves upon traditional keyword search by mapping the meaning between words in any language. For example, the search may correlate that “dogs” and “cats” are both animals or pets in a query about pets, even if neither are explicitly mentioned. It’s a powerful way to search content.

Minimal Request Example #

By default, the search will include a) any source your team has uploaded, and b) any source that has been contributed to the global corpus. Here is a minimal example:

curl \
--header 'x-api-key: apg_xxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data '{
    "query": "Who is Jesus?"
}' \
--url https://my.gospel.bot/api/v1/search

Please note: you must replace the x-api-key value with your API key and my.gospel.bot with your Agent’s domain.

Full Request Example #

However, the API supports an advanced set of filtering parameters. Here’s an example of all supported parameters that have an effect on the output:

curl \
--header 'Authorization: Bearer apg_xxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data '{
    "query": "Who is Jesus?",
    "limit": 100,
    "filters": {
        "model": "source",
        "ids": [1,2,3],
        "types": ["article"],
        "languages": ["en","es"],
        "collection_ids": [4,5],
        "contributor_ids": [6],
        "category_ids": [7],
        "classification_id": 8,
        "external_ids": [9],
        "team_ids": [10],
        "user_ids": [11],
        "is_locked": false,
        "min_weight": 2,
        "max_weight": 4,
        "min_rating": 4,
        "max_rating": 5,
        "min_num_views": 100,
        "max_num_views": 1000,
        "min_num_impressions": 1,
        "max_num_impressions": 10,
        "min_num_referrals": 3,
        "max_num_referrals": 33,
        "min_published_on": "2025-01-01",
        "max_published_on": "2025-08-31",
        "min_created_at": "2025-03-01 00:00:00",
        "max_created_at": "2025-03-01 23:59:59",
        "min_updated_at": "2025-03-01 00:00:00",
        "max_updated_at": "2025-03-01 23:59:59"
    }
}' \
--url https://my.gospel.bot/api/v1/search

Please note: you must replace the Authorization bearer token value with your API key and my.gospel.bot with your Agent’s domain.

API Keys #

API keys are provisioned against a given Agent and cannot be used for another Agent.

Query #

The query parameter is the free text string to match content.

Limit #

The limit parameter specifies how many results to return, up to a maximum of 100. The semantic API does not support paging. If more than 100 results are returned, consider using filters to further specify what kind of results you want.

Filters #

The filters parameter value is a JSON object containing key / value pairs to constrain the results returned. Each filter is related to other filters as an AND operator; i.e., all conditions must match. Each value within a multi-value filter is evaluated as an OR operator. Hence, the logical structure that is evaluated would be: “return anything that matches any of the values of filter x and any of the values of filter y.”

All possible filters are described below:

Filter Parameter	Description	Options	Default
model	Used to specify what kind of object.	source, collection, or contributor	source
ids	Array of integer model IDs. If the model is source, then the IDs match source IDs, etc.
types	Array of model types that pertain to the model	source types: article, book, url, media, youtube, or episode collection types: anthology, list, periodical, rss, website, channel, podcast, or series The contributor model has no types itself.
languages	Array of ISO 639 language codes.
collection_ids	Array of integer collection IDs.
contributor_ids	Array of integer contributor IDs.
category_ids	Array of integer category IDs.
classification_ids	Array of integer classification IDs (denomination IDs).
external_ids	Array of integer / string external IDs.
team_ids	Array of integer team IDs.
user_ids	Array of integer user IDs.
locked	Boolean for whether model is locked.
min_weight / max_weight	Integers 1-5 for range of weight value.
min_rating / max_rating	Integers 1-5 for range of rating value.
min_num_views / max_num_views	Integers for # views range.
min_num_impressions / max_num_impressions	Integers for # impressions range.
min_num_referrals / max_num_referrals	Integers for # referrals range.
min_published_on / max_published_on	ISO 8601 dates for published range.
min_created_at / max_created_at	ISO 8601 dates for created range.
min_updated_at / max_updated_at	ISO 8601 dates for updated range.

Caching #

The semantic search endpoint supports caching. The entirety of the JSON input is used to match any cached response, meaning all parameters must match a previously cached value in order for the cache to be used.

Learn more about how caching works in our system.