> 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/sites.md).

# Sites

Administrative endpoints for the **sites** registered on the installation. A site pairs a domain name with a display name, and it is the record the platform relies on to know which domain it serves — the value used whenever an absolute link has to be built (e-mail links, sitemaps, password-reset URLs) and wherever content is scoped to a domain.

Most installations serve a single storefront and therefore keep exactly one site. Additional sites are registered when the same installation serves more than one domain.

### Core Capabilities

* **List** the registered sites, paging through and sorting the results.
* **Retrieve** a single site by its identifier.
* **Register** a new site by supplying its domain and display name.
* **Update** a site's domain or display name, either in full or field by field.
* **Read the current site** — the one this installation is configured to serve — without knowing its identifier.

Sites cannot be deleted through this API.

### Site Fields

| Field    | Type    | Description                                                                                                                                            |
| -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `pk`     | integer | Identifier of the site, assigned when it is registered. Read-only.                                                                                     |
| `name`   | string  | Display name of the site, shown wherever the site is presented to staff. Up to 50 characters, and it cannot be left empty.                             |
| `domain` | string  | Domain name the site is served on, for example `www.example.com`. Up to 100 characters, unique across all sites, and it cannot contain spaces or tabs. |

The identifier is exposed as `pk` rather than `id`, so that is also the name used when sorting the list by identifier.

The domain is stored exactly as it is sent. It is expected to be a bare host name — without a scheme such as `https://` and without a trailing path — because those parts are added around it when absolute links are generated.

### Uniqueness

A domain can belong to only one site. A request that would give a site a domain already registered to another site is rejected and the existing site is left untouched. A site keeping its own domain while only its display name changes is not affected by this rule.

The conflict is normally reported as a validation error on the `domain` field. If the domain is instead claimed by another request in the moment between this request being checked and being saved, the rejection is reported as the business error `site_100` described under the create and update operations. In both cases nothing is written.

### Dynamic Settings & Environment Variables

No dynamic settings configured in the management panel affect these endpoints. One server configuration value does:

| Name      | Type    | Default | Effect                                                                                                                                                                                                                                                                                                                                                                                  |
| --------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SITE_ID` | integer | `1`     | Identifies which registered site this installation serves. It selects the record returned by **Read the current site** (`GET /sites/current/`) and has no effect on any other operation. It must point to a site that exists, otherwise the current-site request cannot be served. In deployments that read their configuration from the environment, this value can be supplied there. |

The current site is cached after it is first read, and the cache is cleared whenever a site is registered or updated, so a change is reflected on the next request.


---

# 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/sites.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.
