Skip to main content

Ask as Web Search

Overview​

In this guide we will show you how to ask a question as a web search.

Prerequisites​

  • apiKey: The API key you want to use to ask a question. (Get Assistant API Key)
  • assistantId: The ID of the assistant you want to ask a question to.
  • conversationId: The ID of the conversation you want write in. (Create a Conversation)
  • conversationToken: The token of the conversation you want to write in. (Create a Conversation)

Request​

The request is the same as the Ask a Question endpoint, but with the addition of the webSearch parameter set to true.

Endpoint​

Make a POST request to the following endpoint: 

https://api.pupau.ai/chat-bots/:assistantId/conversations/:conversationId/queries?sse=true&webSearch=true
  • webSearch: a boolean that indicates if the web search is enabled.
  • sse: a boolean that indicates if the response should be streamed. To know more about SSE: Wikipedia

Request Headers​

Api-Key: <apiKey>
Conversation-Token: <conversationToken>

Request Body​

{
    "request": "Here are some files, what do you think about them?",
    "attachments": ["attachment_id_1", "attachment_id_2"]
}
  • request: The question you want to ask to the assistant.
  • attachments: The attachments you want to send to the assistant, as an array of Strings. Each String is the ID of an attachment.

If you want to send an attachment, you need to upload it first. (Upload an Attachment).
If you want to get the id and info of an attachment, you can use the Get Attachments endpoint.

Response SSE​

If you set the sse parameter to true, you will receive a stream of "data" JSON objects.
Here is an example of the stream:

data: {
    "id": "idabc",
    "type": "WEBSEARCH",
    "enabled": true,
    "assistantName": "My Assistant",
    "imageUuid": "11111111-3333-2222-0000-111111111111",
    "cause": null,
    "chatBotId": "id123"
}

data: {
    "id":"idabc",
    "type":"WEBSEARCH_QUERY",
    "query":"Cats",
    "language":"en",
    "country":"US",
    "results":2,
    "chatBotId":"id123"
}

data: {
    "id": "idabc",
    "type": "WEBSEARCH_INFO",
    "attachment": {
        "id": "idatt",
        "type": "TEXT"
    },
    "chatBotId": "id123",
    "info": {
        "searchParameters": {
            "q": "Cats",
            "gl": "us",
            "hl": "en",
            "type": "search",
            "num": 2,
            "engine": "google"
        },
        "organic": [
            {
                "title": "Cats",
                "link": "https://www.cats.com/",
                "snippet": "Cats are a group of mammals that are known for their ability to purr and meow. They are also known for their ability to climb trees and jump from high places. Cats are a popular pet animal, and they are often kept as indoor pets.",
                "position": 1
            },
            {
                "title": "Cats Musical",
                "link": "https://www.cats-musical.com/",
                "snippet": "Cats is a musical with a book by T.S. Eliot, music by Andrew Lloyd Webber, and lyrics by T.S. Eliot and John Kander. It is based on the 1981 stage musical Cats, which was based on T.S. Eliot's 1939 Old Possum's Book of Practical Cats.",
                "rating": 4.5,
                "ratingCount": 42,
                "attributes": {
                    "Type": "Musical",
                    "Year": "2024"
                },
                "sitelinks": [
                    {
                        "title": "Cats Musical",
                        "link": "https://www.cats-musical.com/"
                    },
                    {
                        "title": "Cats Musical Info",
                        "link": "https://www.cats-musical-info.com/"
                    }
                ],
                "position": 2
            }
        ],
        "images": [
            {
                "title": "Cats 2025 Wall Calendar",
                "imageUrl": "https://www.calendars-funny.com/images/cats-2025-wall-calendar.jpg",
                "link": "https://www.calendars-funny.com/"
            },
            {
                "title": "365 Cats pictures",
                "imageUrl": "https://www.cats.com/images/365-cats-pictures.jpg",
                "link": "https://www.cats.com/"
            }
        ],
        "relatedSearches": [
            {
                "query": "Cats species"
            },
            {
                "query": "Cats 2025"
            }
        ],
        "credits": 1
    }
}

data: {
    "id": "idabc",
    "message": "Cats are ",
    "assistantName": "My Assistant",
    "imageUuid": "11111111-3333-2222-0000-111111111111",
    "chatBotId": "id123"
}

data: {
    "id": "idabc",
    "message": "mammals known for ",
    "assistantName": "My Assistant",
    "imageUuid": "11111111-3333-2222-0000-111111111111",
    "chatBotId": "id123"
}

