NAV
shell

Index

List indexes

curl -X GET
    -H "Authorization: Bearer ..."
    https://afosto.app/api/instant/indexes

200 response code

{
    "data": {
        "id": null,
        "name": "CSV Products",
        "alias": "csv-products",
        "state": "LIVE",
        "source": {
            "id": null,
            "type": "CSV_INTEGRATION"
        },
        "synonyms": null,
        "stop_words": [
            "the",
            "a",
            "an"
        ],
        "ranking_rules": [
            "typo",
            "words",
            "proximity",
            "attribute",
            "exactness",
            "category:asc",
            "sku:desc"
        ],
        "fields": {
            "from": "Category",
            "to": "category",
            "type": "STRING",
            "label": "Category"
        },
        "facet_fields": null,
        "distinct_field": "reference",
        "search_fields": null,
        "display_fields": null,
        "filters": {
            "key": null,
            "type": "STRING",
            "is_processed": null
        },
        "is_active": null,
        "created_at": null,
        "updated_at": null
    },
    "page": {
        "first": "https://afosto.app/api/instant/indexes",
        "next": "https://afosto.app/api/instant/indexes?page[after]=HcT689qLWfUVLhRlbJOYp2GoZ",
        "after": "HcT689qLWfUVLhRlbJOYp2GoZ"
    }
}

401 response code

{
    "error": {
        "code": 401,
        "message": "Unauthorized: invalid or expired authorization header",
        "details": null
    },
    "meta": null
}

403 response code

{
    "error": {
        "code": 403,
        "message": "Forbidden: insufficient scopes for resource",
        "details": null
    },
    "meta": null
}

500 response code

{
    "error": {
        "code": 500,
        "message": "Internal server error: something went wrong on our side",
        "details": null
    },
    "meta": null
}

400 response code

{
    "error": {
        "code": 400,
        "message": "Bad request: invalid filter, pagination or request body",
        "details": null
    },
    "meta": null
}

List all indexes for the authenticated user

HTTP Request

GET https://afosto.app/api/instant/indexes

Query Parameters

Parameter Type Default Description
page[size] integer
page[after] string
sort string

Response fields

Content-type: application/vnd.afosto.api.v1+json

Parameter Type Default Description
name string The name of the index
alias string An alias set on the index by an automatic proces
stop_words array
ranking_rules array
fields.from string The source field
fields.to string The target field
fields.label string The label for the field
distinct_field string The field that's unique for each document

Create index

curl -X POST
    -H "Authorization: Bearer ..."
    -H "Content-Type: application/vnd.afosto.api.v1+json"
    -d '{
    "data": {
        "id": null,
        "name": "CSV Products",
        "alias": "csv-products",
        "source": {
            "id": null,
            "type": "CSV_INTEGRATION"
        },
        "synonyms": null,
        "stop_words": [
            "the",
            "a",
            "an"
        ],
        "ranking_rules": [
            "typo",
            "words",
            "proximity",
            "attribute",
            "exactness",
            "category:asc",
            "sku:desc"
        ],
        "fields": {
            "from": "Category",
            "to": "category",
            "type": "STRING",
            "label": "Category"
        },
        "filters": [
            {
                "key": "category"
            },
            {
                "key": "brand"
            },
            {
                "key": "is_premium"
            }
        ],
        "search_fields": null,
        "display_fields": null
    }
}'
    https://afosto.app/api/instant/indexes

201 response code

{
    "data": {
        "id": null,
        "name": "CSV Products",
        "alias": "csv-products",
        "state": "LIVE",
        "source": {
            "id": null,
            "type": "CSV_INTEGRATION"
        },
        "synonyms": null,
        "stop_words": [
            "the",
            "a",
            "an"
        ],
        "ranking_rules": [
            "typo",
            "words",
            "proximity",
            "attribute",
            "exactness",
            "category:asc",
            "sku:desc"
        ],
        "fields": {
            "from": "Category",
            "to": "category",
            "type": "STRING",
            "label": "Category"
        },
        "facet_fields": null,
        "distinct_field": "reference",
        "search_fields": null,
        "display_fields": null,
        "available_fields": null,
        "filters": {
            "key": null,
            "type": "STRING",
            "is_processed": null
        },
        "last_processed_at": null,
        "is_active": null,
        "has_pending_updates": null,
        "created_at": null,
        "updated_at": null
    },
    "page": null
}

