> 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/bulk-create-or-update-seo-configurations-from-a-file.md).

# Bulk create or update SEO configurations from a file

Uploads a CSV or XLS file that creates or updates many SEO configurations in one request. The accepted file layout is described under **Bulk Update File Format** in the section introduction.

Send the file as `multipart/form-data` with **exactly one** file part; the name of the part is not significant. A request carrying no file, or more than one, is answered with an empty `400` body.

Processing is **asynchronous**. The response only confirms that the file was accepted: its type, delimiter and column names were valid. The rows themselves are applied in the background afterwards, and a row that cannot be applied is skipped silently — there is no response body, no job identifier and no status endpoint to follow up on. Verify the outcome by reading the configurations back from the list or detail paths.

```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."}},"responses":{"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"}}}},"SeoFileError":{"description":"The uploaded file was rejected — its type is neither CSV nor XLS, its columns could not be read, its extension is not one the spreadsheet reader recognises, the required `url` column is missing, or it carries a column that is neither a configuration field nor a defined attribute. The `error_code` field tells the cases apart; the codes are listed under **Error Codes** in the section introduction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoBusinessError"}}}}},"schemas":{"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}}},"paths":{"/seo/bulk_update/":{"post":{"tags":["SEO"],"operationId":"bulkUpdateSeoConfigurations","summary":"Bulk create or update SEO configurations from a file","description":"Uploads a CSV or XLS file that creates or updates many SEO configurations in one request. The accepted file layout is described under **Bulk Update File Format** in the section introduction.\n\nSend the file as `multipart/form-data` with **exactly one** file part; the name of the part is not significant. A request carrying no file, or more than one, is answered with an empty `400` body.\n\nProcessing is **asynchronous**. The response only confirms that the file was accepted: its type, delimiter and column names were valid. The rows themselves are applied in the background afterwards, and a row that cannot be applied is skipped silently — there is no response body, no job identifier and no status endpoint to follow up on. Verify the outcome by reading the configurations back from the list or detail paths.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"The CSV or XLS file holding the configurations. Exactly one file must be sent."}},"required":["file"]}}}},"responses":{"200":{"description":"The file was accepted and is being applied in the background. No response body."},"400":{"description":"The request did not carry exactly one file. No response body."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"406":{"$ref":"#/components/responses/SeoFileError"}}}}}}
```


---

# 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/bulk-create-or-update-seo-configurations-from-a-file.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.
