For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

Field
Description

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, leave attributes out 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.

Rule
Detail

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.

Code
Meaning

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?