swagger.json

{
    "swagger": "2.0",
    "info": {
        "version": "1.0.0",
        "title": "Search API"
    },
    "paths": {
        "/indexes/{name}": {
            "post": {
                "description": "Add an object to the index and automatically assign an identifier.\n",
                "security": [
                    {
                        "api_key": []
                    }
                ],
                "responses": {
                    "201": {
                        "description": "The indexed document containing the automatically generated id and supplied fields",
                        "schema": {
                            "type": "object"
                        }
                    },
                    "401": {
                        "description": "A valid authentication token has not been supplied with the request",
                        "schema": {
                            "type": "object"
                        }
                    },
                    "403": {
                        "description": "A valid authentication token was supplied but does not allow access for this operation",
                        "schema": {
                            "type": "object"
                        }
                    },
                    "413": {
                        "description": "The size of the object being indexed exceeds the size limit.",
                        "schema": {
                            "type": "object"
                        }
                    }
                }
            },
            "delete": {
                "description": "Deletes an index.\n",
                "security": [
                    {
                        "api_key": []
                    }
                ],
                "responses": {
                    "204": {
                        "description": "Index deleted"
                    },
                    "401": {
                        "description": "A valid authentication token has not been supplied with the request",
                        "schema": {
                            "type": "object"
                        }
                    },
                    "403": {
                        "description": "A valid authentication token was supplied but does not allow access for this operation",
                        "schema": {
                            "type": "object"
                        }
                    }
                }
            },
            "get": {
                "description": "Get objects from the index.\n",
                "security": [
                    {
                        "api_key": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "An array of indexed objects",
                        "schema": {
                            "type": "array",
                            "items": {
                                "type": "object"
                            }
                        }
                    },
                    "401": {
                        "description": "A valid authentication token has not been supplied with the request",
                        "schema": {
                            "type": "object"
                        }
                    },
                    "403": {
                        "description": "A valid authentication token was supplied but does not allow access for this operation",
                        "schema": {
                            "type": "object"
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "id",
                        "in": "query",
                        "description": "Identifiers of the objects to get from the index",
                        "required": true,
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    }
                ]
            },
            "parameters": [
                {
                    "name": "name",
                    "in": "path",
                    "description": "Name of the index in which to create the object",
                    "required": true,
                    "type": "string"
                }
            ]
        },
        "/indexes/{name}/batch": {
            "post": {
                "description": "Perform batch operations on the index",
                "security": [
                    {
                        "api_key": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Operations performed",
                        "schema": {
                            "type": "object",
                            "properties": {
                                "objectIDs": {
                                    "description": "Identifiers of any created objects",
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "A valid authentication token has not been supplied with the request",
                        "schema": {
                            "type": "object"
                        }
                    },
                    "403": {
                        "description": "A valid authentication token was supplied but does not allow access for this operation",
                        "schema": {
                            "type": "object"
                        }
                    },
                    "413": {
                        "description": "The size of an object being indexed exceeds the size limit.",
                        "schema": {
                            "type": "object"
                        }
                    }
                }
            },
            "parameters": [
                {
                    "name": "name",
                    "in": "path",
                    "description": "Name of the index to operate on",
                    "required": true,
                    "type": "string"
                },
                {
                    "name": "operations",
                    "in": "body",
                    "description": "The operations to perform",
                    "required": true,
                    "schema": {
                        "type": "object",
                        "properties": {
                            "requests": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/definitions/BatchOperation"
                                }
                            }
                        }
                    }
                }
            ]
        },
        "/indexes/{name}/move": {
            "post": {
                "description": "Move an index to a new or existing index. When an existing index is given, it will be replaced.",
                "security": [
                    {
                        "api_key": []
                    }
                ],
                "parameters": [
                    {
                        "name": "options",
                        "in": "body",
                        "description": "Options for moving index",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/IndexMoveOptions"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Index moved",
                        "schema": {
                            "type": "object"
                        }
                    },
                    "401": {
                        "description": "A valid authentication token has not been supplied with the request",
                        "schema": {
                            "type": "object"
                        }
                    },
                    "403": {
                        "description": "A valid authentication token was supplied but does not allow access for this operation",
                        "schema": {
                            "type": "object"
                        }
                    }
                }
            },
            "parameters": [
                {
                    "name": "name",
                    "type": "string",
                    "in": "path",
                    "description": "Name of the index to move",
                    "required": true
                }
            ]
        },
        "/indexes/{name}/settings": {
            "put": {
                "description": "Replace the settings for an index.\n",
                "security": [
                    {
                        "api_key": []
                    }
                ],
                "parameters": [
                    {
                        "name": "settings",
                        "in": "body",
                        "description": "The index settings",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/IndexSettings"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Settings saved",
                        "schema": {
                            "$ref": "#/definitions/IndexSettings"
                        }
                    },
                    "401": {
                        "description": "A valid authentication token has not been supplied with the request",
                        "schema": {
                            "type": "object"
                        }
                    },
                    "403": {
                        "description": "A valid authentication token was supplied but does not allow access for this operation",
                        "schema": {
                            "type": "object"
                        }
                    }
                }
            },
            "get": {
                "description": "Get settings from the index.\n",
                "security": [
                    {
                        "api_key": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Settings",
                        "schema": {
                            "$ref": "#/definitions/IndexSettings"
                        }
                    },
                    "401": {
                        "description": "A valid authentication token has not been supplied with the request",
                        "schema": {
                            "type": "object"
                        }
                    },
                    "403": {
                        "description": "A valid authentication token was supplied but does not allow access for this operation",
                        "schema": {
                            "type": "object"
                        }
                    }
                }
            },
            "parameters": [
                {
                    "name": "name",
                    "in": "path",
                    "description": "Name of the index to replace settings on",
                    "required": true,
                    "type": "string"
                }
            ]
        },
        "/indexes/{name}/{objectID}": {
            "delete": {
                "description": "Delete an object by it's identifier.\n",
                "security": [
                    {
                        "api_key": []
                    }
                ],
                "responses": {
                    "204": {
                        "description": "Object deleted"
                    },
                    "401": {
                        "description": "A valid authentication token has not been supplied with the request",
                        "schema": {
                            "type": "object"
                        }
                    },
                    "403": {
                        "description": "A valid authentication token was supplied but does not allow access for this operation",
                        "schema": {
                            "type": "object"
                        }
                    }
                }
            },
            "get": {
                "description": "Get an object by it's identifier.\n",
                "security": [
                  {
                    "api_key": []
                  }
                ],
                "responses": {
                    "200": {
                        "description": "The identified object",
                        "schema": {
                            "type": "object"
                        }
                    },
                    "401": {
                        "description": "A valid authentication token has not been supplied with the request",
                        "schema": {
                            "type": "object"
                        }
                    },
                    "404": {
                        "description": "The object was not found",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    }
                }
            },
            "put": {
                "description": "Create or replace an object in the index.\n",
                "security": [
                    {
                        "api_key": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The object that has replaced another in the index.",
                        "schema": {
                            "type": "object"
                        }
                    },
                    "201": {
                        "description": "The object created in the index.",
                        "schema": {
                            "type": "object"
                        }
                    },
                    "401": {
                        "description": "A valid authentication token has not been supplied with the request",
                        "schema": {
                            "type": "object"
                        }
                    },
                    "403": {
                        "description": "A valid authentication token was supplied but does not allow access for this operation",
                        "schema": {
                            "type": "object"
                        }
                    },
                    "413": {
                        "description": "The size of the object being indexed exceeds the size limit.",
                        "schema": {
                            "type": "object"
                        }
                    }
                }
            },
            "parameters": [
                {
                    "name": "name",
                    "in": "path",
                    "description": "Name of the index to search",
                    "required": true,
                    "type": "string"
                },
                {
                    "name": "objectID",
                    "in": "path",
                    "description": "The identifier of the object to delete",
                    "required": true,
                    "type": "string"
                }
            ]
        },
        "/indexes/{name}/query": {
            "post": {
                "description": "Performs a search on an index\n",
                "security": [
                  {
                    "api_key": []
                  }
                ],
                "responses": {
                    "200": {
                        "description": "Search results",
                        "schema": {
                            "type": "object",
                            "properties": {
                                "hits": {
                                    "type": "array",
                                    "items": {
                                        "type": "object"
                                    }
                                },
                                "facets": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/definitions/Facet"
                                    }
                                },
                                "totalHits": {
                                    "type": "integer",
                                    "description": "Total number of available results"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "A valid authentication token has not been supplied with the request",
                        "schema": {
                            "type": "object"
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "name",
                        "in": "path",
                        "description": "Name of the index to query",
                        "required": true,
                        "type": "string"
                    },
                    {
                        "name": "params",
                        "in": "body",
                        "description": "The search query",
                        "required": true,
                        "schema": {
                            "type": "object",
                            "properties": {
                                "query": {
                                    "type": "string",
                                    "description": "Search keywords"
                                },
                                "filters": {
                                    "type": "array",
                                    "description": "An array of search filter objects. Either 'term' or 'range' is required",
                                    "items": {
                                        "type": "object",
                                        "minProperties": 2,
                                        "maxProperties": 2,
                                        "required": [
                                            "field"
                                        ],
                                        "properties": {
                                            "field": {
                                                "type": "string",
                                                "description": "The field to filter by"
                                            },
                                            "term": {
                                                "type": "string",
                                                "description": "The filter term"
                                            },
                                            "terms": {
                                                "type": "array",
                                                "description": "The filter terms (combined with OR)",
                                                "items": {
                                                    "type": "string",
                                                    "description": "Filter term"
                                                }
                                            },
                                            "range": {
                                                "type": "object",
                                                "description": "The filter range",
                                                "minProperties": 1,
                                                "properties": {
                                                    "from": {
                                                        "type": "number",
                                                        "description": "The range's lower bound"
                                                    },
                                                    "to": {
                                                        "type": "number",
                                                        "description": "The range's upper bound"
                                                    }
                                                }
                                            }
                                        }
                                    }
                                },
                                "page": {
                                    "type": "integer",
                                    "description": "Page of results to return"
                                },
                                "hitsPerPage": {
                                    "type": "integer",
                                    "description": "Number of hits per page"
                                },
                                "sort": {
                                    "type": "array",
                                    "description": "An array of sort options",
                                    "items": {
                                        "type": "object",
                                        "description": "A sort object. If direction is emitted it defaults to asc",
                                        "required": [
                                            "field"
                                        ],
                                        "properties": {
                                            "field": {
                                                "type": "string",
                                                "description": "Field to sort on"
                                            },
                                            "direction": {
                                                "type": "string",
                                                "description": "Sort direction",
                                                "enum": [
                                                    "asc",
                                                    "desc"
                                                ]
                                            }
                                        }
                                    }
                                },
                                "params": {
                                    "type": "string",
                                    "description": "Search parameters encoded as URI compments e.g. `query=shoes&hitsPerPage=5`. Array parameters should be stringified to JSON before encoding. If specified must be the only field in the request body. When using this format the request may optionally supply a 'content-type' header with a value of 'application/x-www-form-urlencoded' to avoid a CORS pre-flight request."
                                }
                            }
                        }
                    }
                ]
            }
        },
        "/indexes/{indexName}/task/{taskID}": {
            "get": {
                "description": "Get details of an indexing task.\n",
                "security": [
                    {
                        "api_key": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Task found",
                        "schema": {
                            "type": "object",
                            "properties": {
                                "status": {
                                    "type": "string",
                                    "description": "The status of the task (published or notPublished)"
                                },
                                "pendingTask": {
                                    "type": "boolean",
                                    "description": "Indicates whether the index has remaining tasks running"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "A valid authentication token has not been supplied with the request",
                        "schema": {
                            "type": "object"
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "indexName",
                        "in": "path",
                        "description": "Name of the index containing the task",
                        "required": true,
                        "type": "string"
                    },
                    {
                        "name": "taskID",
                        "in": "path",
                        "description": "The identifier of the task",
                        "type": "integer",
                        "format": "int32",
                        "required": true
                    }
                ]
            }
        }
    },
    "securityDefinitions": {
        "api_key": {
            "type": "apiKey",
            "name": "Authorization",
            "in": "header"
        }
    },
    "definitions": {
        "Facet": {
            "type": "object",
            "properties": {
                "field": {
                    "type": "string"
                },
                "values": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "description": "An object containing the facet `value` and `count`. Value can be any primative type."
                    }
                }
            }
        },
        "IndexSettings": {
            "type": "object",
            "required": ["searchable_fields", "facets"],
            "properties": {
                "searchable_fields": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "facets": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "field": {
                                "type": "string",
                                "description": "The field name to return as a facet"
                            },
                            "order": {
                                "type": "string",
                                "enum": ["value", "valueDESC", "count", "countDESC"],
                                "description": "The order of facet values"
                            }
                        }
                    }
                }
            }
        },
        "IndexMoveOptions": {
            "type": "object",
            "required": [
                "destination"
            ],
            "properties": {
                "destination": {
                    "type": "string",
                    "description": "The name of the index to move to"
                }
            }
        },
        "BatchOperation": {
            "type": "object",
            "required": [
                "action"
            ],
            "properties": {
                "action": {
                    "type": "string",
                    "enum": [
                        "create",
                        "upsert",
                        "delete"
                    ],
                    "description": "The action to perform on an index"
                },
                "body": {
                    "type": "object",
                    "description": "For create and upsert, the object to index"
                },
                "objectID": {
                    "type": "string",
                    "description": "For upsert and delete, the identifier of the object to act upon"
                }
            }
        },
        "Error": {
            "type": "object",
            "properties": {
                "message": {
                    "type": "string",
                    "description": "A message explaining the error"
                },
                "error": {
                    "type": "string",
                    "description": "An error message"
                },
                "statusCode": {
                    "type": "integer",
                    "format": "int32",
                    "description": "An HTTP status code"
                }
            }
        }
    }
}