IBM Cloud API Docs

Introduction

Last updated: 2022-05-09

The search service is a global and shared resource properties repository that is integrated in the IBM Cloud® platform. It's used for storing and searching cloud resource attributes. It categorizes and classifies resources. A resource is controlled and owned by resource providers within the IBM Cloud platform, such as IBM Cloud Kubernetes Service, or Resource Controller. Resources are uniquely identified by a Cloud Resource Naming identifier (CRN). The properties of a resource include tags and system properties. Both properties are defined within an IBM Cloud billing account, and span across many regions.

The search service can list, query, and retrieve information about IBM Cloud resources in the user IBM Cloud billing account, including IAM Access Groups (AG) and IAM Service IDs. It cannot retrieve resources that are:

Users
IAM API keys
IAM Trusted profiles
Context Based Restrictions (CBR) Zones and Rules
Support Cases
Billing data
Cost estimations.

The search service cannot retrieve Deployable Architectures (DA) and related information, documentation, or release notes.

SDKs for Java, Node, Python, and Go are available to make it easier to programmatically access the API from your code. The client libraries that are provided by the SDKs implement best practices for using the API and reduce the amount of code that you need to write. The tab for each language includes code examples that demonstrate how to use the client libraries. For more information about using the SDKs, see the IBM Cloud SDK Common project on GitHub.

To filter search results, you can apply query strings following the Lucene query syntax:

Basic Term: A single word is a term, and it searches for that word in all the resource attributes.
Example: database searches for the word database in all the resource attributes.
Phrase: A group of words surrounded by double quotes (" ") forms a phrase query, and it searches for all the words in the same order.
Example: "My resource" searches for the exact phrase in all the resource attributes.
Field: Specify a resource attribute for a term by prefixing it with the attribute name followed by a colon (:).
Example: name:my-resource searches for resources whose attribute name is my-resource.
Boolean Operators:
AND (finds resources containing both terms),
OR (finds resources containing either term),
NOT (excludes resources containing the term).
Boolean operators must be capitalized.
Example: my-resource AND database searches for words my-resource and database in all the resource attributes.
Wildcards: * matches any character sequence (including none), and ? matches a single character.
Example: my-res* finds my-resource, my-resources, etc.
Special characters: Enclose in double-quotes terms containing special characters: + & | ! ( ) { } [ ] ^ ~ : \ / as they are reserved in Lucene query syntax (e.g. CRNs, type-4 GUIDs). Example: name:"Fancy!Resource&Co.".
Ranges: Search for terms within a range. Can be numeric or alphabetical.
Inclusive range: [start TO end], exclusive range: {start TO end}.
Example: creation_date:[2021-01-01 TO 2021-12-31] finds resources whose creation_date is in the range.
Grouping: Group queries with parentheses (()) to control operator precedence.
Example: (database OR containers-kubernetes) AND name:my-resource find database or container-kubernetes resources named my-resource.

The most commonly used resource attributes (or fields) that you can query and retrieve are:

access_tags: The list of access management tags attached to the resource.
account_id: The billing account ID of the resource.
catalog_tags: The list of tags determining the resource categories.
creation_date: The date on which the resource was created in ISO format "YYYY-MM-DDTHH:mm:ss.SSSZ".
crn: The Cloud Resource Name in the format: "crn:version:cname:ctype:service-name:location:scope:service-instance:resource-type:resource".
modification_date: The date on which the resource was last updated in ISO format "YYYY-MM-DDTHH:mm:ss.SSSZ".
name: The user-provided resource name.
region: The IBM Cloud location of the resource.
resource_group_id: The unique identifier of the resource group into which the resource is provisioned.
service_instance: The unique identifier of the service instance.
resource_id: The unique identifier of the resource provisioned by a service instance.
service_name: The name of the service as it appears in the Name column of the output of ibmcloud catalog service-marketplace.
service_tags: The list of service tags attached to the resource.
tags: The list of user tags attached to the resource.
type: The type of the resource.

Using the /resources/search API you can retrieve or list IBM Cloud resources and services using a variety of filters.
Only resources that belong to the account ID and that are accessible by the client are returned.

Hereafter only some of the use cases that you can accomplish by building the right Lucene query.

To check if your backup policies are correctly configured you can use the query:
service_name:is AND type:backup-policy
which returns the backup policies that you are entitled to view.

