Skip to main content

Resource tags

Tags are case-sensitive string key/value pairs, such as environment=staging, component=api or pr_preview=125. They group managed resources inside a project without changing their configuration, permissions or placement.

Add or change tags in the Tags section of a resource's creation or edit form, then use the usual Create, Update or Save changes button. Containers, jobs, cronjobs, databases, gateways, websites and shared volumes use the same key/value fields. For one-time jobs, runtime settings remain read-only and tags can still be updated. Managing tags requires the same permissions as managing resources. Custom services and connection poolers, which have no standalone console form, can be tagged through the API.

In resource lists, open Tags beside the existing search, status and type filters. Choose a Tag key, then choose or enter the exact Value equals criterion. Value suggestions only belong to the selected key; typing narrows suggestions without applying a filter. Select a suggestion or Use your typed value to apply it. Criteria appear as Tag: environment = "staging". Selecting another value for the same key replaces its previous criterion. Remove a criterion with its cross, or use Clear to reset all filters together. The filter bar stays visible when no resources match.

A compact Tags column shows each resource's tag count without adding another line. Open it to read the key/value pairs or select one as an exact filter. Detail pages show a compact tag summary below the resource header; expand it to read every key and value. Tag editing remains in the existing resource form.

All selected tag filters must match. Keys and values are exact and case-sensitive: environment=Staging and environment=staging are different. A resource can have up to 50 tags; keys contain 1–128 letters, digits, underscores, dots, slashes or hyphens, and values contain up to 256 characters. Empty values are allowed.

Tags belong to a resource's identity. Deleting and recreating a resource with the same name starts a new identity without its old tags. Changes to tags do not restart workloads. Routes, connections, snapshots and block volumes remain managed through their existing parent workflows; they do not have independent tag records.

Tag resources when deploying​

Include a tags object in a supported resource creation request:

{
"name": "preview-api-125",
"tags": { "environment": "preview", "pr_preview": "125", "component": "api" },
"spec": {
"image": "ghcr.io/example/api:pr-125",
"computeClass": "standard",
"resources": { "cpu": 500, "memory": 512 }
}
}

The stack apply/plan request also accepts default tags. Individual resource tags override the entire default map; an explicit {} clears tags. Omitted tags preserve existing metadata when no stack defaults are supplied. Stack exports include tags.

Search through the API​

The Public API provides a project-wide resource listing:

curl --get \
-H "X-Api-Key: $SAILOPS_API_KEY" \
--data-urlencode 'tag=environment=preview' \
--data-urlencode 'tag=pr_preview=125' \
'https://app.sailops.io/api/public/api/v1/resources'

The response has items and, when another page exists, nextCursor. Each item carries id, kind, name, tags, revision, canDelete, and an optional parentId. Repeat the same filters with cursor=nextCursor to fetch the next page. limit accepts 1–200, defaulting to 100. An optional kind=CONTAINER narrows the resource type. Filters are applied before pagination. Deleted resources are excluded.

Replace all tags using the resource ID and revision from that listing:

PUT /api/public/api/v1/resources/{resourceId}/tags
X-Api-Key: <project-api-key>
Content-Type: application/json

{"revision": 0, "tags": {"pr_preview": "125", "component": "api"}}

An empty map removes all tags. A concurrent edit returns a conflict: fetch the resource's current tags and revision before retrying.

Clean up a preview environment​

Use the tag filters in each resource list to find the preview's components and delete them with their usual resource actions. Cross-resource cleanup is available through the API:

For automation, list all matching pages, retain those exact resource IDs, then call DELETE /api/public/api/v1/resources/{resourceId} for each deletable resource. Stop scheduled workloads and delete consumers before databases and shared volumes. Keep failed IDs for retry rather than assuming the entire environment was removed. The API refuses to delete a replacement generation under a previously selected name.

Deletion follows each resource's existing rules, including data removal and cleanup of owned children. Parent-managed resources, custom services and applications deployed before Marketplace retirement are not individually deletable through this endpoint (canDelete: false). Existing applications retain their tags; their tags can still be read and replaced through the API. Shared dependencies outside the selection are not selected implicitly. Tags provide grouping; they do not impose an automatic expiry time.