# Edara API v3: Brands

Read the [guide](../guide.md) first: authentication, paging, errors, rate limits and the shared `PagedResult`, `BatchResult` and `*Reference` shapes.

- `GET /v3/brands`: Lists brands.
- `GET /v3/brands/{id}`: Gets a brand by id.
- `POST /v3/brands`: Creates a brand.

## Endpoints

### `GET /v3/brands`: Lists brands.

Operation `GetBrands` · permission `read:brand`

**Query string**: `GetBrandsQuery`

| field | type | default | validation | description |
|---|---|---|---|---|
| `offset` | `int?` | 0 | >= 0 | Number of items to skip before returning results. Defaults to 0. |
| `limit` | `int?` | 100 | 1..1000 (out of range → 400) | Maximum number of items to return. Defaults to 100, maximum 1000. |
| `name` | `string` |  |  | Brand name filter. |

**Responses**: OK `PagedResult<BrandResponse>`: Paged list of brands.

**Notes**

- `name` is trimmed and matches brands whose name contains it. A blank `name` means no filter.
- Results are ordered by name, not by id. Brands have no active flag.
- A page past the end returns an empty list with `totalCount` 0, not the real total.

---

### `GET /v3/brands/{id}`: Gets a brand by id.

Operation `GetBrandById` · permission `read:brand`

**Parameters**

| name | in | type | default | description |
|---|---|---|---|---|
| `id` | route | `int` |  | The brand id. |

**Responses**: OK `BrandResponse`: The brand.

---

### `POST /v3/brands`: Creates a brand.

Operation `CreateBrand` · permission `create:brand`

**Body**: `BrandUpsertRequest`

| field | type | default | validation | description |
|---|---|---|---|---|
| `name` | `string` |  | NotEmpty() .MaximumLength(50) | Brand name. |
| `brandManager` | `string` |  | MaximumLength(50) | Optional brand manager. |

**Responses**: Created `BrandResponse`: Brand created.

**Business errors** (HTTP 409, match on `errorCode`):

- `DupplicatedName`: Another brand already uses the same name.
- `NameContainsInvalidSpecialCharacters`: The brand name contains unsupported special characters such as quotes, pipes, commas, backslashes, or angle brackets.

**Notes**

- A `name` that contains a backslash, single quote, pipe, comma, double quote, angle bracket, tab or newline returns `409` with `errorCode` `NameContainsInvalidSpecialCharacters`.
- A duplicate `name` returns `409` with `errorCode` `DupplicatedName`.
- The API does not trim `name`.
- A null `brandManager` is stored as an empty string.
- The response repeats the values you sent plus the new `id`.

## Types

### `BrandResponse`

Response describing a brand.

| field | type | description |
|---|---|---|
| `id` | `int` | Brand identifier. |
| `name` | `string` | Brand name. |
| `brandManager` | `string` | Optional brand manager. |