This page is about version 1.63.0 of the app, which is not the most recent version. The latest stable version is 1.63.2.

This article serves as a comprehensive guide to the GraphQL API provided by the Rewriter app. This API allows managing internal URLs and URL redirects.

Routes stored in the Rewriter commonly have complex paths, since they communicate with other systems and databases. To improve client-side usage and SEO rankings, the Rewriter app has, in the definition of the routes, the standard paths along with canonical (shorter) paths. For instance, the standard path to a product is /_v/segment/routing/vtex.store@2.x/product/:id/:slug/p, while the canonical path to a product is /:slug/p.

The Rewriter app is responsible for three main types of routes: product, search, and navigation routes.

The first two are first-class entities in Rewriter, meaning Rewriter identifies these routes and directly forwards them to the rendering pipeline.

Navigation routes, in turn, are client-side defined routes related to custom paths and VTEX IO pre-defined templates, such as department, brand, and category routes. These routes can have a canonical path and a search query string.

In Rewriter, navigation routes are identified by the internal type, and routes used to redirect a route from one path to another are identified by the redirect type.

The table below summarizes the classification of routes used in the API.

Type of route	Description
Internal	Identifies navigation routes. Its standard path can have segments specifying the communication with other systems such as databases or apps, possibly making them long. It can be associated with a canonical path, omitting some segments, for improved client-side usage and SEO ranking.
Redirect	Navigation route that redirects one path to another. There are various reasons to use a redirect including URL changes, content removal, SEO and navigation improvements, and others.

Rewriter includes functionalities to:

• Create an internal route.
• Create a canonical path related to an internal route.
• Create a redirect route.
• Delete an internal route.
• Delete a canonical path related to an internal route.
• Delete a redirect route.
• Create translated URLs for cross-border stores.

In the following sections are the definitions of endpoints and parameter descriptions of the Rewriter GraphQL API.

Field	Type	Description
redirect	QueryRedirect!	Provides redirect routes data. Redirect routes are used to redirect a route from one path to another.
internal	QueryInternal!	Provides internal routes data. Internal routes are navigation routes.

Field	Type	Description
redirect	MutateRedirect!	Updates or deletes redirect routes data according to the provided arguments. Redirect routes are used to redirect a route from one path to another.
internal	MutateInternal!	Updates or deletes internal routes data according to the provided arguments. Internal routes are navigation routes.

Arguments must be provided by the user. The exclamation mark ! indicates that a type cannot be nullable.

Field	(argument)	Type	Description
get		Redirect	Returns information regarding a specific redirect route, given its related path and locator.
path		String!	The path of the desired route to fetch data.
locator		RouteLocator	The RouteLocator object, containing information about the store locale and route origin.
listRedirects		ListRedirectsResponse!	Lists all redirect routes.
limit		Int	The number of ListRedirectsResponse objects to be displayed at once.
next		String	The argument used to fetch more internal routes from ListRedirectsResponse. It must be empty in the first query and, in the following, filled in with the string previously obtained from the ListRedirectsResponse object.

Field	(argument)	Type	Description
get		Internal	Returns information regarding a specific internal route, given its related path and locator
path		String!	The path of the desired route to fetch data.
locator		RouteLocator	The RouteLocator object, containing information about the store locale and route origin.
listInternals		ListInternalsResponse!	Lists all internal routes.
limit		Int	The number of ListInternalsResponse objects to be displayed at once.
next		String	The argument used to fetch more internal routes from ListInternalsResponse. It must be empty in the first query and, in the following, filled in with the string previously obtained from the ListInternalsResponse object.
routes		[RoutesByBinding!]	Lists all internal routes of a specific type (e.g. deparment routes, category routes, etc.) and its related binding, which is an identifier for each store locale.
locator		EntityLocator	The EntityLocator object, containing information about the entity type of the routes to be listed.

Field	(argument)	Type	Description
save		Redirect	Creates or updates a redirect route according to the provided arguments.
route		RedirectInput!	The data regarding the redirect route to be created or updated.
saveMany		Boolean!	Creates or updates many redirect routes according to the provided arguments.
routes		[RedirectInput!]!	The data regarding the redirect routes to be created or updated.
delete		Redirect	Deletes a redirect route according to the provided arguments.
path		String!	The path of the route to be deleted.
locator		RouteLocator	The EntityLocator object, containing information about the entity type of the route to be deleted.
deleteMany		Boolean!	Deletes many redirect route according to the provided arguments.
paths		[String!]!	The paths of the routes to be deleted.
locators		[RouteLocator!]	The EntityLocator objects, containing information about the entity type of the routes to be deleted.

