> For the complete documentation index, see [llms.txt](https://docs.premsoft.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.premsoft.de/en/plugins/blog/store-api.md).

# Store API

PremsBlog is fully **headless-capable**: anything you see in the shop is also available through the Shopware Store API. This page is the technical reference for your developer or integrator.

## General

All endpoints live under the standard path `/store-api/prems-blog/...` and follow the exact Shopware conventions. Responses are returned as JSON.

### Required headers

| Header                           | Required              | Meaning                                                                                                                                                                              |
| -------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `sw-access-key`                  | yes                   | Sales-channel access key (found in the administration under *Sales channels → Detail*).                                                                                              |
| `sw-context-token`               | only for POST reviews | Customer context token of an active session.                                                                                                                                         |
| `sw-language-id`                 | no                    | UUID of the desired language; without it the sales channel's default language is used. Translated fields automatically fall back to the default language when no translation exists. |
| `Content-Type: application/json` | for POST              | for request bodies.                                                                                                                                                                  |

### Sales-channel activation

{% hint style="info" %}
If the plugin is **not** active in a sales channel (see [Plugin configuration](/en/plugins/blog/create-and-edit-blog-posts/configuration.md)), every endpoint responds with **404 Not Found**. Visibility stays consistent: whatever the shop hides, the API hides as well.
{% endhint %}

***

## Article list

```http
GET /store-api/prems-blog/articles
```

**Login required:** No

Returns a paginated list of active articles. Honours the activity window (`activeFrom` / `activeTo`) and the plan limits of the active licence.

### Query parameters

| Parameter  | Type   | Default  | Meaning                                              |
| ---------- | ------ | -------- | ---------------------------------------------------- |
| `page`     | int    | 1        | Page number (1-based).                               |
| `limit`    | int    | 12       | Articles per page. Clamped to the plan limit.        |
| `category` | string | —        | One or several category IDs, separated by \`         |
| `tag`      | string | —        | One or several tag IDs, separated by \`              |
| `author`   | string | —        | One or several author IDs, separated by \`           |
| `sort`     | string | `newest` | Sort: `newest`, `oldest`, `title-asc`, `title-desc`. |

### Example response

```json
{
  "apiAlias": "prems_blog_article_list_response",
  "articles": {
    "elements": [
      {
        "id": "0190abc...",
        "title": "My first article",
        "displayDate": "2026-04-12T08:00:00+00:00",
        "author": { "firstName": "Max", "lastName": "Doe" },
        "categories": [ /* ... */ ],
        "tags": [ /* ... */ ],
        "previewMedia": { "url": "..." }
      }
    ],
    "total": 42,
    "page": 1,
    "limit": 12
  }
}
```

***

## Article detail

```http
GET /store-api/prems-blog/article/{articleId}
```

**Login required:** No

Returns a single article including `author`, `categories`, `tags`, `previewMedia` and all approved `reviews`. The translated `content` field carries the complete CMS layout for your app to hydrate.

### Missing or inactive articles

* **404 Not Found** — the article doesn't exist, isn't `active`, falls outside its visibility window, or isn't assigned to the sales channel of the active access key.

***

## Authors

### List

```http
GET /store-api/prems-blog/authors
```

**Login required:** No

Returns a list of active authors.

#### Query parameters

| Parameter | Type   | Default | Meaning                                                                    |
| --------- | ------ | ------- | -------------------------------------------------------------------------- |
| `letter`  | string | —       | Optional A–Z bucket filter (`A`–`Z` or `#` for non-alphabetic last names). |
| `page`    | int    | 1       | Page number.                                                               |
| `limit`   | int    | 25      | Authors per page.                                                          |

### Detail

```http
GET /store-api/prems-blog/author/{authorId}
```

**Login required:** No

Returns the author including `media` (profile picture) and their active articles.

***

## Categories

```http
GET /store-api/prems-blog/category/{categoryId}
```

**Login required:** No

Returns the blog category including its active articles within the activity window. Supports `page`, `limit` and `sort` like the article list.

***

## Tags

```http
GET /store-api/prems-blog/tag/{tagId}
```

**Login required:** No

Same shape as categories — tag including active articles.

***

## Submit a review *(premium)*

```http
POST /store-api/prems-blog/review
```

**Login required:** Yes (`sw-context-token` of a logged-in customer)

### Request body

```json
{
  "articleId": "uuid",
  "points": 5,
  "title": "Great article",
  "content": "Very helpful, thanks!"
}
```

### Behaviour

* `points` is required (1–5). `title` and `content` are optional.
* Successful responses contain the newly created review with status `pending`. The review only becomes public after you approve it in the administration (see [Reviews](/en/plugins/blog/create-and-edit-blog-posts/reviews.md)).

### Errors

* **400 Bad Request** — validation failed (e.g. `points` outside 1–5).
* **401 Unauthorized** — no valid customer context token in the header.
* **404 Not Found** — article doesn't exist or isn't active.

***

## cURL examples

```bash
curl -X GET "https://shop.example/store-api/prems-blog/articles?page=1&limit=10&sort=newest" \
  -H "sw-access-key: SWSCBHFSNTVMAWNZDNFKSHLAYW" \
  -H "Accept: application/json"
```

```bash
curl -X POST "https://shop.example/store-api/prems-blog/review" \
  -H "sw-access-key: SWSCBHFSNTVMAWNZDNFKSHLAYW" \
  -H "sw-context-token: 1a2b3c4d..." \
  -H "Content-Type: application/json" \
  -d '{
    "articleId": "0190abc...",
    "points": 5,
    "title": "Great",
    "content": "Very helpful!"
  }'
```

## OpenAPI schema

A complete endpoint specification including schema and response structures is exposed by the standard Shopware endpoint:

```http
GET /store-api/_info/openapi3.json
```

The blog routes appear there under the prefix `prems-blog`.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.premsoft.de/en/plugins/blog/store-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.