# Tag your services

> Add labels to your services so you can filter and find them, in the dashboard or through the API.

Source: https://docs.coritan.com/get-started/tags/

A *tag* is a label of your own, such as `production` or `eu-customers`, that you put on a service, an instance or a server to find it again. Tags do nothing else: they change no setting and cost nothing.

## Before you begin

- A tag uses lowercase letters, digits and hyphens, and starts with a letter or a digit. The dashboard turns spaces into hyphens and capitals into lowercase for you.
- Tags on a service and tags on the instance or server behind it are kept apart. [Where tags live](#where-tags-live) explains which list each one filters.

## Add a tag

1. Open the thing you want to tag:
   - A service: its page from **Services**, or the page of a floating IP, a mail service or an Object Storage service. The **Tags** card is on the **Overview** tab.
   - A Cloud Compute instance or a Container Apps server: its **Settings** tab, in the **Tags** card.
2. Type the tag in **Add a tag**. Under the field, **Suggestions** offers the tags you already use.
3. Press <kbd>Enter</kbd>, type a comma, or select **Add tag**.

The tag is saved at once and appears as a chip above the field.

## Remove a tag

1. Open the **Tags** card that holds the tag.
2. Select the cross on the tag's chip. With the field empty, <kbd>Backspace</kbd> removes the last tag.

## Filter a list by tag

1. Open **Services**, **Cloud Compute** or **Container Apps**.
2. Select a tag in the row of tags under the search box. The number beside each tag counts the items that have it.
3. Select more tags to narrow the list to items that have all of them.
4. Select **Clear** to show everything again.

## Where tags live

A Cloud Compute instance and a Container Apps server each have a service as well: the service carries the plan and the billing. Each keeps its own tags.

| Where you add the tag | Where it shows and filters |
| --- | --- |
| A service's **Overview** tab | **Services** |
| An instance's **Settings** tab | **Cloud Compute** |
| A server's **Settings** tab | **Container Apps** |

To find an instance or a server from **Services**, tag its service as well.

## Result

The tag shows on the item and in its list, where it filters. Through the API, `GET /services/?tag=` returns only the services with that tag.

## Troubleshooting

**Could not save the tags** with `Tag must be 1–128 chars: lowercase letters, digits, hyphen, underscore`
: The tag has a character that tags cannot hold, such as a dot, a colon or a slash. Use lowercase letters, digits and hyphens.

A tag you added on an instance or server is missing from **Services**
: Instance and server tags filter **Cloud Compute** and **Container Apps**. Add the tag on the service's **Overview** tab too, as [Where tags live](#where-tags-live) shows.

## Related

- [Manage your services](/get-started/services/)
- [Pagination and filtering](/api/pagination/)

## With the API

Each tag belongs to a *source*: a type and an ID.

| `source_type` | `source_id` |
| --- | --- |
| `service` | The service ID, such as `1042`. |
| `vps` (or `cloud_compute`) | The instance's UUID. |
| `container_server` (or `server`) | The server's UUID. |
| `dns_zone` | The DNS zone's ID. |
| `proxy_route` | The web proxy's ID. |

Read a source's tags with [`GET /client/tags/sources/{source_type}/{source_id}`](/api/reference/client/resource-tags/#op-get-api-v1-client-tags-sources-source-type-source-id):

```bash
curl https://api.coritan.com/api/v1/client/tags/sources/service/1042 \
  -H "Authorization: Bearer $CORITAN_TOKEN"
```

```json
{"source_type": "service", "source_id": "1042", "tags": ["production", "web"]}
```

Add one tag with [`POST`](/api/reference/client/resource-tags/#op-post-api-v1-client-tags-sources-source-type-source-id) and `{"tag": "production"}`. Replace every tag at once with [`PUT`](/api/reference/client/resource-tags/#op-put-api-v1-client-tags-sources-source-type-source-id) and a list of up to 50; an empty list removes them all:

```bash
curl -X PUT https://api.coritan.com/api/v1/client/tags/sources/vps/0b6f3e2a-7c41-4d8e-9f25-6a1d3c8e4b70 \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["production", "eu-customers"]}'
```

Remove one with [`DELETE /client/tags/sources/{source_type}/{source_id}/{tag}`](/api/reference/client/resource-tags/#op-delete-api-v1-client-tags-sources-source-type-source-id-tag). All three answer with the source's tags after the change, sorted: `{"tags": ["eu-customers", "production"]}`.

The API lowercases a tag and turns spaces into hyphens. It accepts lowercase letters, digits, hyphens and underscores, 1–128 characters, starting with a letter or a digit. Adding a tag the source already has changes nothing.

[`GET /client/tags/vocabulary`](/api/reference/client/resource-tags/#op-get-api-v1-client-tags-vocabulary) lists the tags you use on one `source_type`, with how many of your resources carry each:

```bash
curl "https://api.coritan.com/api/v1/client/tags/vocabulary?source_type=service" \
  -H "Authorization: Bearer $CORITAN_TOKEN"
```

```json
{"items": [{"tag": "production", "resource_count": 3}, {"tag": "web", "resource_count": 1}], "source_type": "service"}
```

The errors:

- `400` `Unsupported source_type: ...` or `Tagging not enabled for source_type: ...`: use a type from the table.
- `404` `Service not found`, `Cloud Compute instance not found`, `Server not found`, `DNS zone not found` or `Proxy route not found`: the ID is wrong or the item is not yours.
- `400` `Tag must be 1–128 chars: lowercase letters, digits, hyphen, underscore`: the tag breaks the format.
- `422`: a `PUT` sent more than 50 tags.

## API

- `GET /api/v1/client/tags/sources/{source_type}/{source_id}`: Get resource tags (https://docs.coritan.com/api/reference/client/resource-tags/#op-get-api-v1-client-tags-sources-source-type-source-id)
- `POST /api/v1/client/tags/sources/{source_type}/{source_id}`: Add resource tag (https://docs.coritan.com/api/reference/client/resource-tags/#op-post-api-v1-client-tags-sources-source-type-source-id)
- `PUT /api/v1/client/tags/sources/{source_type}/{source_id}`: Replace resource tags (https://docs.coritan.com/api/reference/client/resource-tags/#op-put-api-v1-client-tags-sources-source-type-source-id)
- `DELETE /api/v1/client/tags/sources/{source_type}/{source_id}/{tag}`: Remove resource tag (https://docs.coritan.com/api/reference/client/resource-tags/#op-delete-api-v1-client-tags-sources-source-type-source-id-tag)
- `GET /api/v1/client/tags/vocabulary`: Distinct tags on resources you own for a given sourcetype (https://docs.coritan.com/api/reference/client/resource-tags/#op-get-api-v1-client-tags-vocabulary)