401 response code

{
    "error": {
        "code": 401,
        "message": "Unauthorized: invalid or expired authorization header",
        "details": null
    },
    "meta": null
}

403 response code

{
    "error": {
        "code": 403,
        "message": "Forbidden: insufficient scopes for resource",
        "details": null
    },
    "meta": null
}

500 response code

{
    "error": {
        "code": 500,
        "message": "Internal server error: something went wrong on our side",
        "details": null
    },
    "meta": null
}

400 response code

{
    "error": {
        "code": 400,
        "message": "Bad request: invalid filter, pagination or request body",
        "details": null
    },
    "meta": null
}

Create a new index

HTTP Request

POST https://afosto.app/api/instant/indexes

Input body

Parameter Type Default Description
name string The name of the index
alias string The alias of this index (group)
stop_words array
ranking_rules array
fields.from string The source field
fields.to string The target field
fields.label string The label for the field
filters array

Response fields

Content-type: application/vnd.afosto.api.v1+json

Parameter Type Default Description
name string The name of the index
alias string An alias set on the index by an automatic proces
stop_words array
ranking_rules array
fields.from string The source field
fields.to string The target field
fields.label string The label for the field
distinct_field string The field that's unique for each document

View index

curl -X GET
    -H "Authorization: Bearer ..."
    https://afosto.app/api/instant/indexes/{alias}

200 response code

{
    "data": {
        "id": null,
        "name": "CSV Products",
        "alias": "csv-products",
        "state": "LIVE",
        "source": {
            "id": null,
            "type": "CSV_INTEGRATION"
        },
        "synonyms": null,
        "stop_words": [
            "the",
            "a",
            "an"
        ],
        "ranking_rules": [
            "typo",
            "words",
            "proximity",
            "attribute",
            "exactness",
            "category:asc",
            "sku:desc"
        ],
        "fields": {
            "from": "Category",
            "to": "category",
            "type": "STRING",
            "label": "Category"
        },
        "facet_fields": null,
        "distinct_field": "reference",
        "search_fields": null,
        "display_fields": null,
        "available_fields": null,
        "filters": {
            "key": null,
            "type": "STRING",
            "is_processed": null
        },
        "last_processed_at": null,
        "is_active": null,
        "has_pending_updates": null,
        "created_at": null,
        "updated_at": null
    },
    "page": null
}

401 response code

{
    "error": {
        "code": 401,
        "message": "Unauthorized: invalid or expired authorization header",
        "details": null
    },
    "meta": null
}

403 response code

{
    "error": {
        "code": 403,
        "message": "Forbidden: insufficient scopes for resource",
        "details": null
    },
    "meta": null
}

500 response code

{
    "error": {
        "code": 500,
        "message": "Internal server error: something went wrong on our side",
        "details": null
    },
    "meta": null
}

400 response code

{
    "error": {
        "code": 400,
        "message": "Bad request: invalid filter, pagination or request body",
        "details": null
    },
    "meta": null
}

404 response code

{
    "error": {
        "code": 404,
        "message": "Not found: could not find requested entity",
        "details": null
    },
    "meta": null
}

Show a single index for the tenant.

HTTP Request

GET https://afosto.app/api/instant/indexes/{alias}

URL Parameters

Parameter Type Default Description
alias string The alias of the index

Response fields

Content-type: application/vnd.afosto.api.v1+json

Parameter Type Default Description
name string The name of the index
alias string An alias set on the index by an automatic proces
stop_words array
ranking_rules array
fields.from string The source field
fields.to string The target field
fields.label string The label for the field
distinct_field string The field that's unique for each document

Documents

Upsert documents

