---
title: Brands API - Create, List & Update Brand Kits
description: Manage brand kits with the PostNitro Embed API. Create, list, read, and update brands with logo, handle, and display settings for your carousels. Full request bodies and examples.
canonical: https://postnitro.ai/docs/embed/api/brands
---

# Brands

A **brand** is the logo, name, and handle that PostNitro stamps onto generated
carousels. These endpoints let you manage the brand kits in your workspace.

All endpoints require the `embed-api-key` header — see
[Authentication](https://postnitro.ai/docs/embed/api/authentication).

## The brand object

```jsonc
{
  "id": "brand_123",
  "name": "PostNitro",          // display name
  "image": "https://...",     // logo URL
  "handle": "@postnitroai",          // social handle
  "isCompanyDetail": false,   // treat as a company (vs personal) brand
  "showName": true,           // render the name on slides
  "showHandle": true,         // render the handle on slides
  "showImage": true           // render the logo on slides
}
```

---

## List brands

```
GET /brand
```

Returns brands in your workspace, most recently updated first.

### Query parameters

| Parameter | Default | Description |
| --- | --- | --- |
| `page` | `1` | Page number (positive integer). |
| `limit` | `10` | Items per page (`1`–`100`). |

### Response `200`

```jsonc
{
  "success": true,
  "data": {
    "brands": [
      {
        "id": "brand_123",
        "name": "PostNitro",
        "image": "https://...",
        "handle": "@postnitroai",
        "isCompanyDetail": false,
        "showHandle": true,
        "showImage": true,
        "showName": true
      }
    ]
  }
}
```

### Errors

| Status | Body | When |
| --- | --- | --- |
| `404` | `{ "success": false, "message": "No brands found" }` | The workspace has no brands. |

---

## Create a brand

```
POST /brand
```

### Request body

```jsonc
{
  "name": "PostNitro",        // required, string
  "handle": "@postnitroai",        // required, string
  "image": "https://...",   // required, string (logo URL)
  "isCompanyDetail": false, // required, boolean
  "showName": true,         // required, boolean
  "showHandle": true,       // required, boolean
  "showImage": true         // required, boolean
}
```

All seven keys are required and **no other** top-level key is accepted — sending
an unknown key is rejected with `422 Extra parameters passed in the body.`

### Example request

```bash
curl -X POST "https://embed-api.postnitro.ai/brand" \
  -H "embed-api-key: $EMBED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "PostNitro",
    "handle": "@postnitroai",
    "image": "https://cdn.example.com/logo.png",
    "isCompanyDetail": false,
    "showName": true,
    "showHandle": true,
    "showImage": true
  }'
```

### Response `200`

```jsonc
{
  "success": true,
  "data": {
    "brand": {
      "id": "brand_123",
      "name": "PostNitro",
      "image": "https://cdn.example.com/logo.png",
      "handle": "@postnitroai",
      "isCompanyDetail": false,
      "showName": true,
      "showHandle": true,
      "showImage": true
    }
  }
}
```

### Errors

| Status | Body | When |
| --- | --- | --- |
| `400` | `{ "error": "Brand name is required" }` | `name` missing or not a string. |
| `400` | `{ "success": false, "message": "Brand handle is required" }` | `handle` missing or not a string. |
| `400` | `{ "success": false, "message": "Brand image is required" }` | `image` missing or not a string. |
| `401` | `{ "error": "You've reached the maximum number of brands that can be added to the organization." }` | Plan brand limit reached. |
| `500` | `{ "success": false, "message": "Error creating Brand", ... }` | Brand could not be created. |

---

## Read a brand

```
GET /brand/:id
```

### Path parameters

| Parameter | Description |
| --- | --- |
| `id` | The brand id. Must belong to your workspace. |

### Response `200`

```jsonc
{
  "success": true,
  "data": {
    "brand": {
      "id": "brand_123",
      "name": "PostNitro",
      "image": "https://...",
      "handle": "@postnitroai",
      "isCompanyDetail": false,
      "showHandle": true,
      "showImage": true,
      "showName": true
    }
  }
}
```

A `404` is returned when no brand with that id exists in your workspace.

---

## Update a brand

```
PUT /brand/:id
```

### Path parameters

| Parameter | Description |
| --- | --- |
| `id` | The brand id. Must belong to your workspace. |

### Request body

Same shape as [create](#create-a-brand) — all seven keys are required by
validation. `name`, `handle`, and `image` are only overwritten when a non-empty
value is sent; the boolean display flags (`isCompanyDetail`, `showName`,
`showHandle`, `showImage`) are always applied.

### Response `200`

```jsonc
{
  "success": true,
  "data": {
    "brand": { "id": "brand_123", "name": "PostNitro", "...": "..." }
  }
}
```

### Errors

| Status | Body | When |
| --- | --- | --- |
| `404` | `{ "success": false, "message": "Brand not found" }` | No brand with that id in your workspace. |
| `500` | `{ "success": false, "message": "Error updating brand", ... }` | Update did not complete. |

---

## Validation & common errors

Request-shape errors return `422 { "status": false, "message": "..." }`:

| `message` | When |
| --- | --- |
| `Brand id is required` | `:id` missing on read/update. |
| `Name is required` / `Image is required` / `Handle is required` | Required body field missing (create/update). |
| `Is company detail is required` / `Show name is required` / `Show handle is required` / `Show image is required` | Required boolean flag missing (create/update). |
| `Page must be a positive integer` / `Limit must be between 1 and 100` | Invalid list pagination. |
| `Extra parameters passed in the body.` | Unknown top-level body key. |

See [Authentication](https://postnitro.ai/docs/embed/api/authentication) for `401` / `402` responses.