data: {
    "id": "idabc",
    "message": "their ability to meow.",
    "assistantName": "My Assistant",
    "imageUuid": "11111111-3333-2222-0000-111111111111",
    "chatBotId": "id123"
}

data: {
    "id": "idabc",
    "chatBotId": "id123",
    "type": "context_info",
    "info": {
        "credit": 12,
        "availableContext": 204800,
        "usedContext": 4175,
        "outputTokens": 196,
        "userQuery": 2
    }
}

data: {
    "id": "idabc",
    "message": "",
    "last": true,
    "assistantName": "My Assistant",
    "imageUuid": "11111111-3333-2222-0000-111111111111",
    "chatBotId": "id123"
}

Response REST​

If you set the sse parameter to false, you will receive a JSON object
Here is an example of the response:

{
    "id123": {
        "errors": [],
        "info": [
            {
                "id": "idabc",
                "type": "WEBSEARCH",
                "enabled": true,
                "assistantName": "My Assistant",
                "imageUuid": "11111111-3333-2222-0000-111111111111",
                "cause": null,
                "chatBotId": "id123"
            },
            {
                "id": "idabc",
                "type": "WEBSEARCH_QUERY",
                "query": "Cats",
                "language": "en",
                "country": "US",
                "results": 2,
                "chatBotId": "id123"
            },
            {
                "id": "idabc",
                "type": "WEBSEARCH_INFO",
                "attachment": {
                    "id": "idatt",
                    "type": "TEXT"
                },
                "chatBotId": "id123",
                "info": {
                    "searchParameters": {
                        "q": "Cats",
                        "gl": "us",
                        "hl": "en",
                        "type": "search",
                        "num": 2,
                        "engine": "google"
                    },
                    "organic": [
                        {
                            "title": "Cats",
                            "link": "https://www.cats.com/",
                            "snippet": "Cats are a group of mammals that are known for their ability to purr and meow. They are also known for their ability to climb trees and jump from high places. Cats are a popular pet animal, and they are often kept as indoor pets.",
                            "position": 1
                        },
                        {
                            "title": "Cats Musical",
                            "link": "https://www.cats-musical.com/", 
                            "snippet": "Cats is a musical with a book by T.S. Eliot, music by Andrew Lloyd Webber, and lyrics by T.S. Eliot and John Kander. It is based on the 1981 stage musical Cats, which was based on T.S. Eliot's 1939 Old Possum's Book of Practical Cats.",
                            "position": 2
                        }
                    ],
                    "images": [
                        {
                            "title": "Cats 2025 Wall Calendar",
                            "imageUrl": "https://www.calendars-funny.com/images/cats-2025-wall-calendar.jpg",
                            "link": "https://www.calendars-funny.com/"
                        },
                        {
                            "title": "365 Cats pictures",
                            "imageUrl": "https://www.cats.com/images/365-cats-pictures.jpg",
                            "link": "https://www.cats.com/"
                        }
                    ],
                    "relatedSearches": [
                        {
                            "query": "Cats species"
                        },
                        {
                            "query": "Cats 2025"
                        }
                    ],
                    "credits": 1
                }
            },
            {
                "id": "idabc",
                "chatBotId": "id123",
                "type": "context_info",
                "info": {
                    "credit": 9,
                    "availableContext": 204800,
                    "usedContext": 4763,
                    "outputTokens": 414,
                    "userQuery": 2
                }
            }
        ],
        "message": "The message of the assistant..."
    }
}

Response Fields​

In the REST response, the message parameter is the full response of the assistant.

In the SSE response, the data objects with the message parameter contains each a part of the response of the assistant.

Other than the messages, these are the main objects in the response, categorized by the type parameter:

  • WEBSEARCH: This object contains basic information about the assistant used for the web search, like the assistant name and its image uuid.
  • WEBSEARCH_QUERY: This object contains the query sent to the web search and other useful information like the language, the country and the number of results found.
  • WEBSEARCH_INFO: This object contains the information returned by the web search:
    • organic: This array contains the sources used by the web search to answer the query
    • images: This array contains the images related to the query
    • relatedSearches: This array contains a list of possible searches related to the query
    • credits: The number of credits used for this response
  • context_info: This object contains the context information of the assistant, like the credits used in this response, the available context, the used context, the output tokens, and the user query tokens.