IBM Cloud API Docs

Introduction

With IBM Cloud® Functions you can use you can use your favorite programming language to write lightweight code that executes app logic in a scalable way. You can run code on-demand with HTTP-based API requests from applications or automatically in response to IBM Cloud services and third-party events. The Function-as-a-Service (Faas) programming platform is based on the open source project Apache OpenWhisk.

Because Cloud Functions is serverless, you're not limited in the languages that you can use and you don't have to spend time explicitly provisioning backend infrastructure. You can focus on writing app logic instead of worrying about auto-scaling, high availability, updates, or maintenance. Out of the box, IBM provides the hardware, networking, software administration, load balancing, plugins, and so on. You just have to bring the code!

You can use one of the following client libraries to access the Cloud Functions API.

For help getting started with Cloud Functions, check out the Cloud Functions documentation.

Authentication

This API is protected with HTTP Basic authentication. The Basic authentication credentials are in the AUTH property in your ~/.wskprops file, delimited by a colon. You can also retrieve these credentials by using the CLI running ibmcloud fn property get --auth.

In the following cURL example, authentication is passed by using the -u flag: curl -u USERNAME:PASSWORD https://us-south.functions.cloud.ibm.com/api/v1.

You can also include authentication part of the URL: curl https://USERNAME:PASSWORD@us-south.functions.cloud.ibm.com/api/v1.

For the {namespace} in the URL, the underscore character (_) can be used to specify the user's default namespace.

You can create and manage new Identity and Access Management (IAM)-based namespaces in IBM Cloud® Functions. Unlike Cloud Foundry-based namespaces, which are generated from your Cloud Foundry org and space names, IAM-based namespaces are created in resource groups and are managed with IAM access policies.

This API requires IBM Cloud Identity and Access Management (IAM) authentication. You can retrieve your IAM access token by running ibmcloud iam oauth-tokens. You must pass the IAM token in the Authorization header. For each API, an authorization check is made, to ensure that the user has the appropriate role for executing the request. For more information about service-specific roles, see Service-specific roles.

When you invoke an action from a public package such as /whisk.system/utils/echo, you need to set the header x-namespace-id to one of your IAM managed namespaces. This will also determine the scope of the accounting.

For specific information about using IAM with Cloud Functions, see the Cloud Functions documentation.

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response always indicates success. A 400 type response is some sort of failure, and a 500 type response usually indicates 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}'. Check that you have the correct access credentials and permissions.
404 Not Found The requested resource could not be found. Check that the namespace ID is correct and try again.
408 Request Timeout The connection to the server timed out. Wait a few minutes, then try again.
409 Conflict The entity is already in the requested state.
500 Internal Server Error IBM Cloud Functions is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.
502 Bad Gateway A call forwarding component received an invalid response while working as a gateway to handle the response.

Methods

Get all namespaces

List all namespaces; including IAM and Cloud Foundry-based namespaces. A namespace groups Cloud Functions entities such as actions or rules. The /whisk.system namespace is reserved for entities that are distributed with the Cloud Functions system. Note: If you pass basic authorization instead of an IAM access token, the Cloud Foundry-based namespace associated with these authorization credentials is returned. For namespaces of type classic which have not been migrated (classic_type: 1) only a subset of properties is provided. The properties name, description, crn, resource_plan_id, and service_id are unavailable.

GET /namespaces

Request

Custom Headers

  • Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Query Parameters

  • The maximum number of namespaces to return. Default 100. Maximum 200.

  • The number of namespaces to skip. Default 0.

  • curl --request GET   --url 'https://us-south.functions.cloud.ibm.com/api/v1/namespaces?limit=0&skip=0'   --header 'accept: application/json'   --header 'authorization: <IAM_token>'
  • HttpResponse<String> response = Unirest.get("https://us-south.functions.cloud.ibm.com/api/v1/namespaces")
      .header("accept", "application/json")
      .asString();
  • var options = {
      "method": "GET",
      "hostname": "us-south.functions.cloud.ibm.com",
      "port": null,
      "path": "/api/v1/namespaces",
      "headers": {
        "accept": "application/json"
      }
    };
    
    var req = http.request(options, function (res) {
      var chunks = [];
    
      res.on("data", function (chunk) {
        chunks.push(chunk);
      });
    
      res.on("end", function () {
        var body = Buffer.concat(chunks);
        console.log(body.toString());
      });
    });
    
    req.end();
    
  • import http.client
    
    conn = http.client.HTTPSConnection("us-south.functions.cloud.ibm.com")
    
    [object Object]
    conn.request("GET", "/api/v1/namespaces", headers=headers)
    
    res = conn.getresponse()
    data = res.read()
    
    print(data.decode("utf-8"))
    

