Tags

Endpoints for managing team tags and sharing them read-only with other teams.

GET

https://server.chief.app/api/v1

/tags

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

List the tags the authenticated team can see: its own tags (access owner) and tags other teams shared with it (access viewer), sorted by name.

query

string | null · maxLength: 255

Search results by name.

per_page

integer · min: 1 · max: 100

Number of results per page.

Default: 50

page

integer · min: 1

Page number to return.

Default: 1

Paginated set of Tag

Tag[] · required

object · required

GET/tags

curl https://server.chief.app/api/v1/tags \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "id": "tag_01j8q8zk2f4m6n7p9r1s3t5v7x",
      "name": "production",
      "color": "zinc",
      "owner_team": {
        "slug": "acme",
        "name": "Acme Inc"
      },
      "access": "owner",
      "servers_count": 4,
      "created_at": "created_at",
      "updated_at": "updated_at"
    }
  ],
  "links": {
    "first": "first",
    "last": "last",
    "prev": "prev",
    "next": "next"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": "url",
        "label": "label",
        "active": true
      }
    ],
    "path": "path",
    "per_page": 0,
    "to": 1,
    "total": 0
  }
}

json

application/json

Create a tag

POST

https://server.chief.app/api/v1

/tags

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Create a tag in the authenticated team. Attach it to servers with the server tags endpoints, and share it to give other teams read-only access to those servers.

Create a tag › Request Body

SaveTagRequest

name

string · maxLength: 64 · pattern: ^[\pL\pN][\pL\pN _.:… · required

Tag name, unique within the team. Letters, digits, spaces and . _ - : /, starting with a letter or digit.

Example: production

color

string · enum

Colour of the tag in the dashboard.

Enum values:

zinc

red

orange

amber

green

teal

sky

blue

Default: zinc

Create a tag › Responses

The tag was created.

Tag · required

Show a tag

GET

https://server.chief.app/api/v1

/tags/{tag}

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Show one of the team's tags, or a tag shared with the team.

Show a tag › path Parameters

tag

string · required

Show a tag › Responses

Tag

Tag · required

Update a tag

PATCH

https://server.chief.app/api/v1

/tags/{tag}

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Rename or recolour one of the team's tags. Tags shared with the team cannot be changed.

Update a tag › path Parameters

tag

string · required

Update a tag › Request Body

SaveTagRequest

name

string · maxLength: 64 · pattern: ^[\pL\pN][\pL\pN _.:… · required

Tag name, unique within the team. Letters, digits, spaces and . _ - : /, starting with a letter or digit.

Example: production

color

string · enum

Colour of the tag in the dashboard.

Enum values:

zinc

red

orange

amber

green

teal

sky

blue

Default: zinc

Update a tag › Responses

Tag

Tag · required

Delete a tag

DELETE

https://server.chief.app/api/v1

/tags/{tag}

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Delete one of the team's tags. It is removed from every server, and teams it was shared with lose access to the servers they only saw through it.

Delete a tag › path Parameters

tag

string · required

Delete a tag › Responses

The tag was deleted.

string

List a tag's shares

GET

https://server.chief.app/api/v1

/tags/{tag}/shares

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

List the teams one of the team's tags is shared with. Only the owner team can see the shares of a tag.

List a tag's shares › path Parameters

tag

string · required

List a tag's shares › Responses

Array of TagShare

TagShare[] · required

POST

https://server.chief.app/api/v1

/tags/{tag}/shares

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Share one of the team's tags with another team by its slug. The other team then sees every server of this team that carries the tag, read-only, until the tag is detached, unshared or deleted. Sharing again with the same team updates the role. Shared servers never count towards the other team's plan.

tag

string · required

ShareTagRequest

team

string · maxLength: 255 · required

Slug of the team to share the tag with. The team must use Server Chief.

Example: acme

role

string · enum

What the team can do with the tagged servers. viewer is read-only.

Enum values:

viewer

Default: viewer

The tag is shared with the team.

TagShare · required

Unshare a tag

DELETE

https://server.chief.app/api/v1

/tags/{tag}/shares/{team}

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Stop sharing one of the team's tags with a team. The team immediately loses access to the servers it only saw through the tag. A team a tag is shared with can leave the share by passing its own slug.

Unshare a tag › path Parameters

tag

string · required

team

string · required

Unshare a tag › Responses

The tag is no longer shared with the team.

string

Alerts Agent releases

Tags

List tags

List tags › query Parameters

List tags › Responses

Create a tag

Create a tag › Request Body

Create a tag › Responses

Show a tag

Show a tag › path Parameters

Show a tag › Responses

Update a tag

Update a tag › path Parameters

Update a tag › Request Body

Update a tag › Responses

Delete a tag

Delete a tag › path Parameters

Delete a tag › Responses

List a tag's shares

List a tag's shares › path Parameters

List a tag's shares › Responses

Share a tag

Share a tag › path Parameters

Share a tag › Request Body

Share a tag › Responses

Unshare a tag

Unshare a tag › path Parameters

Unshare a tag › Responses