> For the complete documentation index, see [llms.txt](https://publer.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://publer.com/docs/posting/create-posts/post-labels.md).

# Post Labels

Add labels to posts to organize content within a workspace. Labels can be used to filter posts, group content in analytics, and control labeled auto-scheduling timeslots.

For an overview of the different ways to publish and schedule posts, see [Publishing Methods](/docs/posting/create-posts/publishing-methods.md).

### Overview

A label is a workspace scoped tag with a `name` and `color`. You can attach multiple labels to a post.

Labels are created automatically when you use a new label name while creating a post.

When Publer receives a label:

1. It looks for an existing label with the same name in the workspace.
2. If the label exists, it is reused.
3. If it doesn't exist, a new label is created.
4. The label is attached to the post.

Labels are supported when:

* Scheduling a post
* Publishing immediately
* Creating drafts or ideas
* Creating recycling posts
* Creating recurring posts
* Using bulk scheduling

#### Where Labels Go

There are two places where labels can be provided, but they serve different purposes:

<table><thead><tr><th width="241.4140625">Location</th><th width="145.08984375">Format</th><th>Purpose</th></tr></thead><tbody><tr><td><code>posts[].labels</code></td><td>Array of objects</td><td>Recommended for labeling posts</td></tr><tr><td><code>posts[].accounts[].labels</code></td><td>Array of strings</td><td>Used primarily for labeled auto-scheduling</td></tr></tbody></table>

**Use `posts[].labels` for normal post labeling.**

Account-level labels should only be used when you need to select labeled auto-scheduling timeslots.

### Post-Level Labels

The recommended way to add labels is to include a `labels` array directly on the post.

```json5
{
  "bulk": {
    "state": "scheduled",
    "posts": [
      {
        "networks": {
          "facebook": {
            "type": "status",
            "text": "Check out our latest product!"
          }
        },
        "accounts": [
          {
            "id": "66db83154e299efa19a2d8eb",
            "scheduled_at": "2025-05-15T14:30:00Z"
          }
        ],
        "labels": [
          {
            "name": "Product Launch",
            "color": "#84FFBF"
          },
          {
            "name": "Q2 Campaign",
            "color": "#87C7F6"
          }
        ]
      }
    ]
  }
}
```

#### Label Object

<table><thead><tr><th width="156.70703125">Field</th><th width="117.24609375">Type</th><th width="121.359375">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>name</code></td><td>string</td><td>Yes</td><td>Label name</td></tr><tr><td><code>color</code></td><td>string</td><td>No</td><td>Hex color used when creating a new label</td></tr></tbody></table>

#### Label Matching

Labels are matched by name, **case-insensitively**.

For example:

```
Recipes
recipes
RECIPES
```

all refer to the same label.

Whitespace is significant, however. These are different labels:

```
Recipes
 Recipes
Recipes 
```

Trim label names before sending them.

If a label already exists, the color you provide is ignored and the existing color is preserved.

#### Requirements

`posts[].labels` must be an array of objects:

```json5
"labels": [
  {
    "name": "Product Launch",
    "color": "#84FFBF"
  }
]
```

A plain array of strings is not supported at the post level:

```json5
"labels": ["Product Launch"]
```

***

### Account-Level Labels

Account-level labels are provided inside `accounts[]`:

```json5
{
  "bulk": {
    "state": "scheduled",
    "posts": [
      {
        "networks": {
          "facebook": {
            "type": "status",
            "text": "Evergreen tip of the week"
          }
        },
        "accounts": [
          {
            "id": "66db83154e299efa19a2d8eb",
            "labels": ["Recipes"]
          }
        ]
      }
    ]
  }
}
```

Use this format primarily when you want to control **auto-scheduling through labeled timeslots**.

When an account-level label is used:

1. The label is attached to the post.
2. If the label doesn't exist, it is created with the fixed color `#434343`.
3. If no `scheduled_at` is provided, Publer uses the label to select posting-schedule timeslots.

#### Timeslot Selection

This applies when `scheduled_at` is not explicitly provided, including auto-scheduling, `share_next`, and recycling.

<table><thead><tr><th width="211.515625">Labels</th><th>Timeslots used</th></tr></thead><tbody><tr><td>Omitted or <code>[]</code></td><td>Unlabeled timeslots only</td></tr><tr><td>One label</td><td>Timeslots with exactly that label</td></tr><tr><td>Multiple labels</td><td>Timeslots matching any of the provided labels</td></tr></tbody></table>

If one label is provided and no matching timeslot exists, the post fails. There is no fallback to unlabeled timeslots.

If multiple labels are provided and none match, Publer falls back to unlabeled timeslots.

{% hint style="warning" %}
\
Timeslot label matching is **case-sensitive and exact**.

For example, a timeslot labeled `Recipes` does not match `recipes`.

Post-level labels use case-insensitive matching, so these two behaviors are different.<br>
{% endhint %}

Timeslot labels are not available through the API. You can check them in the Publer web app under **Accounts → Posting Schedule**.

#### Account-Level Label Differences

* Color is always `#434343`.
* Recurring occurrences are **not** labeled; only the parent post is.
* For recycling posts, the first label is also stored as the recycling label and returned in `recycling_props.label`.
* If `scheduled_at` is explicitly provided, labels do not affect timeslot selection.

**For normal post categorization, use post-level labels instead.**

***

### Label Colors

Publer supports the following colors in the web app:

<table><thead><tr><th width="226.4140625">Name</th><th>Hex</th></tr></thead><tbody><tr><td>Green</td><td><code>#84FFBF</code></td></tr><tr><td>DarkBlue</td><td><code>#87C7F6</code></td></tr><tr><td>DarkRed</td><td><code>#F28EBB</code></td></tr><tr><td>Orange</td><td><code>#FCB000</code></td></tr><tr><td>Primary</td><td><code>#C0C2D1</code></td></tr><tr><td>Pink</td><td><code>#FF8787</code></td></tr><tr><td>DarkGreen</td><td><code>#73DDD8</code></td></tr><tr><td>LightOrange</td><td><code>#FDDF79</code></td></tr><tr><td>Blue</td><td><code>#C5B7FF</code></td></tr><tr><td>LightBlue</td><td><code>#B6DCF9</code></td></tr></tbody></table>

`#C0C2D1` is the standard default color.

{% hint style="info" %}
\
Colors are only applied when a label is created. Sending a different color for an existing label does not change its color.
{% endhint %}

***

### Scheduling Posts with Labels

Labels work with the standard scheduling endpoint.

#### Example

```json5
{
  "bulk": {
    "state": "scheduled",
    "posts": [
      {
        "networks": {
          "facebook": {
            "type": "status",
            "text": "Check out our latest product!"
          }
        },
        "accounts": [
          {
            "id": "66db83154e299efa19a2d8eb",
            "scheduled_at": "2025-05-15T14:30:00Z"
          }
        ],
        "labels": [
          {
            "name": "Product Launch",
            "color": "#84FFBF"
          }
        ]
      }
    ]
  }
}
```

***

### Reading Labels

`GET /api/v1/posts` returns a `labels` array for each post. See [Posts](/docs/api-reference/posts.md).

```json5
{
  "posts": [
    {
      "id": "68176f0e8bee9dc9b0ce3427",
      "state": "scheduled",
      "type": "status",
      "text": "Check out our latest product!",
      "account_id": "66db83154e299efa19a2d8eb",
      "scheduled_at": "2025-05-15T14:30:00.000+02:00",
      "labels": [
        {
          "id": "6937e35e9823a2eeecfa378f",
          "name": "Product Launch",
          "color": "#84FFBF"
        },
        {
          "id": "69f327eb912f8d1e7e0bc7f0",
          "name": "Q2 Campaign",
          "color": "#87C7F6"
        }
      ]
    }
  ],
  "total": 1
}
```

***

### Updating Labels

Use:

```http
PUT /api/v1/posts/{id}
```

The `labels` property uses the same format as post creation.

```json5
{
  "post": {
    "text": "Updated copy",
    "labels": [
      {
        "name": "Product Launch",
        "color": "#84FFBF"
      }
    ]
  }
}
```

{% hint style="danger" %}
`labels` is a **full replacement set**, not an addition.

If you only want to add a label, first read the current labels and send the complete desired set.

If you omit `labels` entirely, all labels are removed from the post.

If the post currently has `Product Launch` and `Q2 Campaign`, sending only `Product Launch` removes `Q2 Campaign`.<br>
{% endhint %}

For recurring posts, updating labels applies the replacement to the parent post and its occurrences.

Removing a label from its last post does not delete the label from the workspace.

***

### Limitations

* Labels cannot be created independently; they are created when attached to a post.
* Labels are scoped to a workspace.
* Updating labels requires appropriate access to the post.

***

### Best Practices

* **Use post-level labels by default.** Use `posts[].labels` for normal post organization and categorization.
* **Use account-level labels for auto-scheduling.** Only use `accounts[].labels` when you need labeled posting-schedule timeslots.
* **Keep names consistent.** Trim whitespace and use consistent casing.
* **Send the complete label set when updating.** `PUT /api/v1/posts/{id}` replaces the existing labels.
* **Use supported colors** for consistent rendering in the Publer web app.

***

### Related Topics

* [Publishing Methods](/docs/posting/create-posts/publishing-methods.md) — Learn about the different ways to publish and schedule posts
* [Recurring Posts](/docs/posting/create-posts/publishing-methods/recurring-posts.md) — Label recurring posts and their generated occurrences
* [Media Handling](/docs/posting/create-posts/media-handling.md) — Upload media before attaching it to a post
* [Content Types](/docs/posting/create-posts/content-types.md) — Supported post types and network-specific fields


---

# 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, and the optional `goal` query parameter:

```
GET https://publer.com/docs/posting/create-posts/post-labels.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.