Response

Successful response when listing namespaces

Status Code

  • Success

  • Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • Forbidden. This action requires the Reader, Writer, or Manager role for the namespace. Contact your account owner to change your IAM access policies.

  • Internal Server Error. IBM Cloud Functions is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses
  • {
      "limit": 10,
      "offset": 0,
      "total_Count": 2,
      "namespaces": [
        {
          "id": "organization_space",
          "location": "us-south",
          "classic_type": 1,
          "classic_spaceguid": "12345678-1234-abcd-1234-123456789abc"
        },
        {
          "id": "12345678-1234-abcd-1234-123456789abc",
          "name": "My Namespace",
          "description": "namespace for project A",
          "location": "us-south",
          "resource_plan_id": "functions-base-plan",
          "service_id": "ServiceId-12345678-1234-abcd-1234-123456789abc",
          "crn": "crn:v1:bluemix:public:functions:us-south:a/1a22bb3c44dd1a22bb3c44dd1a22:12345678-1234-abcd-1234-123456789abc"
        }
      ]
    }

Create a namespace

Create an IAM-enabled IBM Cloud Functions namespace. The following IBM Cloud artifacts are created. For more information, see the IAM-based namespace topic. in the IBM Cloud Functions documentation.

  • Service instance for the IBM Cloud namespace resource - The namespace is created as an IBM Cloud resource and is identified by an IAM-managed service instance. To see service instances, run ibmcloud resource service-instances --service-name functions.
  • Service ID - For each namespace, a service ID is created as a functional id that represents the namespace. All of the actions that are created in this namespace can use this Service ID for access to other resources. To see all of your Service IDs, run ibmcloud iam service-ids. For more information, see IAM documentation for Service ID.
  • API key for the service ID - The API key can be used by action code to derive IAM token and authenticate with other IBM Cloud services; it will be provided to the actions as environment variable. Also see the IAM documentation. To see all of your API keys, run ibmcloud fn iam service-api-keys <ServiceID-12345678-1234-abcd-1234-123456789abc> and be sure to include your service ID.
  • IBM Cloud IAM policies - IAM service policies for the ServiceID to allow other services to work with the namespace service instance. To see service policies, run ibmcloud iam service-policies.
POST /namespaces

Request

Custom Headers

  • Your IBM Cloud Identity and Access Management (IAM) token.

The request body to create a namespace.

  • curl --request POST   --url 'https://us-south.functions.cloud.ibm.com/api/v1/namespaces'   --header 'accept: application/json'   --header 'authorization: <IAM_token>'   --data '{"description":"string","name":"string","resource_group_id":"string","resource_plan_id":"string"}'

Response

Successful response when creating or getting a namespace.

Status Code

  • Success

  • Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • Forbidden. This action requires the Editor role for the namespace. Contact your account owner to change your IAM access policies.

  • Internal Server Error. IBM Cloud Functions is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses
  • {
      "id": "12345678-1234-abcd-1234-123456789abc",
      "name": "My Namespace",
      "description": "namespace for project A",
      "location": "us-south",
      "resource_plan_id": "functions-base-plan",
      "service_id": "ServiceID-12345678-1234-abcd-1234-123456789abc",
      "crn": "crn:v1:bluemix:public:functions:us-south:a/1a22bb3c44dd1a22bb3c44dd1a22:12345678-1234-abcd-1234-123456789abc"
    }

Get namespace information