You can verify when a PostgreSQL database named mydb was created and updated by using the query service_name:compose-for-postgresql AND name:mydb and check the creation_date and modification_date fields.

You can list resources whose name starts with either climate_change or global_warming by using the query name:(climate_change* OR global_warming*).

You can retrieve resources by date. For example, those updated between 2020 and 2022 using the query modification_date:[2020 TO 2022].
You can use the notation [now-X TO now] for time relative queries:

For "last X years" use the range [now-Xy TO now]
For "last X months" use the range [now-XM TO now]
For "last X weeks" use the range [now-Xw TO now]
For "last X days" use the range [now-Xd TO now]
For "last X hours" use the range [now-Xh TO now]
For "last X minutes" use the range [now-Xm TO now]
For "last X seconds" use the range [now-Xs TO now]

For example, the query creation_date:[now-1w TO now] returns the resources created in the last week.

Another interesting set of use cases is querying resources in your account by category: e.g., compute, network, storage, databases, security, devops.
Suppose you want to know if there are databases in your account. You can list them using the query:
catalog_tags:databases.

Similarly, if you want to know if there are specific services provisioned in your account you can use a query like:
service_name:(databases-for-elasticsearch OR cloudantnosqldb)
which returns instances of Elasticsearch or Cloudant databases that you are entitled to view.

Sometimes, you need to obtain the CRN of a resource given its name, or vice versa: the name of a resource given its CRN.
To do so you can use the queries:
name:your-resource-name and crn:”your-resource-crn” respectively.
You can use the service_instance:your-service-instance-id or resource_id:your-resource-id as an alternative to the CRN to retrieve the name of a resource.

Finally, you can filter resources by tags.
Suppose that you are interested in resources tagged as dev, test, and production.
You can use the queries:
tags:dev, tags:test, and tags:production respectively.

What if you are interested in resources provisioned with an enterprise project configuration?
All resources provisioned with a project do have service tags, which can be used to get them. For example, the query:
service_tags:(”project::config_id:1e3bf974-0f34-4a96-960b-15823558f952” AND “project::project_id:efd46015-1902-4465-99a4-a0e12fba5759”)
returns all the resources provisioned with the specified project_id and config_id.

Installing the Java SDK

Maven

<dependency>
	<groupId>com.ibm.cloud</groupId>
	<artifactId>global-search</artifactId>
	<version>{version}</version>
</dependency>
Copy to clipboard

Gradle

compile 'com.ibm.cloud:global-search:{version}'

Replace {version} in these examples with the release version.

View on GitHub

https://github.com/IBM/platform-services-java-sdk

Installing the Node SDK

npm install @ibm-cloud/platform-services

View on GitHub

https://github.com/IBM/platform-services-node-sdk

Installing the Python SDK

pip install --upgrade "ibm-platform-services"

View on GitHub

https://github.com/IBM/platform-services-python-sdk

Installing the Go SDK

Go modules (recommended): Add the following import in your code, and then run go build or go mod tidy

import (
	"github.com/IBM/platform-services-go-sdk/globalsearchv2"
)

Go get

go get -u github.com/IBM/platform-services-go-sdk/globalsearchv2

View on GitHub

https://github.com/IBM/platform-services-go-sdk

Endpoint URLs

The Global Search API uses the following public global endpoint URL. When you call the API, add the path for each method to form the complete API endpoint for your requests.

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

If you enabled service endpoints in your account, you can send API requests over the IBM Cloud private network at the following base endpoint URLs. For more information, see Enabling VRF and service endpoints.

Private endpoint URL (Dallas) for classic infrastructure: Dallas https://api.private.us-south.global-search-tagging.cloud.ibm.com

Example API request

curl --request POST --header "Content-Type: application/json" --header "Accept: application/json" --header "Authorization: Bearer <IAM token>" --data "{\"query\":\"string\"}" --url "https://api.global-search-tagging.cloud.ibm.com/v3/resources/search?account_id=string&limit=10&timeout=0&sort=string"
Copy to clipboard

Replace <IAM token> in this example with the value for your particular API call.

Authentication

Authorization to the Global Search API is enforced by using an IBM Cloud Identity and Access Management (IAM) access token. The token is used to determine the actions that a user or service ID has access to when they use the API.

Obtaining an IAM token for an authenticated user or service ID is described in the IAM Identity Services API documentation.