Field	(argument)	Type	Description
save		Internal	Creates or updates an internal route according to the provided arguments.
route		InternalInput!	The data regarding the internal route to be created or updated.
saveMany		Boolean!	Creates or updates many internal routes according to the provided arguments.
routes		[InternalInput!]!	The data regarding the internal routes to be created or updated.
delete		Internal	Deletes an internal route according to the provided arguments.
path		String!	The path of the route to be deleted.
locator		RouteLocator	The EntityLocator object, containing information about the entity type of the route to be deleted.
deleteMany		Boolean!	Deletes many internal routes according to the provided arguments.
paths		[String!]!	The paths of the routes to be deleted.
locators		[RouteLocator!]	The EntityLocator objects, containing information about the entity type of the routes to be deleted.

Field	Type	Description
from	String!	The route path.
declarer	String!	The app that originally defined the route in a routes.json file. For VTEX IO pre-defined routes, the declarer value is vtex.store@2.x.
type	String!	The route entity type defined in the declarer app, which can be: department, category, subcategory, brand, etc.
id	String!	The entity type id. For example, a deparment id.
query	JSON	The query string parameters of a route.
binding	String!	The id of the binding which the route is available. Keep in mind: Every store has a binding id related to its store locale. Hence, cross-border stores always have more than one binding, while accounts with a single storefront have only one binding id.
endDate	String	The date a route stops being valid. Keep in mind: The endDate value for permanent routes is null.
imagePath	String
imageTitle	String
routesVersion	Float	The current routes version. Keep in mind: If the routesVersion value is null or different from the current version, the route is not currently available in the store.
resolveAs	String	Alias paths of a route, meaning that the route will resolve the paths defined in the resolveAs field Keep in mind: The resolveAs parameter must always be defined in the catalog's default language.
origin	String	A string that defines the origin of the route, for example: user-canonical
disableSitemapEntry	Boolean	The boolean value that indicates if a route is included (False) or not (True) in the store's sitemap.

Field	Type	Description
routes	[Internal!]	Returns the demanded information from the Internal object for each route.
next	String	Returns a string to be used as the next argument of the succeeding listInternals query to fetch more data. When next returns null, all data have already been fetched.

Field	Type	Description
binding	String!	The id of the binding which the route is available. Keep in mind: Every store has a binding id related to its store locale. Hence, cross-border stores always have more than one binding, while accounts with a single storefront have only one binding id.
route	String!	Returns the route path.

Field	Type	Description
from	String!	The original route path.
to	String!	The route redirect path.
endDate	String	The date a redirect route stops being valid. Keep in mind: The endDate value for permanent routes is null.
type	RedirectTypes!	The route type: temporary or permanent.
binding	String!	The id of the binding which the route is available. Keep in mind: Every store has a binding id related to its store locale. Hence, cross-border stores always have more than one binding, while accounts with a single storefront have only one binding id.
origin	String	A string that defines the origin of the route, for example: user-canonical

Field	Type	Description
routes	[Redirect!]	Returns the demanded information from the Redirect object for each route.
next	String	Returns a string to be used as the next argument of the succeeding listInternals query to fetch more data. When next returns null, all data have already been fetched.

Field	Type	Description
id	String!	The entity type id. For example, a deparment id.
type	String!	The route entity type, which can be: department, category, subcategory, brand , etc

Field		Type	Description
from		String!	The route path.
declarer		String!	The app that originally defined the route in a routes.json file. For VTEX IO pre-defined routes, the declarer value is vtex.store@2.x.
type		String!	The route entity type, which can be: department, category, subcategory, brand , etc
id		String!	The entity type id. For example, a deparment id.
query		JSON	The query string parameters of a route.
binding		String	The id of the binding which the route is available. Keep in mind: Every store has a binding id related to its store locale. Hence, cross-border stores always have more than one binding, while accounts with a single storefront have only one binding id.
endDate		String	The date a route stops being valid. Keep in mind: The endDate value for permanent routes is null.
imagePath		String
imageTitle		String
resolveAs		String	Alias paths of a route, meaning that the route will resolve the paths defined in the resolveAs field. Keep in mind: The resolveAs parameter must always be defined in the catalog's default language.
origin		String	A string that defines the origin of the route, for example: user-canonical
disableSitemapEntry		Boolean	The boolean value that indicates if a route is included (False) or not (True) in the store's sitemap.

Field		Type	Description
from		String!	The original route path.
to		String!	The route redirect path.
endDate		String	The date a route stops being valid. Keep in mind: The endDate value for permanent routes is null.
type		RedirectTypes!	The route type: temporary or permanent.
binding		String	The id of the binding which the route is available. Keep in mind: Every store has a binding id related to its store locale. Hence, cross-border stores always have more than one binding, while accounts with a single storefront have only one binding id.
origin		String	A string that defines the origin of the route, for example: user-canonical

Field		Type	Description
from		String!	The original route path.
binding		String!	The id of the binding which the route is available. Keep in mind: Every store has a binding id related to its store locale. Hence, cross-border stores always have more than one binding, while accounts with a single storefront have only one binding id.

Value
PERMANENT
TEMPORARY