Get detailed information about one IBM Cloud Functions namespace.

GET /namespaces/{id}

Request

Custom Headers

  • Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Path Parameters

  • The unique ID of the namespace to get information about. To list all namespace IDs, use the GET /namespaces call.

  • curl --request GET   --url 'https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{id}'   --header 'accept: application/json'   --header 'authorization: <IAM_token>'

Response

Successful response when creating or getting a namespace.

Status Code

  • Success

  • Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • Forbidden. This action requires the Reader, Writer, or Manager role for the namespace. Contact your account owner to change your IAM access policies.

  • Not found. Check that the namespace ID is correct and try again.

  • Internal Server Error. IBM Cloud Functions is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses
  • {
      "classic_spaceguid": "12345678-1234-abcd-1234-123456789abc",
      "classic_type": 1,
      "description": "new namespace for packages X, Y, and Z.",
      "id": "12345678-1234-abcd-1234-123456789abc",
      "location": "us-south",
      "crn": "crn:v1:functions:us-south:a/1a22bb3c44dd1a22bb3c44dd1a22:12345678-1234-abcd-1234-123456789abc::",
      "name": "mynamespace",
      "resource_group_id": "1a22bb3c44dd1a22bb3c44dd1a22",
      "resource_plan_id": "functions-base-plan",
      "service_id": "ServiceId-12345678-1234-abcd-1234-123456789abc"
    }

Delete a namespace

Delete an IBM Cloud Functions namespace. Warning - All Functions entities, such as actions, tiggers, rules, and packages, within this namespace are also deleted.

DELETE /namespaces/{id}

Request

Custom Headers

  • Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Path Parameters

  • The unique ID of the namespace to delete. To list all namespace IDs, use the GET /namespaces call.

  • curl --request DELETE   --url 'https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/actions/{actionName}'   --header 'accept: application/json'   --header 'authorization: <IAM_token>'

Response

Successful response when deleting a namespace

Status Code

  • Success

  • Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • Forbidden. This action requires the Manager role for the namespace. Contact your account owner to change your IAM access policies.

  • Not found. Check that the namespace ID is correct and try again.

  • Internal Server Error. IBM Cloud Functions is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses
  • {
      "id": "12345678-1234-abcd-1234-123456789abc"
    }

Update a namespace

Update an IBM Cloud Functions namespace. This API is NOT supported for classic namespaces. This API supports only IAM-based namespaces.

PATCH /namespaces/{id}

Request

Custom Headers

  • Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Path Parameters

  • The unique ID of the namespace to update. To list all namespace IDs, use the GET /namespaces call.

The request body to update the namespace

  • curl --request PATCH   --url 'https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{id}'   --header 'accept: application/json'   --header 'authorization: <IAM_token>'   --data '{"description":"string","name":"string"}'

Response

Successful response when creating or getting a namespace.

Status Code

  • Success

  • Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • Forbidden. This action requires the Manager role for the namespace. Contact your account owner to change your IAM access policies.

  • Not found. Check that the namespace ID is correct and try again.

  • Internal Server Error. IBM Cloud Functions is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses
  • {
      "description": "My updated description of this namespace.",
      "name": "myupdatednamespace"
    }

Update a namespace API key

Update an IBM Cloud Functions namespace API key. This API is NOT supported for classic namespaces. This API supports only IAM-based namespaces.

PATCH /namespaces/{id}/apikey

Request

Custom Headers

  • Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Path Parameters

  • The ID of the namespace to update the API key.

The request body to update the namespace API key. The request body is optional. However, if specified, it must contain a service ID that is used to generate the API key. If the service ID is specified, it replaces the existing service ID for the namespace and is used for further actions. Note that policies that are associated with the previous service ID are not automatically transferred to the new service ID. Limitation - While any new triggers use the new API key, any existing triggers will continue to use the old API key. If the old service ID and/or API key is deleted, or policies are removed, old triggers will fail as not being authorized. Therefore, consider recreating your triggers after updating the API key.

  • curl --request PATCH   --url 'https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{id}/apikey'   --header 'accept: application/json'   --header 'authorization: <IAM_token>'   --data '{"service_id":"string"}'