To use the API, add a valid IAM token to the HTTP Authorization request header, for example, --header "Authorization: Bearer <TOKEN>".

When you use the SDK, configure an IAM authenticator with the IAM API key. The authenticator automatically obtains the IAM access token for the API key and includes it with each request. You can construct an authenticator in either of two ways:

Programmatically by constructing an IAM authenticator instance and supplying your IAM API key
By defining the API key in external configuration properties and then using the SDK authenticator factory to construct an IAM authenticator that uses the configured IAM API key

In this example of using external configuration properties, an IAM authenticator instance is created with the configured API key, and then the service client is constructed with this authenticator instance and the configured service URL.

For more information, see the Authentication section of the IBM Cloud SDK Common documentation.

To call each method, you'll need to be assigned a role that includes the required IAM actions. Each method lists the associated action. For more information about IAM actions and how they map to roles, see Assigning access to account management services.

To retrieve your access token:

curl -X POST   "https://iam.cloud.ibm.com/identity/token"   --header 'Content-Type: application/x-www-form-urlencoded'   --header 'Accept: application/json'   --data-urlencode 'grant_type=urn:ibm:params:oauth:grant-type:apikey'   --data-urlencode 'apikey=<API_KEY>'
Copy to clipboard

Replace <API_KEY> with your IAM API key.

Setting client options through external configuration

Example environment variables, where <SERVICE_URL> is the endpoint URL and <API_KEY> is your IAM API key

export GLOBAL_SEARCH_URL=<SERVICE_URL>
export GLOBAL_SEARCH_AUTHTYPE=iam
export GLOBAL_SEARCH_APIKEY=<API_KEY>
Copy to clipboard

Example of constructing the service client

import {
    "github.com/IBM/platform-services-go-sdk/globalsearchv2"
}
...
serviceClientOptions := &globalsearchv2.GlobalSearchV2Options{}
serviceClient, err := globalsearchv2.NewGlobalSearchV2UsingExternalConfig(serviceClientOptions)

Setting client options through external configuration

Example environment variables, where <SERVICE_URL> is the endpoint URL and <API_KEY> is your IAM API key

export GLOBAL_SEARCH_URL=<SERVICE_URL>
export GLOBAL_SEARCH_AUTHTYPE=iam
export GLOBAL_SEARCH_APIKEY=<API_KEY>
Copy to clipboard

Example of constructing the service client

import com.ibm.cloud.platform_services.global_search.v2.GlobalSearch;
...
GlobalSearch serviceClient = GlobalSearch.newInstance();
Copy to clipboard

Setting client options through external configuration

Example environment variables, where <SERVICE_URL> is the endpoint URL and <API_KEY> is your IAM API key

export GLOBAL_SEARCH_URL=<SERVICE_URL>
export GLOBAL_SEARCH_AUTHTYPE=iam
export GLOBAL_SEARCH_APIKEY=<API_KEY>
Copy to clipboard

Example of constructing the service client

const GlobalSearchV2 = require('@ibm-cloud/platform-services/global-search/v2');
...
const serviceClient = GlobalSearchV2.newInstance({});
Copy to clipboard

Setting client options through external configuration

Example environment variables, where <SERVICE_URL> is the endpoint URL and <API_KEY> is your IAM API key

export GLOBAL_SEARCH_URL=<SERVICE_URL>
export GLOBAL_SEARCH_AUTHTYPE=iam
export GLOBAL_SEARCH_APIKEY=<API_KEY>
Copy to clipboard

Example of constructing the service client

from ibm_platform_services import GlobalSearchV2
...
global_search_service = GlobalSearchV2.new_instance()

Error handling

Global Search 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.

Methods

Find IAM-enabled resources or storage and network resources that run on classic infrastructure in a specific account ID.

To filter results, you can apply query strings following the Lucene query syntax.

Only resources that belong to the account ID and that are accessible by the client are returned.

The usage of this API is deprecated for cases when the provider is not specified or provider=ghost. /v3/resources/search replaces this API for the deprecated cases.

POST /v2/resources/search

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

global-search-tagging.resource.read

Request

Custom Headers

x-request-id
string
An alphanumeric string that is used to trace the request. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*
x-correlation-id
string
An alphanumeric string that is used to trace the request as a part of a larger context: the same value is used for downstream requests and retries of those requests. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*
X-IMS-Auth-Token
string
The SoftLayer authorization token. You must set it only if you are searching SoftLayer resources, which you do adding ims to the search providers query parameter.

