Introduction

Manage your tags with the Tagging API in IBM Cloud. You can create, delete, search, attach, or detach tags with the Tagging API. Tags are uniquely identified by a Cloud Resource Naming (CRN) identifier. Tags have a name, which must be unique within a billing account. You can make tags in key:value or label format.

API endpoint

https://tags.global-search-tagging.cloud.ibm.com

API endpoint

https://tags.global-search-tagging.cloud.ibm.com

API endpoint

https://tags.global-search-tagging.cloud.ibm.com

API endpoint

https://tags.global-search-tagging.cloud.ibm.com

Authentication

REST APIs require the user to specify an OAuth2 security token in the header to be authorized by the IBM Cloud IAM service. You can obtain a bearer token by using the IBM Cloud command line command ibmcloud iam oauth-tokens. Another way to obtain a bearer token is through an API key. For more information, see Getting an IBM Cloud IAM token by using an API key.

Error handling

The resource manager uses standard HTTP response codes to indicate whether a method completed successfully. A 200 type response always indicates success. A 400 type response is a failure, and a 500 type response is an internal system error.

HTTP Error Code Description Recovery
200 Success The request was successful.
400 Bad Request The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request.
401 Unauthorized You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions.
403 Forbidden The supplied authentication is not authorized to access '{namespace}'.
404 Not Found The requested resource could not be found.
409 Conflict The entity is already in the requested state.
410 Gone The resource is valid but has been removed already in a previous call
500 Internal Server Error offering_name is currently unavailable. Your request could not be processed. Wait a few minutes and try again.

After tagging resources, you can search by tag name, resource groups, or by building even more complex search strings. For more information about advanced search capabilities that use the Lucene query syntax, see the IBM Cloud Search API.

Methods

Get all tags

Lists all tags in a billing account. Use the attached_to parameter to return the list of tags attached to the specified resource.

GET /v3/tags
Request

Query Parameters

  • Select a provider. Supported values are ghost and ims. To list GhoST tags and infrastructure tags use ghost,ims

    Allowable values: [ghost,ims]

    Default: ["ghost"]

  • If you want to return only the list of tags attached to a specified resource, pass here the ID of the resource. For GhoST onboarded resources, the resource ID is the CRN; for IMS resources, it is the IMS ID. When using this parameter it is mandatory to specify the appropriate provider (ims or ghost).

    Constraints: Value must match regular expression ^crn:v1(:[a-zA-Z0-9 \-\._~\*\+,;=!$&'\(\)\/\?#\[\]@]*){8}$|^[0-9]+$

  • If set to true, this query returns the provider, ghost, ims or ghost,ims, where the tag exists and the number of attached resources.

    Default: false

  • The offset is the index of the item from which you want to start returning data from.

    Constraints: value ≥ 0

    Default: 0

  • The number of tags to return.

    Constraints: 1 ≤ value ≤ 1000

    Default: 100

  • Order the output by tag name.

    Allowable values: [asc,desc]

    Default: asc

  • The search timeout bounds the search request to be executed within the specified time value. It returns the hits accumulated until time runs out.

    Default: 0

Response

A list of tags.

Status Code

  • A result paging with the list of tags matching the provided filters.

  • Bad request

  • Unauthorized, wrong authorization token type, or IAM authorization token not valid

  • Unauthorized operation

  • Unsupported operation

  • Internal server error, IAM not initialized, or malformed IAM credentials

  • System problem or unexpected error

No Sample Response

This method does not specify any sample responses.

Delete a tag

Delete an existing tag. A tag can be deleted only if it is not attached to any resource.

DELETE /v3/tags/{tag_name}
Request

Path Parameters

  • The name of tag to be deleted.

Query Parameters

  • Select a provider. Supported values are ghost and ims. To delete tag both in GhoST in IMS, use ghost,ims

    Allowable values: [ghost,ims]

    Default: ["ghost"]

Response

Results of a delete_tag request.

Status Code

  • Success message

  • Validation error

  • Missing or bad IAM authentication

  • System problem or unexpected error

Example responses

Attach one ore more tags

Attaches one or more tags to one or more resources. To attach a tag to a resource managed by the Resource Controller, you must be an editor on the resource. To attach a tag to a Cloud Foundry resource, you must have space developer role. To attach a tag to IMS resources, depending on the resource, you need either view hardware details, view virtual server details or manage storage permission.

POST /v3/tags/attach
Request

Array of tag names and list of resource IDs on which the tags should be attached. For GhoST onboarded resources, the resource ID is the CRN; for IMS resources, it is the IMS ID. The maximum number of resource IDs where the tag will be attached is 100. You can specify up to 100 tags to be attached.

Example:
Response

Results of an attach_tag or detach_tag request

Status Code

  • Success

  • Validation error

  • Missing or bad IAM authentication

  • System problem or unexpected error

Example responses

Detach one or more tags

Detach one or more tags from one or more resources. To detach a tag from a Resource Controller managed resource, you must be an editor on the resource. To detach a tag to a Cloud Foundry resource, you must have space developer role. To detach a tag to IMS resources, depending on the resource, you need either view hardware details, view virtual server details or storage manage permission.

POST /v3/tags/detach
Request

Array of tag names and list of resource IDs from which the tag should be detached. For GhoST onboarded resources, the resource ID is the CRN; for IMS resources, it is the IMS ID. For IMS resource also the IMS datatype must be specified. The maximum number of resources where the tag will be detached from is 100. You can specify up to 100 tags to be detached.

Example:
Response

Results of an attach_tag or detach_tag request

Status Code

  • Success message

  • Validation error

  • Missing or bad IAM authentication

  • System problem or unexpected error

Example responses