Tags and hashtags are objects with their own GraphQL IDs. To change the tags of a story, first find the IDs of the tags you want. Then send them to the storyTag mutation, with the ID of the story (see Get a story). About tags describes tags, categories and hashtags as users see them.

Find the tags

Search by name among the global tags (those not limited to a space) and the hashtags:

query searchTags {
  me {
    searchGlobalTags(text: "a tag") {
      tag {
        id
        name
      }
    }
    searchHashtags(text: "hashtag") {
      hashtag {
        id
        name
      }
    }
  }
}

The response:

{
  "data": {
    "me": {
      "searchGlobalTags": [
        { "tag": { "id": "VGFnOjEwOQ==", "name": "a nice tag" } },
        { "tag": { "id": "VGFnOjQwMw==", "name": "another test tag" } }
      ],
      "searchHashtags": [
        { "hashtag": { "id": "SGFzaHRhZzozMDU=", "name": "my cool hashtag" } }
      ]
    }
  }
}

A tag always belongs to a category (a Facet in the API). To list the tags of one category, read it by ID:

query tagsOfACategory {
  node(id: "FACET_ID") {
    ... on Facet {
      name
      tags(first: 50) {
        edges {
          node {
            id
            name
          }
        }
      }
    }
  }
}

Tags limited to one or more spaces are found with searchTags(text:, spaces:) on me, with the IDs of those spaces.

Keep the id of each tag you want to use.

Create a tag

If the tag does not exist, create it in its category:

mutation createATag {
  tagCreate(input: { facetId: "FACET_ID", names: { en: "Name of the tag" } }) {
    tag {
      id
    }
  }
}

names takes one name per language. name sets a single name.

Change the tags of the story

Send the IDs of the tags to add and of the tags to remove. The mutation:

mutation storyTagExample($input: StoryTagInput!) {
  storyTag(input: $input) {
    story {
      tags {
        id
        name
      }
      hashtags {
        id
        name
      }
    }
    ignoredTags {
      id
      name
    }
    ignoredHashtags {
      id
      name
    }
  }
}

The variables:

{
  "input": {
    "id": "STORY_ID",
    "addedTags": ["TAG_ID_1", "TAG_ID_2"],
    "removedTags": ["TAG_ID_3"],
    "addedHashtags": ["HASHTAG_ID_1"],
    "removedHashtags": []
  }
}

The response lists the tags and hashtags of the story after the change:

{
  "data": {
    "storyTag": {
      "story": {
        "tags": [
          { "id": "TAG_ID_1", "name": "Tag 1" },
          { "id": "TAG_ID_2", "name": "Tag 2" }
        ],
        "hashtags": [{ "id": "HASHTAG_ID_1", "name": "Hashtag 1" }]
      },
      "ignoredTags": null,
      "ignoredHashtags": null
    }
  }
}

ignoredTags and ignoredHashtags list the tags and hashtags the platform did not apply, for example because the story's template sets them.