Possible values: Value must match regular expression ^Basic .*$

Query Parameters

account_id
string
The account ID to filter resources.

Possible values: Value must match regular expression ^[a-fA-F0-9]{32}$|^[*]{1}$
limit
integer
The maximum number of hits to return. Defaults to 10.

Possible values: 1 ≤ value ≤ 1000
Default: 10
timeout
integer
A search timeout in milliseconds, bounding the search request to run within the specified time value and bail with the hits accumulated up to that point when expired. Defaults to the system defined timeout.

Possible values: 0 ≤ value ≤ 600000
Default: 0
is_deleted
string
Determines if deleted documents should be included in result set or not. Possible values are false (default), true or any. If false, only existing documents are returned; if true, only deleted documents are returned; If any, both existing and deleted documents are returned. (for administrators only).

Allowable values: [true,false,any]
Default: false
is_reclaimed
string
Determines if reclaimed documents should be included in result set or not. Possible values are false (default), true or any. If false, only not reclaimed documents are returned; if true, only reclaimed documents are returned; If any, both reclaimed and not reclaimed documents are returned.

Allowable values: [true,false,any]
Default: false
is_public
string
Determines if public resources should be included in result set or not. Possible values are false (default), true or any. If false, do not search public resources; if true, search only public resources; If any, search also public resources.

Allowable values: [true,false,any]
Default: false
impersonate_user
string
The user on whose behalf the search must be performed. Only a GhoST admin can impersonate a user, so be sure you set a GhoST admin IAM token in the Authorization header if you set this parameter. (for administrators only).

Possible values: Value must match regular expression ^.*-.*$
can_tag
string
Determines if the result set must return the resources that the user can tag or the resources that the user can view (only a GhoST admin can use this parameter). If false (default), only resources user can view are returned; if true, only resources that user has permissions for tagging are returned (for administrators only).

Allowable values: [true,false]
Default: false
is_project_resource
string
Determines if documents belonging to Project family should be included in result set or not. Possible values are false (default), true or any. If false, documents belonging to all families except Project are returned; if true, only documents belonging to Project family are returned; if any, documents of any family are returned. Only authorized ServiceIds can use this query parameter.

Allowable values: [true,false,any]
Default: false
offset
integer
The offset is the index of the item you want to start returning data from. Default is 0.

Possible values: 0 ≤ value ≤ 10000
Default: 0
sort
string
Comma separated properties name that is used for sorting
provider
string
Search providers. Supported values are ghost and ims. If not specified, the defaults to ghost. Specify a single provider.

Allowable values: [ghost,ims]
Default: ghost

Request Body

Required*

SearchBody

It contains the query filters, the list of fields to be returned, and the search token (initially set to null or undefined)

Examples:

Response

Response Body

SearchResults

The results of the requested search.

Status Code

200
A result paging with the list of resources that match the provided filters.
400
Bad Request
401
Unauthorized / Wrong auth token type IAM / Auth token not valid
403
Unauthorized operation
429
Too Many Requests
500
Internal Server Error / IAM not initialized / Malformed IAM credentials
502
Search IAM error
default
System problem or unexpected error

No Sample Response

This method does not specify any sample responses.

Find IAM-enabled resources or storage and network resources that run on classic infrastructure in a specific account ID.

To filter results, you can apply query strings following the Lucene query syntax.

By default, the fields that are returned for every resource are crn, name, family, type, and account_id. You can specify the subset of the fields you want in your request using the fields request body attribute. Set "fields": ["*"] to discover the complete set of fields which are available to request.

Find Cloud Foundry resources, IAM-enabled resources, or storage and network resources that run on classic infrastructure in a specific account ID. You can apply query strings if necessary.

To filter results, you can insert a string by using the Lucene syntax and the query string is parsed into a series of terms and operators. A term can be a single word or a phrase, in which case the search is performed for all the words, in the same order. To filter for a specific value regardless of the property that contains it, type the search term without specifying a field. Only resources that belong to the account ID and that are accessible by the client are returned.

You must use /v3/resources/search when you need to fetch more than 10000 resource items. On the first call, the operation returns a live cursor on the data that you must use on all the subsequent calls to get the next batch of results until you get the empty result set. By default, the fields that are returned for every resource are "crn", "name", "family", "type", and "account_id". You can specify the subset of the fields you want in your request.

