Tags & Folders

Tags and folders help you organize what you monitor:

• Tags are labels shared by your whole workspace. You can attach them to both sites and uptime monitors, and filter either list by tag.
• Folders group sites. A site is in at most one folder, and folders are a flat list (they don't nest). Each folder has a name, an optional description, and an accent color.

Tag and folder names are unique within a workspace.

Using Tags and Folders

Attach tags and a folder when you create or update a site, and tags when you create or update an uptime monitor:

mutation {
  createSite(
    domain: "acme.io"
    tags: ["prod", "marketing"]
    folderId: "..."
  ) {
    domain
    tags
    folderId
  }
}

A tag name that doesn't exist yet is created for you. updateSite and updateUptimeLink replace the full set of tags, so send every tag you want to keep. See Site and Uptime for the full arguments.

Filter by tag or folder with the query argument:

query {
  findSite(query: "tags = prod AND folderId = \"...\"") {
    items {
      domain
    }
  }
}

query {
  findUptimeLink(query: "tags IN (prod, staging)") {
    items {
      name
    }
  }
}

A tag filter matches a record when any of its tags matches. See Filtering.

Queries

findWorkspaceTag

Paginated, filterable list of your workspace's tags.

query {
  findWorkspaceTag(query: "name ~ \"prod\"", limit: 25) {
    pagination {
      count
    }
    items {
      id
      name
    }
  }
}

Parameters

Response: a WorkspaceTagList — pagination + items: [WorkspaceTag!]!:

findWorkspaceFolder

Paginated, filterable list of your workspace's folders.

query {
  findWorkspaceFolder(limit: 25) {
    items {
      id
      name
      color
    }
  }
}

Parameters

Response: a WorkspaceFolderList — pagination + items: [WorkspaceFolder!]!:

Mutations

Any key can read tags and folders. Creating, updating, and deleting them requires a read-write key that isn't limited to specific sites or uptime monitors.

createWorkspaceTag / updateWorkspaceTag / deleteWorkspaceTag

mutation {
  createWorkspaceTag(input: { name: "prod" }) {
    id
    name
  }
}

mutation {
  updateWorkspaceTag(id: "...", input: { name: "production" }) {
    id
    name
  }
}

mutation {
  deleteWorkspaceTag(id: "...") {
    affectedRecords
  }
}

Parameters

Renaming a tag renames it on every site and monitor that carries it. Deleting a tag removes it from every site and monitor that carries it.

Response: the WorkspaceTag (create and update), or a DeleteResult — { affectedRecords: Int! } (delete).

createWorkspaceFolder / updateWorkspaceFolder / deleteWorkspaceFolder

mutation {
  createWorkspaceFolder(
    input: { name: "Clients", color: BLUE, description: "Client sites" }
  ) {
    id
    name
  }
}

Parameters

updateWorkspaceFolder changes only the fields you pass. Deleting a folder keeps its sites and leaves them without a folder.

Response: the WorkspaceFolder (create and update), or a DeleteResult — { affectedRecords: Int! } (delete).

Accent Colors

AccentColor values: SLATE, GRAY, ZINC, NEUTRAL, STONE, RED, ORANGE, AMBER, YELLOW, LIME, GREEN, EMERALD, TEAL, CYAN, SKY, BLUE, INDIGO, VIOLET, PURPLE, FUCHSIA, PINK, ROSE.