SEO
Administrative endpoints for SEO configurations — the per-URL search engine and social media metadata (page title, meta description, keywords, and social media tags) that the storefront renders in the head of the matching page.
A configuration is bound to a storefront path through its url, which is unique: one configuration describes one page. When a page is requested on the storefront, the configuration whose url matches supplies its metadata.
Core Capabilities
1. Listing & Filtering
Retrieve a paginated list of SEO configurations.
Filter by URL, title and description with case-insensitive partial matching, by keywords with an exact match, and by creation or modification date.
2. Configuration Lifecycle Management
Create a configuration for a URL, fully or partially update it, and delete it permanently.
3. Social Media & Custom Tags
Alongside the fixed fields, each configuration carries a set of attributes whose shape is defined by the SEO attribute schema configured for the project.
4. Spreadsheet Bulk Update
Create or update many configurations at once by uploading a CSV or XLS file. The file is processed in the background after it has been accepted.
Fields
url
The storefront path the configuration applies to. Required, unique across all configurations, and limited to 512 characters.
title
The page title rendered in the head of the page. Required, limited to 512 characters.
description
The meta description of the page. Required, limited to 1000 characters.
keywords
The meta keywords of the page. Optional; may be left out or sent as null, and has no length limit.
attributes
Social media and custom tags, given as a JSON object. Optional.
attributes_kwargs
Read-only supplementary detail the server derives for the stored attributes, such as the labels of grouped tags. It is returned in responses and is ignored if sent.
Attributes
The keys accepted in attributes are not fixed by the API: they come from the SEO attribute schema configured for the project. A typical configuration covers grouped social media tags (Google+, Twitter and Facebook meta tags, each a nested object of text entries such as title, description and image) and a single text entry for a CSS selector class.
Two rules govern how attributes are handled:
On create, and on any update that includes
attributes, the stored attributes are replaced rather than merged — the object sent becomes the complete set of attributes. To keep the stored attributes untouched during a partial update, leaveattributesout of the request body.Attributes that the schema marks as translatable are stored per language. Responses return the values of the language active for the request, falling back to the default language where a translation is missing.
Bulk Update File Format
The bulk update operation accepts a single CSV or XLS file whose first row holds the column names.
Accepted file types
CSV (text/csv) and XLS (application/vnd.ms-excel). Any other type is rejected.
CSV delimiter
One of the three delimiters listed below the table. The delimiter is detected from the file; a file using anything else is rejected.
Required column
url. A file without it is rejected.
Allowed columns
url, title, description, keywords, and one column per attribute defined in the schema. Any other column causes the whole file to be rejected.
Attribute columns
Named after the attribute path, with double underscores between the levels — attributes__css_class for a top-level entry, attributes__facebook__title for an entry inside a grouped tag.
Row handling
A row whose url is empty is skipped. A row is matched to an existing configuration by its url; when no configuration has that URL, one is created.
Empty cells
An empty cell in title, description or keywords is skipped rather than written, so it leaves the stored value untouched.
Attributes are replaced
The attributes of every processed row are cleared and rewritten from the file. A configuration matched by a file that carries no attribute column, or whose attribute cells are empty, therefore loses its stored attributes. Include the attribute columns in the file whenever the stored attributes must survive the update.
A CSV file may separate its columns with a semicolon (;), a comma (,) or a vertical bar (|).
Error Codes
Requests that are well-formed but conflict with a business rule are answered with 406 Not Acceptable and carry one of the following codes.
seo_100
A configuration already exists for the given URL.
unacceptable_file_extension_100
The uploaded file is neither CSV nor XLS.
csv_100_1
The columns of the uploaded CSV file could not be read: its delimiter is not one of the accepted delimiters, or its rows do not all carry the same number of columns.
excel_100_1
The uploaded file could not be read as a spreadsheet, because its file extension is not one the reader recognises.
missing_data_column_100_1
The uploaded file does not contain the required url column.
redundant_data_column_100_1
The uploaded file contains a column that is neither a configuration field nor a defined attribute.
Dynamic Settings & Environment Variables
No dynamic settings (dj_dynamic_settings) are read by these endpoints: listing, filtering, creation, update, deletion and bulk update behave the same regardless of any management-panel setting.
Environment variables: No environment variables are read directly by these endpoints. Two pieces of project configuration nevertheless shape the responses — the SEO attribute schema, which determines the keys accepted in attributes and the columns accepted in a bulk update file, and the language configuration, which determines the language of the returned translatable attribute values.
Last updated
Was this helpful?

