> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/commerce-openapis/admin/seo/update-an-seo-configuration.md).

# Update an SEO configuration

Fully updates an SEO configuration. `url`, `title` and `description` must all be present in the body; a body that leaves any one of them out is answered with a validation error.

The new `url` must not belong to another configuration. Sending the configuration's own URL unchanged is accepted.

Omitting `attributes` leaves the stored attributes untouched; sending it replaces them entirely.

```json
{"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"tags":[{"name":"SEO","description":"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.\n\nA 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.\n\n## Core Capabilities\n\n**1. Listing & Filtering**\n* Retrieve a paginated list of SEO configurations.\n* Filter by URL, title and description with case-insensitive partial matching, by keywords with an exact match, and by creation or modification date.\n\n**2. Configuration Lifecycle Management**\n* Create a configuration for a URL, fully or partially update it, and delete it permanently.\n\n**3. Social Media & Custom Tags**\n* Alongside the fixed fields, each configuration carries a set of **attributes** whose shape is defined by the SEO attribute schema configured for the project.\n\n**4. Spreadsheet Bulk Update**\n* 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.\n\n## Fields\n\n| Field | Description |\n|-------|-------------|\n| `url` | The storefront path the configuration applies to. Required, unique across all configurations, and limited to 512 characters. |\n| `title` | The page title rendered in the head of the page. Required, limited to 512 characters. |\n| `description` | The meta description of the page. Required, limited to 1000 characters. |\n| `keywords` | The meta keywords of the page. Optional; may be left out or sent as `null`, and has no length limit. |\n| `attributes` | Social media and custom tags, given as a JSON object. Optional. |\n| `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. |\n\n## Attributes\n\nThe 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.\n\nTwo rules govern how attributes are handled:\n\n* 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.\n* 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.\n\n## Bulk Update File Format\n\nThe bulk update operation accepts a single CSV or XLS file whose first row holds the column names.\n\n| Rule | Detail |\n|------|--------|\n| Accepted file types | CSV (`text/csv`) and XLS (`application/vnd.ms-excel`). Any other type is rejected. |\n| 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. |\n| Required column | `url`. A file without it is rejected. |\n| 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. |\n| 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. |\n| 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. |\n| Empty cells | An empty cell in `title`, `description` or `keywords` is skipped rather than written, so it leaves the stored value untouched. |\n| 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. |\n\nA CSV file may separate its columns with a semicolon (`;`), a comma (`,`) or a vertical bar (`|`).\n\n## Error Codes\n\nRequests that are well-formed but conflict with a business rule are answered with `406 Not Acceptable` and carry one of the following codes.\n\n| Code | Meaning |\n|------|---------|\n| `seo_100` | A configuration already exists for the given URL. |\n| `unacceptable_file_extension_100` | The uploaded file is neither CSV nor XLS. |\n| `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. |\n| `excel_100_1` | The uploaded file could not be read as a spreadsheet, because its file extension is not one the reader recognises. |\n| `missing_data_column_100_1` | The uploaded file does not contain the required `url` column. |\n| `redundant_data_column_100_1` | The uploaded file contains a column that is neither a configuration field nor a defined attribute. |\n\n## Dynamic Settings & Environment Variables\n\nNo 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.\n\n**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."}],"servers":[{"description":"Omnitron Remote Proxy (external access — recommended)","url":"https://{omnitron_url}/api/v1/remote/{channel_id}","variables":{"omnitron_url":{"default":"sandbox.akinon.com","description":"Omnitron server URL (e.g., {omnitron.akinon.com})"},"channel_id":{"default":"1","description":"The channel identifier the remote request is routed through"}}},{"description":"Commerce API Server (internal / direct access only)","url":"https://{commerce_url}/api/v1","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Internal commerce server URL, reachable only from within the Omnitron network"}}}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Token credential sent in the Authorization header, in the form: `Token <your-token>`. Requires a staff (admin) account."}},"schemas":{"SeoRequest":{"type":"object","description":"Request body for creating an SEO configuration or fully updating an existing one. `url`, `title` and `description` are required; the remaining fields are optional.","properties":{"url":{"type":"string","maxLength":512,"description":"The storefront path the configuration applies to. Must not already belong to another configuration."},"title":{"type":"string","maxLength":512,"description":"The page title rendered in the head of the page."},"description":{"type":"string","maxLength":1000,"description":"The meta description of the page."},"keywords":{"type":["string","null"],"description":"The meta keywords of the page. May be left out or sent as `null`."},"attributes":{"type":"object","description":"The social media and custom tags of the page, keyed by the entries of the SEO attribute schema configured for the project. Sending this field replaces the stored attributes entirely, and leaving it out keeps them as they are.","additionalProperties":true}},"required":["url","title","description"]},"Seo":{"type":"object","description":"An SEO configuration — the search engine and social media metadata of a single storefront URL.","properties":{"pk":{"type":"integer","description":"The unique identifier of the SEO configuration.","readOnly":true},"created_date":{"type":"string","format":"date-time","description":"When the configuration was created.","readOnly":true},"modified_date":{"type":"string","format":"date-time","description":"When the configuration was last modified.","readOnly":true},"attributes":{"type":"object","description":"The social media and custom tags of the page, keyed by the entries of the SEO attribute schema configured for the project. Translatable entries are returned in the language active for the request.","additionalProperties":true},"url":{"type":"string","maxLength":512,"description":"The storefront path the configuration applies to. Unique across all configurations."},"title":{"type":"string","maxLength":512,"description":"The page title rendered in the head of the page."},"description":{"type":"string","maxLength":1000,"description":"The meta description of the page."},"keywords":{"type":["string","null"],"description":"The meta keywords of the page, or `null` when none are stored."},"attributes_kwargs":{"type":"object","description":"Supplementary detail the server derives for the stored attributes, such as the labels of grouped tags. Read-only: it is returned in responses and ignored if sent.","additionalProperties":true,"readOnly":true}}},"ValidationError":{"type":"object","description":"Returned when the request contains invalid or missing data. Errors are grouped by the field they apply to: each key is the name of a field from the request and its value is a list of one or more messages describing what is wrong with that field. Messages that do not belong to any single field are grouped under `non_field_errors`.","properties":{"non_field_errors":{"type":"array","description":"Error messages that apply to the request as a whole rather than to a specific field.","items":{"type":"string"}}},"additionalProperties":{"type":"array","description":"The list of error messages for the field named by the key.","items":{"type":"string"}}},"Error":{"type":"object","description":"An error response.","properties":{"detail":{"type":"string","description":"A human-readable description of the error."}},"additionalProperties":true},"SeoBusinessError":{"type":"object","description":"Returned when a request is valid in form but violates a business rule of the SEO configurations. The message describes the rule that was violated, and a stable code identifies it. The codes these endpoints raise are listed under **Error Codes** in the section introduction.","properties":{"non_field_errors":{"type":"string","description":"A human-readable message describing the business rule that was violated."},"error_code":{"type":"string","description":"A stable code identifying the specific business rule violation."}},"additionalProperties":true}},"responses":{"ValidationError":{"description":"The request contains invalid or missing data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"Unauthorized":{"description":"Authentication credentials were not provided or are invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The authenticated user does not have administrator privileges.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SeoNotFound":{"description":"The requested SEO configuration does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SeoAlreadyExists":{"description":"Another configuration already uses the given URL (`seo_100`). A URL that is already taken is normally reported as a validation error on the `url` field with `400`; this response is returned when the conflicting configuration is created by another request at the same moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoBusinessError"}}}}}},"paths":{"/seo/{id}/":{"put":{"tags":["SEO"],"operationId":"updateSeoConfiguration","summary":"Update an SEO configuration","description":"Fully updates an SEO configuration. `url`, `title` and `description` must all be present in the body; a body that leaves any one of them out is answered with a validation error.\n\nThe new `url` must not belong to another configuration. Sending the configuration's own URL unchanged is accepted.\n\nOmitting `attributes` leaves the stored attributes untouched; sending it replaces them entirely.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoRequest"}}}},"responses":{"200":{"description":"The updated SEO configuration.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seo"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/SeoNotFound"},"406":{"$ref":"#/components/responses/SeoAlreadyExists"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://apidocs.akinon.com/commerce-openapis/admin/seo/update-an-seo-configuration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