Find Cloud Foundry resources, IAM-enabled resources, or storage and network resources that run on classic infrastructure in a specific account ID. You can apply query strings if necessary.

POST /v3/resources/search

(globalSearch *GlobalSearchV2) Search(searchOptions *SearchOptions) (result *ScanResult, response *core.DetailedResponse, err error)

(globalSearch *GlobalSearchV2) SearchWithContext(ctx context.Context, searchOptions *SearchOptions) (result *ScanResult, response *core.DetailedResponse, err error)

ServiceCall<ScanResult> search(SearchOptions searchOptions)
Copy to clipboard

search(params)

search(
        self,
        *,
        query: str = None,
        fields: List[str] = None,
        search_cursor: str = None,
        transaction_id: str = None,
        account_id: str = None,
        limit: int = None,
        timeout: int = None,
        sort: List[str] = None,
        is_deleted: str = None,
        is_reclaimed: str = None,
        is_public: str = None,
        impersonate_user: str = None,
        can_tag: str = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

global-search-tagging.resource.read

Request

Instantiate the SearchOptions struct and set the fields to provide parameter values for the Search method.

Use the SearchOptions.Builder to create a SearchOptions object that contains the parameter values for the search method.

Custom Headers

x-request-id
string
An alphanumeric string that is used to trace the request. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*
x-correlation-id
string
An alphanumeric string that is used to trace the request as a part of a larger context: the same value is used for downstream requests and retries of those requests. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*

Query Parameters

account_id
string
The account ID to filter resources.

Possible values: Value must match regular expression ^[a-fA-F0-9]{32}$|^[*]{1}$
limit
integer
The maximum number of hits to return. Defaults to 10.

Possible values: 1 ≤ value ≤ 1000
Default: 10
timeout
integer
A search timeout in milliseconds, bounding the search request to run within the specified time value and bail with the hits accumulated up to that point when expired. Defaults to the system defined timeout.

Possible values: 0 ≤ value ≤ 600000
Default: 0
sort
string[]
Comma separated properties names that are used for sorting

Possible values: Value must match regular expression ^[+-]?\w+[\w\-\.]*$
is_deleted
string
Determines if deleted documents should be included in result set or not. Possible values are false (default), true or any. If false, only existing documents are returned; if true, only deleted documents are returned; If any, both existing and deleted documents are returned. (for administrators only).

Allowable values: [true,false,any]
Default: false
is_reclaimed
string
Determines if reclaimed documents should be included in result set or not. Possible values are false (default), true or any. If false, only not reclaimed documents are returned; if true, only reclaimed documents are returned; If any, both reclaimed and not reclaimed documents are returned.

Allowable values: [true,false,any]
Default: false
is_public
string
Determines if public resources should be included in result set or not. Possible values are false (default), true or any. If false, do not search public resources; if true, search only public resources; If any, search also public resources.

Allowable values: [true,false,any]
Default: false
impersonate_user
string
The user on whose behalf the search must be performed. Only a GhoST admin can impersonate a user, so be sure you set a GhoST admin IAM token in the Authorization header if you set this parameter. (for administrators only).

Possible values: Value must match regular expression ^.*-.*$
can_tag
string
Determines if the result set must return the resources that the user can tag or the resources that the user can view (only a GhoST admin can use this parameter). If false (default), only resources user can view are returned; if true, only resources that user has permissions for tagging are returned (for administrators only).

Allowable values: [true,false]
Default: false
is_project_resource
string
Determines if documents belonging to Project family should be included in result set or not. Possible values are false (default), true or any. If false, documents belonging to all families except Project are returned; if true, only documents belonging to Project family are returned; if any, documents of any family are returned. Only authorized ServiceIds can use this query parameter.

Allowable values: [true,false,any]
Default: false

Request Body

Required*

One of

Change Schema Parameter List

It contains the query filters on the first operation call, or the search_cursor on next calls. On subsequent calls, set the search_cursor to the value returned by the previous call. After the first, you must set only the search_cursor. Any other parameter but the search_cursor are ignored. The search_cursor encodes all the information that needs to get the next batch of limit data.

parameter

WithContext method only

SearchOptions

The Search options.

SearchOptions

The search options.

parameters

query
string
The Lucene-formatted query string. Default to '*' if not set.
fields
string[]
The list of the fields returned by the search. By default, the returned fields are the account_id, name, type, family, and crn. For all queries, crn is always returned.

Possible values: number of items ≥ 1, Value must match regular expression /^\\S+$/
searchCursor
string
An opaque cursor that is returned on each call and that must be set on the subsequent call to get the next batch of items. If the search returns no items, then the search_cursor is not present in the response.

Possible values: length ≥ 1
transactionId
string
An alphanumeric string that can be used to trace a request across services. If not specified, it automatically generated with the prefix "gst-".

Possible values: 1 ≤ length ≤ 150, Value must match regular expression /.*/
accountId
string
The account ID to filter resources.

Possible values: Value must match regular expression /^[a-zA-Z0-9.]+$|^[*]{1}$/
limit
number
The maximum number of hits to return. Defaults to 10.

Possible values: 1 ≤ value ≤ 1000
Default: 10
timeout
number
A search timeout in milliseconds, bounding the search request to run within the specified time value and bail with the hits accumulated up to that point when expired. Defaults to the system defined timeout.

Possible values: 0 ≤ value ≤ 600000
Default: 0
sort
string[]
Comma separated properties names that are used for sorting.

Possible values: Value must match regular expression /^[+-]?\\w+[\\w\\-\\.]*$/
isDeleted
string
Determines if deleted documents should be included in result set or not. Possible values are false (default), true or any. If false, only existing documents are returned; if true, only deleted documents are returned; If any, both existing and deleted documents are returned. (for administrators only).

Allowable values: [true,false,any]
Default: false
isReclaimed
string
Determines if reclaimed documents should be included in result set or not. Possible values are false (default), true or any. If false, only not reclaimed documents are returned; if true, only reclaimed documents are returned; If any, both reclaimed and not reclaimed documents are returned.

Allowable values: [true,false,any]
Default: false
isPublic
string
Determines if public resources should be included in result set or not. Possible values are false (default), true or any. If false, do not search public resources; if true, search only public resources; If any, search also public resources.

Allowable values: [true,false,any]
Default: false
impersonateUser
string
The user on whose behalf the search must be performed. Only a GhoST admin can impersonate a user, so be sure you set a GhoST admin IAM token in the Authorization header if you set this parameter. (for administrators only).

Possible values: Value must match regular expression /^.*-.*$/
canTag
string
Determines if the result set must return the resources that the user can tag or the resources that the user can view (only a GhoST admin can use this parameter). If false (default), only resources user can view are returned; if true, only resources that user has permissions for tagging are returned (for administrators only).

Allowable values: [true,false]
Default: false

parameters

query
str
The Lucene-formatted query string. Default to '*' if not set.
fields
List[str]
The list of the fields returned by the search. By default, the returned fields are the account_id, name, type, family, and crn. For all queries, crn is always returned.

Possible values: number of items ≥ 1, Value must match regular expression /^\\S+$/
search_cursor
str
An opaque cursor that is returned on each call and that must be set on the subsequent call to get the next batch of items. If the search returns no items, then the search_cursor is not present in the response.

Possible values: length ≥ 1
transaction_id
str
An alphanumeric string that can be used to trace a request across services. If not specified, it automatically generated with the prefix "gst-".

Possible values: 1 ≤ length ≤ 150, Value must match regular expression /.*/
account_id
str
The account ID to filter resources.

Possible values: Value must match regular expression /^[a-zA-Z0-9.]+$|^[*]{1}$/
limit
int
The maximum number of hits to return. Defaults to 10.

Possible values: 1 ≤ value ≤ 1000
Default: 10
timeout
int
A search timeout in milliseconds, bounding the search request to run within the specified time value and bail with the hits accumulated up to that point when expired. Defaults to the system defined timeout.

Possible values: 0 ≤ value ≤ 600000
Default: 0
sort
List[str]
Comma separated properties names that are used for sorting.

Possible values: Value must match regular expression /^[+-]?\\w+[\\w\\-\\.]*$/
is_deleted
str
Determines if deleted documents should be included in result set or not. Possible values are false (default), true or any. If false, only existing documents are returned; if true, only deleted documents are returned; If any, both existing and deleted documents are returned. (for administrators only).

Allowable values: [true,false,any]
Default: false
is_reclaimed
str
Determines if reclaimed documents should be included in result set or not. Possible values are false (default), true or any. If false, only not reclaimed documents are returned; if true, only reclaimed documents are returned; If any, both reclaimed and not reclaimed documents are returned.

Allowable values: [true,false,any]
Default: false
is_public
str
Determines if public resources should be included in result set or not. Possible values are false (default), true or any. If false, do not search public resources; if true, search only public resources; If any, search also public resources.

Allowable values: [true,false,any]
Default: false
impersonate_user
str
The user on whose behalf the search must be performed. Only a GhoST admin can impersonate a user, so be sure you set a GhoST admin IAM token in the Authorization header if you set this parameter. (for administrators only).

Possible values: Value must match regular expression /^.*-.*$/
can_tag
str
Determines if the result set must return the resources that the user can tag or the resources that the user can view (only a GhoST admin can use this parameter). If false (default), only resources user can view are returned; if true, only resources that user has permissions for tagging are returned (for administrators only).

Allowable values: [true,false]
Default: false

Example request

curl -X POST --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   -d '{"query": "GST-sdk-*", "fields": ["*"]}'   "{base_url}/v3/resources/search"
Copy to clipboard

Example request

searchOptions := globalSearchService.NewSearchOptions()
searchOptions.SetLimit(10)
searchOptions.SetQuery("GST-sdk-*")
searchOptions.SetFields([]string{"*"})

scanResult, response, err := globalSearchService.Search(searchOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(scanResult, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

SearchOptions searchOptions = new SearchOptions.Builder()
  .query("GST-sdk-*")
  .fields(new java.util.ArrayList<String>(java.util.Arrays.asList("*")))
  .searchCursor(searchCursor)
  .build();

Response<ScanResult> response = service.search(searchOptions).execute();
ScanResult scanResult = response.getResult();

System.out.println(scanResult);
Copy to clipboard

Example request

const params = {
  query: 'GST-sdk-*',
  fields: ['*'],
  searchCursor: searchCursor,
};

globalSearchService.search(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
Copy to clipboard

Example request

response = global_search_service.search(query='GST-sdk-*',
                    fields=['*'])
scan_result = response.get_result()

print(json.dumps(scan_result, indent=2))
Copy to clipboard

Response

Response Body

ScanResult

The search scan response

ScanResult

The search scan response.

ScanResult

The search scan response.

ScanResult

The search scan response.

ScanResult

The search scan response.

Status Code

200
A result paging with the list of resources that match the provided filters.
400
Bad Request
401
Unauthorized / Wrong auth token type IAM / Auth token not valid
403
Unauthorized operation
429
Too Many Requests
500
Internal Server Error / IAM not initialized / Malformed IAM credentials
502
Search IAM error
default
System problem or unexpected error

No Sample Response

This method does not specify any sample responses.

Collects from Globalcatalog the information about categories, subcategories (children), and services that belong to those categories.

GET /v3/resources/catalog_categories

Request

Custom Headers

x-request-id
string
An alphanumeric string that is used to trace the request. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*
x-correlation-id
string
An alphanumeric string that is used to trace the request as a part of a larger context: the same value is used for downstream requests and retries of those requests. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*

Query Parameters

translations_lang
string
The language you want to retrieve the Catalog translations. Default to English if not set.

Allowable values: [en,de,es,fr,it,pt-br,ja,ko,zh-cn,zh-tw]
Default: en

Response

Response Body

CatalogCategories

The Global catalog categories, subcategories, and services

Status Code

200
A request status object
401
Missing or bad authentication
429
Too Many Requests
500
Internal Server Error
default
System problem or unexpected error

Example responses

Status 200

{
  "categories": [
    {
      "id": "the category identifier in GC",
      "tags": [
        "category tags"
      ],
      "display_name": "the display name in the selected language",
      "services": [
        {
          "id": "the service identifier in GC",
          "name": "the service name in GC... and in GhoST",
          "display_name": "the display name in the selected language",
          "kind": "service|any other GC entry type",
          "gst_support": true
        }
      ],
      "children": [
        {
          "id": "id of a child/sub-category in GC",
          "tags": [
            "sub-category tags"
          ],
          "display_name": "the display name in the selected language",
          "services": [
            {
              "id": "the service identifier in GC",
              "display_name": "the service name in GC and in GhoST",
              "name": "the display name in the selected language",
              "kind": "service|any other GC entry type",
              "gst_support": true
            }
          ]
        }
      ]
    }
  ]
}
Copy to clipboard

health endpoint

GET /health

Request

Custom Headers

x-request-id
string
An alphanumeric string that is used to trace the request. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*
x-correlation-id
string
An alphanumeric string that is used to trace the request as a part of a larger context: the same value is used for downstream requests and retries of those requests. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*

Response

Response Body

HealthResponse

Definition of success health response

Status Code

200
Success
424
Failed Dependency Error
429
Failed - Too Many Requests

No Sample Response

This method does not specify any sample responses.

alive endpoint

GET /alive

Request

Custom Headers

x-request-id
string
An alphanumeric string that is used to trace the request. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*
x-correlation-id
string
An alphanumeric string that is used to trace the request as a part of a larger context: the same value is used for downstream requests and retries of those requests. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*

Response

Response Body

AliveResponse

Definition of success alive response

Status Code

200
Success
429
Too Many Requests
501
Failed Dependency Error

No Sample Response

This method does not specify any sample responses.

Group resources into buckets based on field values, ranges, or other criteria. You can apply query strings if necessary. The query string follows the Lucene syntax, like for the /v3/resources/search.

POST /v3/resources/aggregate

Request

Custom Headers

x-request-id
string
An alphanumeric string that is used to trace the request. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*
x-correlation-id
string
An alphanumeric string that is used to trace the request as a part of a larger context: the same value is used for downstream requests and retries of those requests. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*

Query Parameters

timeout
integer
A search timeout in milliseconds, bounding the search request to run within the specified time value and bail with the hits accumulated up to that point when expired. Defaults to the system defined timeout.

Possible values: 0 ≤ value ≤ 600000
Default: 0
is_deleted
string
Determines if deleted documents should be included in result set or not. Possible values are false (default), true or any. If false, only existing documents are returned; if true, only deleted documents are returned; If any, both existing and deleted documents are returned. (for administrators only).

Allowable values: [true,false,any]
Default: false
is_reclaimed
string
Determines if reclaimed documents should be included in result set or not. Possible values are false (default), true or any. If false, only not reclaimed documents are returned; if true, only reclaimed documents are returned; If any, both reclaimed and not reclaimed documents are returned.

Allowable values: [true,false,any]
Default: false
is_project_resource
string
Determines if documents belonging to Project family should be included in result set or not. Possible values are false (default), true or any. If false, documents belonging to all families except Project are returned; if true, only documents belonging to Project family are returned; if any, documents of any family are returned. Only authorized ServiceIds can use this query parameter.

Allowable values: [true,false,any]
Default: false

Request Body

Required*

AggregateBody

It contains the query filters and the terms aggregation instructions.

Examples:

Response

Response Body

AggregateResult

The resources aggregate response

Status Code

200
The aggregated query results. filters.
400
Bad Request
401
Unauthorized, missing or invalid authorization.
403
Forbidden request.
429
Too Many Requests.
500
Internal server error.
502
Proxy or gateway error.
503
The server is currently unabled to handle the request.
default
Temporary server error.

Example responses

Status 200

{
  "aggregation": {
    "terms": {
      "doc_count_error_upper_bound": 0,
      "sum_other_doc_count": 4794,
      "buckets": [
        {
          "term": "f065ca930006416511b1ebd61681ef9f",
          "doc_count": 123234
        },
        {
          "term": "b0000a9831104111171eae0089e90300",
          "doc_count": 3456
        }
      ]
    }
  }
}
Copy to clipboard

id=curlclassName=tab-item-selected

Introduction

Endpoint URLs

Authentication

Error handling

Methods

Find instances of resources (v2)

Authorization

Request

Custom Headers

x-request-id

x-correlation-id

X-IMS-Auth-Token

Query Parameters

account_id

limit

timeout

is_deleted

is_reclaimed

is_public

impersonate_user

can_tag

is_project_resource

offset

sort

provider

Request Body

query

fields

token

Response

Response Body

more_data

items

any property

filter_error

partial_data

offset

limit

token

Status Code

200

400

401

403

429

500

502

default

No Sample Response

Find instances of resources (v3)

Authorization

Request

Custom Headers

x-request-id

x-correlation-id

Query Parameters

account_id

limit

timeout

sort

is_deleted

is_reclaimed

is_public

impersonate_user

can_tag

is_project_resource

Request Body

query

fields

parameter

ctx

SearchOptions

Query

Fields

SearchCursor

TransactionID

AccountID

Limit

Timeout

Sort