Introduction

IBM Cloud™ resource manager manages the collection of resources by resource groups.

A resource group belongs to an account. All IBM Cloud resources must be provisioned within a resource group. When a user creates an account, a default resource group is created in the account. In a Lite account, a user can have only one resource group. For a Pay-As-You-Go or Subscription account, a user can create more than one resource group.

If an account is suspended, the corresponding resource group and all resources within it are also suspended.

API endpoint

https://resource-controller.cloud.ibm.com

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response indicates success. A 400 type response indicates a failure, and a 500 type response indicates an internal system error.

HTTP Error Code Description Recovery
200 Success The request was successful.
201 Success The resource group was successfully created.
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.
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.

Authentication

To work with the API, authenticate your app or service by including your IBM Cloud IAM access token in the API request authentication header:

-H 'Authorization: Bearer <IAM_TOKEN>'

You can retrieve an access token by first creating an API key, and then exchanging your API key for a IBM Cloud IAM token. For more information, see Getting an IBM Cloud IAM token by using an API key.

To retrieve your access token:

curl -X POST
https://iam.cloud.ibm.com/identity/token
  -H "Content-Type: application/x-www-form-urlencoded"
  -H "Accept: application/json"
  -d "grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey&apikey=<API_KEY>"

Replace <API_KEY> with your service credentials. Then use the full IAM token value, prefixed by the Bearer token type, to authenticate your API requests.

To retrieve your instance ID:

ibmcloud resource service-instance <instance_name> --id

Replace <instance_name> with the unique alias that you assigned to your service instance.

Rate limiting

Rate limits for API requests are enforced on a per-caller basis. If the number of requests for a particular method and endpoint reaches the request limit within the specified time window, no further requests are accepted until the timer expires. After the timer expires, a new time window begins with the next accepted request.

The response to each HTTP request includes headers that you can use to determine whether you are close to the rate limit:

  • X-RateLimit-Reset: The time the current timer expires (in UNIX epoch time)
  • X-RateLimit-Remaining: The number of requests remaining in the current time window
  • X-RateLimit-Limit: The total number of requests that are allowed within the time window

An HTTP status code of 429 indicates that the rate limit was exceeded.

Currently, the rate of allowed requests for all resource manager APIs are 500 requests per 10 seconds.

See the following related APIs for more actions for service and resource management.

Methods

Get a list of all resource groups

Get a list of all resource groups in an account.

GET /resource_groups
Request

Custom Headers

  • Your IBM Cloud IAM access token.

Query Parameters

  • The ID of the account that contains the resource groups that you want to get.

Response

Status Code

  • The resource groups was successfully retrieved.

  • The request could have invalid payload.

  • Your access token is invalid or authenication of your token failed.

  • Your access token is valid but does not have the necessary permissions to access this resource.

  • The resource could not be found.

  • Too many requests. Please wait a few minutes and try again.

  • Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Create a new resource group

Create a new resource group in an account.

POST /resource_groups
Request

Custom Headers

  • Your IBM Cloud IAM access token.

Response

Status Code

  • Resource group has been created.

  • The request could have invalid payload.

  • Your access token is invalid or authenication of your token failed.

  • Your access token is valid but does not have the necessary permissions to access this resource.

  • The resource could not be found.

  • Too many requests. Please wait a few minutes and try again.

  • Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Get a resource group

Retrieve a resource group by ID.

GET /resource_groups/{id}
Request

Custom Headers

  • Your IBM Cloud IAM access token.

Path Parameters

  • The short or long ID of the alias.

Response

Status Code

  • 200 OK

  • Your access token is invalid or authenication of your token failed.

  • Your access token is valid but does not have the necessary permissions to access this resource.

  • The resource could not be found.

  • Too many requests. Please wait a few minutes and try again.

  • Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Update a resource group

Update a resource group by ID.

PATCH /resource_groups/{id}
Request

Custom Headers

  • Your IBM Cloud IAM access token.

Path Parameters

  • The short or long ID of the resource group.

Response

Status Code

  • Successfully updated resource group.

  • The request could have invalid payload.

  • Your access token is invalid or authenication of your token failed.

  • Your access token is valid but does not have the necessary permissions to access this resource.

  • The resource could not be found.

  • Too many requests. Please wait a few minutes and try again.

  • Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Get a list of all quota definitions

Get a list of all quota definitions.

GET /quota_definitions
Request

Custom Headers

  • Your IBM Cloud IAM access token.

Response

Status Code

  • The quota definitions were successfully retrieved.

  • The request could have invalid payload.

  • Your access token is invalid or authenication of your token failed.

  • Your access token is valid but does not have the necessary permissions to access this resource.

  • The resource could not be found.

  • Too many requests. Please wait a few minutes and try again.

  • Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Get a quota definition

Get a a quota definition.

GET /quota_definitions/{id}
Request

Custom Headers

  • Your IBM Cloud IAM access token.

Path Parameters

  • The id of the quota.

Response

Status Code

  • The quota is successfully retrieved.

  • The request could have invalid payload.

  • Your access token is invalid or authenication of your token failed.

  • Your access token is valid but does not have the necessary permissions to access this resource.

  • The resource could not be found.

  • Too many requests. Please wait a few minutes and try again.

  • Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses