Global Search and Tagging - Tagging API

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

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

API endpoint

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

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

API endpoint

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

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

API endpoint

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

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.

IBM Cloud Search.

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

/v3/tags

Request

Query Parameters

providers
string[]
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"]
attached_to
string
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]+$
full_data
boolean
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
offset
integer
The offset is the index of the item from which you want to start returning data from.

Constraints: value ≥ 0
Default: 0
limit
integer
The number of tags to return.

Constraints: 1 ≤ value ≤ 1000
Default: 100
order_by_name
string
Order the output by tag name.

Allowable values: [asc,desc]
Default: asc
timeout
integer
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
attached_only
boolean
Filter on attached tags. If true, returns only tags that are attached to one or more resources. If false returns all tags.

Default: false

Response

Response Body

TagList

A list of tags.

Status Code

200
A result paging with the list of tags matching the provided filters.
400
Bad request
401
Unauthorized, wrong authorization token type, or IAM authorization token not valid
403
Unauthorized operation
407
Unsupported operation
500
Internal server error, IAM not initialized, or malformed IAM credentials
default
System problem or unexpected error

No Sample Response

This method does not specify any sample responses.

Delete unused tags

Delete the tags that are not attatched to any resource.

DELETE /v3/tags

/v3/tags

Request

Query Parameters

providers
string
Select a provider. Supported values are ghost and ims.

Allowable values: [ghost,ims]
Default: ghost

Response

Response Body

DeleteTagsResult

The results of a deleting unattatched tags.

Status Code

200
A results page that includes the list of tags that have been deleted.
400
Bad request
401
Unauthorized, wrong authorization token type, or IAM authorization token was not valid.
500
Internal server error, IAM not initialized, or malformed IAM credentials.
default
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}

/v3/tags/{tag_name}

Request

Path Parameters

tag_name
string
The name of tag to be deleted.

Query Parameters

providers
string[]
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

Response Body

DeleteTagResults

Results of a delete_tag request.

Status Code

200
Success message
400
Validation error
401
Missing or bad IAM authentication
default
System problem or unexpected error

Example responses

Status 200

{
  "results": [
    {
      "provider": "ghost",
      "is_error": false
    },
    {
      "provider": "ims",
      "is_error": true,
      "response": "IMS_API_ERROR",
      "message": "Error calling IMS REST API endpoint",
      "code": "GST915E",
      "level": "error",
      "httpCode": 500,
      "description": "SoftLayer_Exception_Public",
      "more_info": "No tag found with the name \"string\""
    }
  ]
}{
  "results": [
    {
      "provider": "ghost",
      "is_error": false
    },
    {
      "provider": "ims",
      "is_error": true,
      "response": "IMS_API_ERROR",
      "message": "Error calling IMS REST API endpoint",
      "code": "GST915E",
      "level": "error",
      "httpCode": 500,
      "description": "SoftLayer_Exception_Public",
      "more_info": "No tag found with the name \"string\""
    }
  ]
}

Attach one or 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

/v3/tags/attach

Request

Request Body

AttachTagRequest

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:

{
  "tag_names": [
    "tag_test_1",
    "tag_test_2"
  ],
  "resources": [
    {
      "resource_id": "crn:v1:staging:public:resource-controller::a/5c2ac0d93c69e82c6c9c7c78dc4beda3::resource-group:1b061f4485b34360a8f8ee049080dc13"
    },
    {
      "resource_id": "58546459",
      "resource_type": "SoftLayer_Virtual_Guest"
    }
  ]
}{
  "tag_names": [
    "tag_test_1",
    "tag_test_2"
  ],
  "resources": [
    {
      "resource_id": "crn:v1:staging:public:resource-controller::a/5c2ac0d93c69e82c6c9c7c78dc4beda3::resource-group:1b061f4485b34360a8f8ee049080dc13"
    },
    {
      "resource_id": "58546459",
      "resource_type": "SoftLayer_Virtual_Guest"
    }
  ]
}

Response

Response Body

TagResults

Results of an attach_tag or detach_tag request

Status Code

200
Success
400
Validation error
401
Missing or bad IAM authentication
default
System problem or unexpected error

Example responses

Status 200

{
  "results": [
    {
      "resource_id": "crn",
      "is_error": false
    },
    {
      "resource_id": "75ffffwer7",
      "is_error": true,
      "response": "IMS_API_ERROR",
      "message": "Error calling IMS REST API endpoint.",
      "code": "GST915E",
      "level": "error",
      "httpCode": 401,
      "more_info": "IMS token is missing."
    }
  ]
}{
  "results": [
    {
      "resource_id": "crn",
      "is_error": false
    },
    {
      "resource_id": "75ffffwer7",
      "is_error": true,
      "response": "IMS_API_ERROR",
      "message": "Error calling IMS REST API endpoint.",
      "code": "GST915E",
      "level": "error",
      "httpCode": 401,
      "more_info": "IMS token is missing."
    }
  ]
}

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

/v3/tags/detach

Request

Request Body

DetachTagRequest

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:

{
  "tag_names": [
    "tag_test_1",
    "tag_test_2"
  ],
  "resources": [
    {
      "resource_id": "crn:v1:staging:public:resource-controller::a/5c2ac0d93c69e82c6c9c7c78dc4beda3::resource-group:1b061f4485b34360a8f8ee049080dc13"
    },
    {
      "resource_id": "75546457",
      "resource_type": "SoftLayer_Hardware"
    }
  ]
}{
  "tag_names": [
    "tag_test_1",
    "tag_test_2"
  ],
  "resources": [
    {
      "resource_id": "crn:v1:staging:public:resource-controller::a/5c2ac0d93c69e82c6c9c7c78dc4beda3::resource-group:1b061f4485b34360a8f8ee049080dc13"
    },
    {
      "resource_id": "75546457",
      "resource_type": "SoftLayer_Hardware"
    }
  ]
}

Response

Response Body

TagResults

Results of an attach_tag or detach_tag request

Status Code

200
Success message
400
Validation error
401
Missing or bad IAM authentication
default
System problem or unexpected error

Example responses

Status 200

{
  "results": [
    {
      "resource_id": "crn",
      "is_error": false
    },
    {
      "resource_id": "75ffffwer7",
      "is_error": true,
      "response": "IMS_API_ERROR",
      "message": "Error calling IMS REST API endpoint.",
      "code": "GST915E",
      "level": "error",
      "httpCode": 401,
      "more_info": "IMS token is missing."
    }
  ]
}{
  "results": [
    {
      "resource_id": "crn",
      "is_error": false
    },
    {
      "resource_id": "75ffffwer7",
      "is_error": true,
      "response": "IMS_API_ERROR",
      "message": "Error calling IMS REST API endpoint.",
      "code": "GST915E",
      "level": "error",
      "httpCode": 401,
      "more_info": "IMS token is missing."
    }
  ]
}

Introduction

Authentication

Error handling

Related APIs

Methods

Get all tags

Query Parameters

providers

attached_to

full_data

offset

limit

order_by_name

timeout

attached_only

Response Body

total_count

offset

limit

items

Status Code

200

400

401

403

407

500

default

No Sample Response

Delete unused tags

Query Parameters

providers

Response Body

total_count

errors

items

Status Code

200

400

401

500

default

No Sample Response

Delete a tag

Path Parameters

tag_name

Query Parameters

providers

Response Body

results

Status Code

200

400

401

default

Attach one or more tags

Request Body

resources

tag_name

tag_names

Response Body

results

Status Code

200

400

401

default

Detach one or more tags

Request Body

resources

tag_name

tag_names

Response Body

results

Status Code

200

400

401

default