Response

Successful response when creating or getting a namespace.

Status Code

  • Success

  • Bad request. Check that the information you entered in the payload is complete and formatted correctly in JSON..

  • Unauthorized. The IAM token is invalid or expired. To retrieve your IAM token, run ibmcloud login and then ibmcloud iam oauth-tokens.

  • Unauthorized access. Check that you have the correct access credentials and permissions..

  • Not found. Check that the namespace ID is correct and try your request again..

  • Internal Server Error. IBM Cloud Functions is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support.

Example responses
  • {
      "id": "12345678-1234-abcd-1234-123456789abc",
      "name": "My Namespace",
      "description": "namespace for project A",
      "location": "us-south",
      "resource_plan_id": "functions-base-plan",
      "service_id": "ServiceID-12345678-1234-abcd-1234-123456789abc",
      "crn": "crn:v1:bluemix:public:functions:us-south:a/1a22bb3c44dd1a22bb3c44dd1a22:12345678-1234-abcd-1234-123456789abc"
    }

Get all actions

List all actions, web actions, and action sequences in a namespace. An action is a piece of code that performs one specific task. For more information, see the Cloud Functions actions documentation.

GET /namespaces/{namespace}/actions

Request

Custom Headers

  • Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Path Parameters

  • ID of the namespace that the action is in. Find all namespace IDs by running ibmcloud fn namespace list or by using get all namespaces.

Query Parameters

  • Number of actions to include in the result.

  • Number of actions to skip in the result.

  • curl --request GET --url 'https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/actions?limit=0&skip=0'
      --header 'accept: application/json'  --header 'authorization: <IAM_token>'
  • HttpResponse<String> response = Unirest.get("https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/actions?limit=0&skip=0")
      .header("accept", "application/json")
      .asString();
  • var options = {
      "method": "GET",
      "hostname": "us-south.functions.cloud.ibm.com",
      "port": null,
      "path": "/api/v1/namespaces/{namespace}/actions?limit=0&skip=0",
      "headers": {
        "accept": "application/json"
      }
    };
    
    var req = http.request(options, function (res) {
      var chunks = [];
    
      res.on("data", function (chunk) {
        chunks.push(chunk);
      });
    
      res.on("end", function () {
        var body = Buffer.concat(chunks);
        console.log(body.toString());
      });
    });
    
    req.end();
    
  • import http.client
    
    conn = http.client.HTTPSConnection("us-south.functions.cloud.ibm.com")
    
    [object Object]
    conn.request("GET", "/api/v1/namespaces/{namespace}/actions?limit=0&skip=0", headers=headers)
    
    res = conn.getresponse()
    data = res.read()
    
    print(data.decode("utf-8"))
    

Response

Status Code

  • OK

  • Unauthorized

  • Forbidden

  • Internal Server Error

Example responses
  • [
      {
        "name": "myaction",
        "publish": false,
        "annotations": [
          {
            "key": "final",
            "value": true
          },
          {
            "key": "web-export",
            "value": true
          }
        ],
        "version": "0.0.1",
        "updated": 1531167810568,
        "exec": {
          "code": "Javascript",
          "image": null,
          "init": null,
          "kind": "nodejs:6",
          "binary": false,
          "components": null
        },
        "limits": {
          "timeout": 60000,
          "memory": 256,
          "logs": 10
        },
        "namespace": "BobsOrg_dev"
      }
    ]
  • {
      "error": "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.",
      "code": 401
    }
  • {
      "code": 403,
      "error": "The supplied authentication is not authorized to access '{namespace}'."
    }
  • {
      "code": 500,
      "error": "IBM Cloud Functions is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support. If you still encounter this problem, note the incident ID and contact the IBM Cloud support."
    }

Get action information

Get information on a specified action, web action, or action sequence.

GET /namespaces/{namespace}/actions/{actionName}

Request