curl -X PUT
    -H "Authorization: Bearer ..."
    -H "Content-Type: application/vnd.afosto.api.v1+json"
    -d '{
    "data": null
}'
    https://afosto.app/api/instant/indexes/{id}/documents

204 response code


401 response code

{
    "error": {
        "code": 401,
        "message": "Unauthorized: invalid or expired authorization header",
        "details": null
    },
    "meta": null
}

403 response code

{
    "error": {
        "code": 403,
        "message": "Forbidden: insufficient scopes for resource",
        "details": null
    },
    "meta": null
}

500 response code

{
    "error": {
        "code": 500,
        "message": "Internal server error: something went wrong on our side",
        "details": null
    },
    "meta": null
}

400 response code

{
    "error": {
        "code": 400,
        "message": "Bad request: invalid filter, pagination or request body",
        "details": null
    },
    "meta": null
}

404 response code

{
    "error": {
        "code": 404,
        "message": "Not found: could not find requested entity",
        "details": null
    },
    "meta": null
}

Update or insert a list of documents in the specified index. Enter any additional information in the metadata. Data in the metadata key is not searchable, only retrievable.

HTTP Request

PUT https://afosto.app/api/instant/indexes/{id}/documents

URL Parameters

Parameter Type Default Description
id string The alias of the index

Clear documents

curl -X DELETE
    -H "Authorization: Bearer ..."
    https://afosto.app/api/instant/indexes/{id}/documents

204 response code


401 response code

{
    "error": {
        "code": 401,
        "message": "Unauthorized: invalid or expired authorization header",
        "details": null
    },
    "meta": null
}

403 response code

{
    "error": {
        "code": 403,
        "message": "Forbidden: insufficient scopes for resource",
        "details": null
    },
    "meta": null
}

500 response code

{
    "error": {
        "code": 500,
        "message": "Internal server error: something went wrong on our side",
        "details": null
    },
    "meta": null
}

404 response code

{
    "error": {
        "code": 404,
        "message": "Not found: could not find requested entity",
        "details": null
    },
    "meta": null
}

Delete all documents from the specified index

HTTP Request

DELETE https://afosto.app/api/instant/indexes/{id}/documents

URL Parameters

Parameter Type Default Description
id string

Search

Search documents

curl -X POST
    -H "Authorization: Bearer ..."
    -H "Content-Type: application/vnd.afosto.api.v1+json"
    -d '[]'
    https://afosto.app/api/instant/search/{id}

201 response code

{
    "page": null
}

401 response code

{
    "error": {
        "code": 401,
        "message": "Unauthorized: invalid or expired authorization header",
        "details": null
    },
    "meta": null
}

403 response code

{
    "error": {
        "code": 403,
        "message": "Forbidden: insufficient scopes for resource",
        "details": null
    },
    "meta": null
}

500 response code

{
    "error": {
        "code": 500,
        "message": "Internal server error: something went wrong on our side",
        "details": null
    },
    "meta": null
}

400 response code

{
    "error": {
        "code": 400,
        "message": "Bad request: invalid filter, pagination or request body",
        "details": null
    },
    "meta": null
}

Search documents: The id is the proxy key for a tenant, ex: "afosto". The count is the combined count of the results in all selected indices.

HTTP Request

POST https://afosto.app/api/instant/search/{id}

URL Parameters

Parameter Type Default Description
id string

Search documents

curl -X POST
    -H "Authorization: Bearer ..."
    -H "Content-Type: application/vnd.afosto.api.v1+json"
    -d '[]'
    https://afosto.app/api/instant/search/indexes/{alias}

201 response code

{
    "page": null
}

401 response code

{
    "error": {
        "code": 401,
        "message": "Unauthorized: invalid or expired authorization header",
        "details": null
    },
    "meta": null
}

403 response code

{
    "error": {
        "code": 403,
        "message": "Forbidden: insufficient scopes for resource",
        "details": null
    },
    "meta": null
}

500 response code

{
    "error": {
        "code": 500,
        "message": "Internal server error: something went wrong on our side",
        "details": null
    },
    "meta": null
}

400 response code

