Ctrlk
Go to website
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

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:

{ "labels": [{ "name": "Q4 Launch", "color": "#E8613C" }] }

The same array works on POST /api/v1/posts/schedule and when updating media.

Endpoint

List Labels

Retrieve every label in the workspace, ordered by name.

GET /api/v1/labels

List Labels

get

Retrieves every label in the workspace, ordered by name.

Authorizations
AuthorizationstringRequired

API key authentication. Format: "Bearer-API YOUR_API_KEY"

Header parameters
Publer-Workspace-IdstringRequired

ID of the workspace containing the labels

Responses
200

Successful operation

application/json
get/labels
GET /api/v1/labels HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Publer-Workspace-Id: text
Accept: */*

{
  "data": [
    {
      "id": "text",
      "name": "text",
      "color": "text"
    }
  ]
}

Returns every label regardless of whether anything is currently attached to it:

List Labels by Type

Retrieve only the labels currently attached to resources of a given type.

Path Parameters

Parameter
Type
Required
Description

type

string

Yes

One of post, medium (media library items) or timeslot

List Labels by Type

get

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.

Authorizations
AuthorizationstringRequired

API key authentication. Format: "Bearer-API YOUR_API_KEY"

Path parameters
idstring · enumRequired

Label type to list: post, medium (media library items) or timeslot

Possible values:
Header parameters
Publer-Workspace-IdstringRequired

ID of the workspace containing the labels

Responses
200

Successful operation

application/json
typestringOptional

The requested type, echoed back

get/labels/{id}
GET /api/v1/labels/{id} HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Publer-Workspace-Id: text
Accept: */*

{
  "data": [
    {
      "id": "text",
      "name": "text",
      "color": "text"
    }
  ],
  "type": "text"
}

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.

Update Label

put

Renames a label or changes its colour. Renaming also updates any timeslot or recycling rule that referenced the old name.

Authorizations
AuthorizationstringRequired

API key authentication. Format: "Bearer-API YOUR_API_KEY"

Path parameters
idstringRequired

ID of the label to update

Header parameters
Publer-Workspace-IdstringRequired

ID of the workspace containing the labels

Body
namestringOptional

New label name

colorstringOptional

New label colour

Responses
200

Label updated

application/json
idstringOptional

Unique identifier for the label

namestringOptional

Label name

colorstringOptional

Label colour

put/labels/{id}
PUT /api/v1/labels/{id} HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Publer-Workspace-Id: text
Content-Type: application/json
Accept: */*
Content-Length: 30

{
  "name": "text",
  "color": "text"
}
{
  "id": "text",
  "name": "text",
  "color": "text"
}

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.

For the full list of supported label colors and their hex values, see Label Colors.

Delete Label

Delete a label and detach it from everything it was attached to.

Query Parameters

Parameter
Type
Required
Description

type

string

Yes

One of post, medium or timeslot. The request is rejected without it.

Delete Label

delete

Deletes a label and detaches it from every resource it was attached to.

Authorizations
AuthorizationstringRequired

API key authentication. Format: "Bearer-API YOUR_API_KEY"

Path parameters
idstringRequired

ID of the label to delete

Query parameters
typestring · enumRequired

Label type. Required - the request is rejected without it.

Possible values:
Header parameters
Publer-Workspace-IdstringRequired

ID of the workspace containing the labels

Responses
200

Label deleted

application/json
idstringOptional
typestringOptional
delete/labels/{id}
DELETE /api/v1/labels/{id}?type=post HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Publer-Workspace-Id: text
Accept: */*

{
  "id": "text",
  "type": "text"
}

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 — Attaching labels when creating posts

  • List Posts — Filter posts by label

  • Media — Filter the library by label

PreviousPosts
NextMedia

Last updated

Was this helpful?