Custom Headers

  • Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Path Parameters

  • The name of the entity you want to get information for. To list all actions in a namespace, use the GET /namespaces/{namespace}/actions call.

  • ID of the namespace that the entity is in.

  • curl --request GET   --url https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/actions/{actionName}'   --header 'accept: application/json'   --header 'authorization: <IAM_token>'
  • HttpResponse<String> response = Unirest.get("https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/actions/{actionName}")
      .header("accept", "application/json")
      .asString();
  • var http = require("https");
    
    var options = {
      "method": "GET",
      "hostname": "us-south.functions.cloud.ibm.com",
      "port": null,
      "path": "/api/v1/namespaces/{namespace}/actions/{actionName}",
      "headers": {
        "accept": "application/json"
        "authorization": "<IAM token>"
      }
    };
    
    var req = http.request(options, function (res) {
      var chunks = [];
      
      res.on("data", function (chunk) {
        chunks.push(chunk);
      });
      
      res.on("end", function () {
        var body = Buffer.concat(chunks);
        console.log(body.toString());
      });
    });
    
    req.end();
  • import http.client
    
    conn = http.client.HTTPSConnection("us-south.functions.cloud.ibm.com")
    
    headers = { 'accept': "application/json" }
    
    conn.request("GET", "/api/v1/namespaces/{namespace}/actions/{actionName}", headers=headers)
    
    res = conn.getresponse()
    data = res.read()
    
    print(data.decode("utf-8"))

Response

Status Code

  • Returned action

  • Unauthorized

  • Not Found

  • Internal Server Error

Example responses
  • {
      "name": "myaction",
      "publish": false,
      "annotations": [
        {
          "key": "final",
          "value": true
        },
        {
          "key": "web-export",
          "value": true
        }
      ],
      "version": "0.0.1",
      "updated": 1531167810568,
      "exec": {
        "code": "Javascript",
        "image": null,
        "init": null,
        "kind": "nodejs:6",
        "binary": false,
        "components": null
      },
      "limits": {
        "timeout": 60000,
        "memory": 256,
        "logs": 10
      },
      "namespace": "BobsOrg_dev"
    }
  • {
      "error": "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.",
      "code": 401
    }
  • {
      "code": 404,
      "error": "The requested resource could not be found."
    }
  • {
      "code": 500,
      "error": "IBM Cloud Functions is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact the IBM Cloud support."
    }

Invoke an action

Invoke an action, web action, or action sequence. Each invocation results in an activation record.

POST /namespaces/{namespace}/actions/{actionName}

Request

Custom Headers

  • Your IBM Cloud Identity and Access Management (IAM) token. To retrieve your IAM token, run ibmcloud iam oauth-tokens.

Path Parameters

  • The name of the entity to invoke. To list all actions in a namespace, use the GET /namespaces/{namespace}/actions call.

  • ID of the namespace that the entity is in.

Query Parameters

  • Blocking or non-blocking invocation. Default is non-blocking.

    Allowable values: [true,false]

  • Return only the result of a blocking activation. Default is false.

    Allowable values: [true,false]

Parameter bindings included in the context passed to the entity

  • curl --request POST   --url 'https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/actions/{actionName}?blocking=true&result=true'   --header 'accept: application/json'   --header 'authorization: <IAM_token>'  --header 'content-type: application/json'
  • HttpResponse<String> response = Unirest.post("https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/actions/{actionName}?blocking=true&result=true'")
      .header("accept", "application/json")
      .header("authorization", "<IAM token>")
      .header("content-type", "application/json")
      .asString();
  • var http = require("https");
    
    var options = {
      "method": "POST",
      "hostname": "us-south.functions.cloud.ibm.com",
      "port": null,
      "path": "/api/v1/namespaces/{namespace}/actions/{actionName}?blocking=true&result=true",
      "headers": {
        "accept": "application/json",
        "authorization": "<IAM token>"
        "content-type": "application/json"
      }
    };
    
    var req = http.request(options, function (res) {
      var chunks = [];
    
      res.on("data", function (chunk) {
        chunks.push(chunk);
      });
    
      res.on("end", function () {
        var body = Buffer.concat(chunks);
        console.log(body.toString());
      });
    });
    
    req.end();