{
    "error": {
        "code": 400,
        "message": "Bad request: invalid filter, pagination or request body",
        "details": null
    },
    "meta": null
}

Search documents within a single index, without going throuh a proxy.

HTTP Request

POST https://afosto.app/api/instant/search/indexes/{alias}

URL Parameters

Parameter Type Default Description
alias string The alias of the index

Get settings

curl -X GET
    -H "Authorization: Bearer ..."
    https://afosto.app/api/instant/search/{id}/settings

200 response code

{
    "data": {
        "filters": {
            "show_for": "products",
            "sorting": [
                "category",
                "price"
            ],
            "options_count": 5,
            "max_options_count": 25
        },
        "is_autocomplete": true,
        "indexes": {
            "alias": null,
            "template": {
                "name": "PRODUCTS",
                "mapping": null
            },
            "results_per_page": null,
            "filters": {
                "key": null,
                "label": null,
                "type": "STRING",
                "options_count": 5,
                "max_options_count": 5
            }
        }
    },
    "page": null
}

401 response code

{
    "error": {
        "code": 401,
        "message": "Unauthorized: invalid or expired authorization header",
        "details": null
    },
    "meta": null
}

403 response code

{
    "error": {
        "code": 403,
        "message": "Forbidden: insufficient scopes for resource",
        "details": null
    },
    "meta": null
}

500 response code

{
    "error": {
        "code": 500,
        "message": "Internal server error: something went wrong on our side",
        "details": null
    },
    "meta": null
}

400 response code

{
    "error": {
        "code": 400,
        "message": "Bad request: invalid filter, pagination or request body",
        "details": null
    },
    "meta": null
}

404 response code

{
    "error": {
        "code": 404,
        "message": "Not found: could not find requested entity",
        "details": null
    },
    "meta": null
}

Get the settings for a search engine (proxy)

HTTP Request

GET https://afosto.app/api/instant/search/{id}/settings

URL Parameters

Parameter Type Default Description
id string The alias of the index

Response fields

Content-type: application/vnd.afosto.api.v1+json

Parameter Type Default Description
filters.show_for string The index to show the filters for
filters.sorting array
filters.options_count integer The maximum number of options to show (frontend) for an option without showing all options
filters.max_options_count integer The maximum number of options to show for a filter
is_autocomplete boolean false Whether or not you should perform a search as you type
indexes.filters.options_count integer The maximum number of options to show (frontend) for an option without showing all options
indexes.filters.max_options_count integer The maximum number of options to show for a filter

Measure CTR

curl -X GET
    -H "Authorization: Bearer ..."
    https://afosto.app/api/instant/search/{id}/click

307 response code

{
    "page": null
}

401 response code

{
    "error": {
        "code": 401,
        "message": "Unauthorized: invalid or expired authorization header",
        "details": null
    },
    "meta": null
}

403 response code

{
    "error": {
        "code": 403,
        "message": "Forbidden: insufficient scopes for resource",
        "details": null
    },
    "meta": null
}

500 response code

{
    "error": {
        "code": 500,
        "message": "Internal server error: something went wrong on our side",
        "details": null
    },
    "meta": null
}

400 response code

{
    "error": {
        "code": 400,
        "message": "Bad request: invalid filter, pagination or request body",
        "details": null
    },
    "meta": null
}

404 response code

{
    "error": {
        "code": 404,
        "message": "Not found: could not find requested entity",
        "details": null
    },
    "meta": null
}

Redirect the inital url and measure a ctr

HTTP Request

GET https://afosto.app/api/instant/search/{id}/click

URL Parameters

Parameter Type Default Description
id string The alias of the index

Query Parameters

Parameter Type Default Description
url string The alias of the index
position string The alias of the index
session_id string The alias of the index

Errors

The Afosto API uses the following error codes:

Error Code Meaning
400 Bad request: invalid filter, pagination or request body
401 Unauthorized: invalid or expired authorization header
403 Forbidden: insufficient scopes for resource
404 Not found: could not find requested entity
500 Internal server error: something went wrong on our side