> 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/api-reference/labels.md). # Labels ## Labels Labels are shared, colour-coded tags that group posts, media library items, and time slots inside a workspace. Use this API to list what exists, rename or recolour a label, and remove one. #### Requirements * **Authentication**: Bearer API token * **Scope**: `labels` * **Headers**: * `Authorization: Bearer-API YOUR_API_KEY` * `Publer-Workspace-Id: YOUR_WORKSPACE_ID` {% hint style="info" %} **There is no create endpoint.** Labels come into existence when you attach one to something. Pass `labels` on a post at creation time, and any name that does not already exist in the workspace is created for you: ```json { "labels": [{ "name": "Q4 Launch", "color": "#E8613C" }] } ``` The same array works on `POST /api/v1/posts/schedule` and when updating media. {% endhint %} #### Endpoint ### List Labels Retrieve every label in the workspace, ordered by name. ```http GET /api/v1/labels ``` ## List Labels > Retrieves every label in the workspace, ordered by name. ```json {"openapi":"3.1.1","info":{"title":"Publer API","version":"1.0.0"},"tags":[{"name":"Labels","description":"Endpoints for managing post, media and timeslot labels"}],"servers":[{"url":"https://app.publer.com/api/v1"}],"security":[{"BearerApiAuth":[]}],"components":{"securitySchemes":{"BearerApiAuth":{"type":"apiKey","name":"Authorization","in":"header","description":"API key authentication. Format: \"Bearer-API YOUR_API_KEY\""}},"schemas":{"LabelList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Label"}}}},"Label":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the label"},"name":{"type":"string","description":"Label name"},"color":{"type":"string","description":"Label colour"}}},"401ErrorResponseWithWorkspace":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}},"403ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}}}},"paths":{"/labels":{"get":{"summary":"List Labels","tags":["Labels"],"description":"Retrieves every label in the workspace, ordered by name.","parameters":[{"schema":{"type":"string"},"name":"Publer-Workspace-Id","in":"header","required":true,"description":"ID of the workspace containing the labels"}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LabelList"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/401ErrorResponseWithWorkspace"}}}},"403":{"description":"Permission denied or missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/403ErrorResponse"}}}}}}}}} ``` Returns every label regardless of whether anything is currently attached to it: ```json { "data": [ { "id": "665f1a2b3c4d5e6f7a8b9c0d", "name": "Q4 Launch", "color": "#E8613C" }, { "id": "665f1a2b3c4d5e6f7a8b9c0e", "name": "Evergreen", "color": "#2C6A4C" } ] } ``` *** ### List Labels by Type Retrieve only the labels currently attached to resources of a given type. ```http GET /api/v1/labels/{type} ``` **Path Parameters**
ParameterTypeRequiredDescription
typestringYesOne of post, medium (media library items) or timeslot
## List Labels by Type > Retrieves only the labels currently attached to resources of a given type. NOTE: for this operation the path segment is a label TYPE, not a label ID. ```json {"openapi":"3.1.1","info":{"title":"Publer API","version":"1.0.0"},"tags":[{"name":"Labels","description":"Endpoints for managing post, media and timeslot labels"}],"servers":[{"url":"https://app.publer.com/api/v1"}],"security":[{"BearerApiAuth":[]}],"components":{"securitySchemes":{"BearerApiAuth":{"type":"apiKey","name":"Authorization","in":"header","description":"API key authentication. Format: \"Bearer-API YOUR_API_KEY\""}},"schemas":{"Label":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the label"},"name":{"type":"string","description":"Label name"},"color":{"type":"string","description":"Label colour"}}},"401ErrorResponseWithWorkspace":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}},"403ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}}}},"paths":{"/labels/{id}":{"get":{"summary":"List Labels by Type","tags":["Labels"],"description":"Retrieves only the labels currently attached to resources of a given type. NOTE: for this operation the path segment is a label TYPE, not a label ID.","parameters":[{"schema":{"type":"string"},"name":"Publer-Workspace-Id","in":"header","required":true,"description":"ID of the workspace containing the labels"},{"schema":{"type":"string","enum":["post","medium","timeslot"]},"name":"id","in":"path","required":true,"description":"Label type to list: post, medium (media library items) or timeslot"}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Label"}},"type":{"type":"string","description":"The requested type, echoed back"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/401ErrorResponseWithWorkspace"}}}},"403":{"description":"Forbidden - unknown label type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/403ErrorResponse"}}}}}}}}} ``` ```json { "data": [{ "id": "665f1a2b3c4d5e6f7a8b9c0d", "name": "Q4 Launch", "color": "#E8613C" }], "type": "post" } ``` When `type` is `post`, this endpoint also accepts the same filters as List Posts — `state`, `account_ids[]`, `from`, `to`, `query`, `postType`, `member_id` and others — and returns only the labels attached to posts matching that filter. This is how you answer "which labels are in use on failed posts this month". An unrecognised type returns **403 Forbidden**, not 404. *** ### Update Label Rename a label or change its colour. ```http PUT /api/v1/labels/{id} ``` ## Update Label > Renames a label or changes its colour. Renaming also updates any timeslot or recycling rule that referenced the old name. ```json {"openapi":"3.1.1","info":{"title":"Publer API","version":"1.0.0"},"tags":[{"name":"Labels","description":"Endpoints for managing post, media and timeslot labels"}],"servers":[{"url":"https://app.publer.com/api/v1"}],"security":[{"BearerApiAuth":[]}],"components":{"securitySchemes":{"BearerApiAuth":{"type":"apiKey","name":"Authorization","in":"header","description":"API key authentication. Format: \"Bearer-API YOUR_API_KEY\""}},"schemas":{"Label":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the label"},"name":{"type":"string","description":"Label name"},"color":{"type":"string","description":"Label colour"}}},"401ErrorResponseWithWorkspace":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}},"403ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}},"422ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}}}},"paths":{"/labels/{id}":{"put":{"summary":"Update Label","tags":["Labels"],"description":"Renames a label or changes its colour. Renaming also updates any timeslot or recycling rule that referenced the old name.","parameters":[{"schema":{"type":"string"},"name":"Publer-Workspace-Id","in":"header","required":true,"description":"ID of the workspace containing the labels"},{"schema":{"type":"string"},"name":"id","in":"path","required":true,"description":"ID of the label to update"}],"responses":{"200":{"description":"Label updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Label"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/401ErrorResponseWithWorkspace"}}}},"403":{"description":"Forbidden - requires workspace admin or owner","content":{"application/json":{"schema":{"$ref":"#/components/schemas/403ErrorResponse"}}}},"422":{"description":"Unprocessable Entity - invalid attributes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/422ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"New label name"},"color":{"type":"string","description":"New label colour"}}}}},"required":true,"description":"Label attributes"}}}}} ``` ```json { "name": "Q4 Launch 2026", "color": "#2C6A4C" } ``` {% hint style="info" %} Renaming is not cosmetic. Auto-scheduling timeslots and recycling rules match on the label **name**, so a rename rewrites those references in place to keep existing schedules working. {% endhint %} {% hint style="info" %} For the full list of supported label colors and their hex values, see [Label Colors](https://app.gitbook.com/o/N5p5zfz9EYbsFeJqhOWj/sites/site_TcFEg/s/cXusjO4XO5e71kL7hLQj/~/edit/~/changes/290/posting/create-posts/post-labels#label-colors). {% endhint %} *** ### Delete Label Delete a label and detach it from everything it was attached to. ```http DELETE /api/v1/labels/{id}?type=post ``` **Query Parameters**
ParameterTypeRequiredDescription
typestringYesOne of post, medium or timeslot. The request is rejected without it.
## Delete Label > Deletes a label and detaches it from every resource it was attached to. ```json {"openapi":"3.1.1","info":{"title":"Publer API","version":"1.0.0"},"tags":[{"name":"Labels","description":"Endpoints for managing post, media and timeslot labels"}],"servers":[{"url":"https://app.publer.com/api/v1"}],"security":[{"BearerApiAuth":[]}],"components":{"securitySchemes":{"BearerApiAuth":{"type":"apiKey","name":"Authorization","in":"header","description":"API key authentication. Format: \"Bearer-API YOUR_API_KEY\""}},"schemas":{"401ErrorResponseWithWorkspace":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}},"403ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}}}},"paths":{"/labels/{id}":{"delete":{"summary":"Delete Label","tags":["Labels"],"description":"Deletes a label and detaches it from every resource it was attached to.","parameters":[{"schema":{"type":"string"},"name":"Publer-Workspace-Id","in":"header","required":true,"description":"ID of the workspace containing the labels"},{"schema":{"type":"string"},"name":"id","in":"path","required":true,"description":"ID of the label to delete"},{"schema":{"type":"string","enum":["post","medium","timeslot"]},"name":"type","in":"query","required":true,"description":"Label type. Required - the request is rejected without it."}],"responses":{"200":{"description":"Label deleted","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/401ErrorResponseWithWorkspace"}}}},"403":{"description":"Forbidden - requires workspace admin or owner, or unknown label type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/403ErrorResponse"}}}}}}}}} ``` ```json { "id": "665f1a2b3c4d5e6f7a8b9c0d", "type": "post" } ``` Deleting removes the label everywhere at once — it is not scoped to the `type` you pass. The `type` parameter is required for the request to be accepted and is echoed back in the response. #### Notes * **Permissions.** `List Labels` and `List Labels by Type` are available to any member of the workspace. **Update and Delete require workspace admin or owner** — other roles receive `403 Forbidden`. * **The path segment means different things per method.** On `GET` it is a label *type*; on `PUT` and `DELETE` it is a label *ID*. They share one path template because a type listing and a label lookup occupy the same position in the URL. * Label names are unique per workspace. Attaching an existing name reuses that label rather than creating a duplicate. * Colours are free-form strings; the apps use hex values such as `#E8613C`. #### Related Resources * [Post Labels](/docs/posting/create-posts.md) — Attaching labels when creating posts * [List Posts](/docs/api-reference/posts.md) — Filter posts by label * [Media](/docs/api-reference/media.md) — Filter the library by label --- # 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://publer.com/docs/api-reference/labels.md?ask=&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.