Core Resources

Workspace ID and Channel ID To work with the API, you often need the Workspace ID and Channel ID. These can be fetched via the API or found in the URL of the web application.

Workspace ID and Channel ID

To work with the API, you often need the Workspace ID and Channel ID. These can be fetched via the API or found in the URL of the web application. (See Overview)

Tips

Consider caching the Workspace ID and Channel ID in your application to avoid repeatedly querying the API. They are not changing, and the cached values are great for performance and reliability.

Get a list of all workspaces

Use the clients query:

query listWorkspaces {
  clients {
    id
    name
  }
}

Get a list of all channels

Query a specific workspace ("client") to get its channels:

query listChannels {
  client(id: <WORKSPACE_ID>) {
    channels {
      id
      name
    }
  }
}

Alternatively, the top-level channels query returns the channels accessible for a given workspace. An optional product filter (inbox or publisher) narrows the list down to channels the authenticated user can access for that product.

query listChannelsDirect {
  channels(workspace_id: <WORKSPACE_ID>, product: publisher) {
    id
    name
    type
  }
}

Working with tags

To add or remove tags, the dedicated mutations postsAddTag and postsRemoveTag can be used. Tags don’t have to exist to be used the first time. A tag is a simple string

Tags are auto-converted

Tags will always be converted to lowercase and a space ' ' will be converted to a dash '-'.

On a higher level, tags can added/removed/listed on a workspace, using the following endpoints:

workspaceTagCreate
workspaceTagDelete
workspaceTagList

It’s generally possible on the Workspace level to Disable creating new tags with the setting “Only allow pre-defined tags”, which will be respected by above endpoints

Add a tag to posts

postsAddTag takes an array of post IDs and returns the affected posts as a list. context is post for Publisher posts and ticket for Inbox tickets.

mutation addTag {
  postsAddTag(
    context: post
    post_ids: [<POST_ID>]
    tag: "campaign-2024"
    workspace_id: <WORKSPACE_ID>
  ) {
    id
    tags
  }
}

Remove a tag from posts

mutation removeTag {
  postsRemoveTag(
    context: post
    post_ids: [<POST_ID>]
    tag: "campaign-2024"
    workspace_id: <WORKSPACE_ID>
  ) {
    id
    tags
  }
}

Read tags on a post

Tags are returned as part of any post query. Include the tags field in your selection set:

query postTags {
  post(id: <POST_ID>) {
    id
    tags
  }
}

List all tags in a workspace

workspaceTagList returns a paginated wrapper; the tags themselves live under workspace_tags. Optional args: after, search_term, sort_field, sort_order.

query workspaceTags {
  workspaceTagList(workspace_id: <WORKSPACE_ID>) {
    workspace_tags {
      id
      tag
    }
    pagination {
      after
    }
  }
}