The Bulk API provides an efficient interface for making multiple Search / Recommendations / Q&A requests in one API call. These requests will be executed concurrently at the Miso side, and returned at once when all of them are finished. This API is particularly useful when you need to invoke multiple Miso APIs to respond to a user request. Using this API, you can batch multiple API calls into one, and significantly save the network round-trip times.

Request schema

The request schema for this API call is as follow:

POST /v1/bulk
{
  "requests": [
    {
      "api_name": "search/search",
      "body": { ... }
    },
    {
      "api_name": "recommendation/product_to_product",
      "body": { ... }
    },
    ...
  ]
}

Each request object must contain:

• api_name: name of the API you want to access. The name must contain a slash /. For example, search/search for search requests, search/autocomplete for autocomplete requests.
• body: the complete request body as if you are making the API request individually.

Any errors in one of the requests will be returned, and will not prevent other requests from being executed.

Response Schema

Bulk API endpoint will return the API responses in the same order as they appear in the request. For example, if the Bulk API request is like the following:

POST /v1/bulk
{
  "requests": [
    {... request 1 ...},
    {... request 2 ...}
  ]
}

The response will be like:

{
  "data": [
    // response for request 1
    {
      "error": false,
      "status_code": 200,
      "body": { ... }
    },
    // response for request 2
    {
      "error": false,
      "status_code": 200,
      "body": { ... }
    }
  ]
}

Each response object will contain the following fields:

• error: whether there was an error with the request. Check this field to determine whether to perform error handling.
• status_code: status code of the request.
• body: the response body of the request (as if the request was sent individually).

Let's see a complete example with MovieLens data. The following requests will issue two requests in one API call that return the Sci-Fi movies directed by Ridley Scott, and James Cameron respectively in the first and second responses:

POST /v1/bulk
{
  "requests": [
    {
      "api_name": "search/search",
      "body": {
        "user_id": "test_user",
        "q": "sci-fi",
        "fq": "custom_attributes.director:\"Ridley Scott…"
      }
    },
    {
      "api_name": "search/search",
      "body": {
        "user_id": "test_user",
        "q": "sci-fi",
        "fq": "custom_attributes.director:\"James Camero…"
      }
    }
  ]
}

The response will be like:

{
  "data": [
    {
      "error": false,
      "status_code": 200,
      "body": {
        "data": {
          "took": 136,
          "miso_id": "19ab254c-5fb8-11ec-bd48-b20169940…",
          "products": [
            {
              "product_id": "blade-runner",
              "title": "Blade Runner (1982)"
            }
          ],
          "total": 6,
          "start": 0
        }
      }
    },
    {
      "error": false,
      "status_code": 200,
      "body": {
        "data": {
          "took": 116,
          "miso_id": "19ab254c-5fb8-11ec-bd48-b20169940…",
          "products": [
            {
              "product_id": "avatar",
              "title": "Avatar (2009)"
            }
          ],
          "total": 10,
          "start": 0
        }
      }
    }
  ]
}