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 them by tag name or resource groups or 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

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

/v3/tags

Request

Custom Headers

Content-Type
string
Allowable values: [application/json,application/octet-stream]

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]
order_by_name
string
Order the output by tag name.

Allowable values: [asc,desc]
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
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

Response

Response Body

SearchResultV3

A single object

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 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

Custom Headers

Content-Type
string
Allowable values: [application/json,application/octet-stream]

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

ResultItemDeleteV3

A single object

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",
      "isError": false
    },
    {
      "provider": "ims",
      "isError": 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",
      "isError": false
    },
    {
      "provider": "ims",
      "isError": 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 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

/v3/tags/attach

Request

Custom Headers

Content-Type
string
Allowable values: [application/json,application/octet-stream]

Request Body

ConnectionBody_v3attach

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

ResultItemV3

A single object

Status Code

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

Example responses

Status 200

{
  "results": [
    {
      "resourceId": "crn",
      "isError": false
    },
    {
      "resourceId": "75ffffwer7",
      "isError": 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": [
    {
      "resourceId": "crn",
      "isError": false
    },
    {
      "resourceId": "75ffffwer7",
      "isError": 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

Custom Headers

Content-Type
string
Allowable values: [application/json,application/octet-stream]

Request Body

ConnectionBody_v3detach

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

ResultItemV3

A single object

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": [
    {
      "resourceId": "crn",
      "isError": false
    },
    {
      "resourceId": "75ffffwer7",
      "isError": 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": [
    {
      "resourceId": "crn",
      "isError": false
    },
    {
      "resourceId": "75ffffwer7",
      "isError": 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

Custom Headers

Content-Type

Query Parameters

providers

order_by_name

attached_to

full_data

offset

limit

timeout

Response Body

items

name

Status Code

200

400

401

403

407

500

default

No Sample Response

Delete a tag

Custom Headers

Content-Type

Path Parameters

tag_name

Query Parameters

providers

Response Body

results

resource_id

isError

Status Code

200

400

401

default

Attach one ore more tags

Custom Headers

Content-Type

Request Body

resources

tag_name

tag_names

Response Body

results

resource_id

isError

Status Code

200

400

401

default

Detach one or more tags

Custom Headers

Content-Type

Request Body

resources

tag_name

tag_names

Response Body

results

resource_id

isError

Status Code

200

400

401

default