Projects and tags
Projects and tags help you find your instances once you have more than a few. They only exist in the portal: nothing changes on the instances themselves, and they cost nothing.
Projects
A project is a folder for instances, for example one per client, product or environment (Production, Staging). Every instance is in exactly one project.
- Every organization has a Default project. New instances, and instances your provider assigns to you, go there unless you choose another project.
- Open Projects in the sidebar to see each project with its number of instances. Select a project to see only its instances.
- Owners, Admins and Developers can create, rename and delete projects, and choose which one is the default with Make default.
- Deleting a project moves its instances to the default project; no instance is deleted. The default project cannot be deleted; make another project the default first.
Tags
Tags are short labels such as web, db or env:prod. An instance can have up to 20 tags, and the same tag can be on many instances, across projects.
- Tags use lowercase letters, numbers, colons, dashes and underscores, up to 64 characters. Capitals are turned into lowercase.
- Select a tag anywhere in the portal to list every instance that has it, or use the tag filter on Instances.
- A tag disappears automatically when no instance uses it any more.
Moving and tagging an instance
- When creating an instance, choose its project and tags in step 5, Organize.
- Afterwards, open the instance and use Project and tags on the right. Enter tags separated by commas, then select Save. The tags you save replace the previous ones.
Changes are recorded in the audit log.
Using the API
- List projects:
GET /api/v1/organizations/{id}/projects - Create:
POST /api/v1/organizations/{id}/projectswithname, optionaldescriptionandis_default - Rename or make default:
PUT /api/v1/organizations/{id}/projects/{project} - Delete:
DELETE /api/v1/organizations/{id}/projects/{project}(instances move to the default project) - Move or tag an instance:
PATCH /api/v1/organizations/{id}/instances/{instance}withproject_idand/ortags(a list; it replaces the instance's tags) - Filter instances:
GET /api/v1/organizations/{id}/instances?project_id=…&tag=… - Creating an instance also accepts
project_idandtags. Every instance in API responses includes itsprojectandtags.