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();
  • import http.client
    
    conn = http.client.HTTPSConnection("us-south.functions.cloud.ibm.com")
    
    headers = {
        'accept': "application/json",
        'authorization': "<IAM token>",
        'content-type': "application/json"
        }
    
    conn.request("POST", "/api/v1/namespaces/{namespace}/actions/{actionName}?blocking=true&result=true", headers=headers)
    
    res = conn.getresponse()
    data = res.read()
    
    print(data.decode("utf-8"))

Response

Status Code

  • Successful activation

  • Accepted activation request

  • Unauthorized

  • Not Found

  • Request Timeout

  • Internal Server Error

  • Bad Gateway

Example responses
  • {
      "activationId": "014a07f8a66847098a07f8a668870997"
    }
  • {
      "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": 408,
      "error": "The connection to the server timed out. Wait a few minutes, then try again."
    }
  • {
      "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."
    }
  • {
      "code": 502,
      "error": "A call forwarding component received an invalid response while working as a gateway to handle the response."
    }

Create or update an action

Create or update an action, web action, or action sequence.

PUT /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 update. To list all actions in a namespace, use the GET /namespaces/{namespace}/actions call.

  • 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

  • Enter true to overwrite the entity if it exists. The default is false.

    Allowable values: [true,false]

To create a web action, enter the proper web annotations. For a list of annotations for web actions, see the documentation. To create an action sequence, enter sequence as the kind and enter the names of the Actions in the desired order as the components.

  • curl --request PUT   --url 'https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/actions/{actionName}?overwrite=true'   --header 'accept: application/json'   --header 'authorization: <IAM_token>'  --header 'content-type: application/json'   --data '{"annotations":[{"key":"exec","value":"nodejs:8"},{"key":"web-export","value":true}],"exec":{"kind":"nodejs:8","code":"function main(params) { return {payload:params.message}}"},"parameters":[{"key":"message","value":"Hello World"}]}'
  • var http = require("https");
    
    var options = {
      "method": "PUT",
      "hostname": "us-south.functions.cloud.ibm.com",
      "port": null,
      "path": "/api/v1/namespaces/{namespace}/actions/{actionName}?overwrite=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.write(JSON.stringify({ annotations: 
         items: 
          { properties: 
             { key: 'string',
               value: { description: 'Any JSON value', type: 'object' } },
            type: 'object' },
         properties: 
          { key: 'string',
            value: { description: 'Any JSON value', type: 'object' } },
         type: 'object' },
      exec: 
         properties: 
          { binary: true,
            code: 'string',
            components: 'string',
            image: 'string',
            init: 'string',
            kind: '"nodejs:8"' },
         type: 'object' },
      limits: 
         properties: { logs: 0, memory: 0, timeout: 0 },
         type: 'object' },
      parameters: 
         items: 
          { properties: 
             { key: 'string',
               value: { description: 'Any JSON value', type: 'object' } },
            type: 'object' },
         properties: 
          { key: 'string',
            value: { description: 'Any JSON value', type: 'object' } },
         type: 'object' },
      publish: true,
      version: 'string' }));
    req.end();
  • import http.client
    
    conn = http.client.HTTPSConnection("us-south.functions.cloud.ibm.com")
    
    payload = "{"annotations":{"items":{"properties":{"key":"string","value":{"type":"object"}},"type":"object"},"properties":{"key":"string","value":{"type":"object"}},"type":"object"},"exec":{"properties":{"binary":true,"code":"string","components":"string","image":"string","init":"string","kind":"\"nodejs:8\""},"type":"object"},"limits":{"properties":{"logs":0,"memory":0,"timeout":0},"type":"object"},"parameters":{"items":{"properties":{"key":"string","value":{"type":"object"}},"type":"object"},"properties":{"key":"string","value":{"type":"object"}},"type":"object"},"publish":true,"version":"string"}"
    
    headers = {
        'accept': "application/json",
        'authorization': "<IAM token>",
        'content-type': "application/json"
        }
    
    conn.request("PUT", "/api/v1/namespaces/{namespace}/actions/{actionName}?overwrite=true", payload, headers)
    
    res = conn.getresponse()
    data = res.read()
    
    print(data.decode("utf-8"))

Response

Status Code

  • OK

  • Bad Request

  • Unauthorized

  • Conflict

  • Internal Server Error

Example responses
  • {
      "activationId": "014a07f8a66847098a07f8a668870997"
    }
  • {
      "code": 400,
      "error": "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."
    }
  • {
      "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": 409,
      "error": "The entity is already in the requested state."
    }
  • {
      "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."
    }

Delete an action

Delete an action, web action, or action sequence.

DELETE /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 delete. To list all actions in a namespace, use the GET /namespaces/{namespace}/actions call.

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

  • 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>'
     --header 'content-type: application/json'
  • HttpResponse<String> response = Unirest.delete("https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/actions/{actionName}")  .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",
      "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();
    
  • import http.client
    
    conn = http.client.HTTPSConnection("us-south.functions.cloud.ibm.com")
    
    headers = {
        'accept': "application/json",
        'authorization': "<IAM token>",
        'content-type': "application/json"
        }
    
    conn.request("POST", "/api/v1/namespaces/{namespace}/actions/{actionName}?blocking=true", headers=headers)
    
    res = conn.getresponse()
    data = res.read()
    
    print(data.decode("utf-8"))
    

Response

Status Code

  • OK

  • Unauthorized

  • Forbidden

  • Internal Server Error

Example responses
  • {
      "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."
    }

Get activation IDs

List the IDs for all activation records in a namespace. Whenever an action is invoked, an activation record is created for that invocation. For more information, see the Cloud Functions activations documentation.

GET /namespaces/{namespace}/activations

Request

Custom Headers

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

Path Parameters

  • Namespace that you want to see activation records for.

Query Parameters

  • Whether to include the full description for each activation record.

  • Number of records to include in the result.

  • To see activation records for only one entity, enter the entity name.

  • Only include records later than this timestamp (measured in milliseconds since Thu, 01 Jan 1970)

  • Number of records to skip in the result.

  • Only include records earlier than this timestamp (measured in milliseconds since Thu, 01 Jan 1970)

  • curl --request GET   --url 'https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/activations?docs=true&limit=0&name=string&since=0&skip=0&upto=0'   --header 'authorization: <IAM_token>'   --header 'accept: application/json'
  • HttpResponse<String> response = Unirest.get("https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/activations?docs=true&limit=0&name=string&since=0&skip=0&upto=0")
      .header("accept", "application/json")
      .header("authorization", "<IAM token>")
      .asString();
  • var http = require("https");
    
    var options = {
      "method": "GET",
      "hostname": "us-south.functions.cloud.ibm.com",
      "port": null,
      "path": "/api/v1/namespaces/{namespace}/activations?docs=true&limit=0&name=string&since=0&skip=0&upto=0",
      "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}/activations?docs=true&limit=0&name=string&since=0&skip=0&upto=0", headers=headers)
    
    res = conn.getresponse()
    data = res.read()
    
    print(data.decode("utf-8"))

Response

Status Code

  • Activations response

  • Unauthorized

  • Internal Server Error

Example responses
  • {
      "name": "myaction",
      "statusCode": 1,
      "duration": 76,
      "annotations": [
        {
          "key": "path",
          "value": "BobsOrg_dev/myaction"
        },
        {
          "key": "waitTime",
          "value": 98
        },
        {
          "key": "kind",
          "value": "nodejs:6"
        },
        {
          "key": "initTime",
          "value": 58
        }
      ],
      "activationId": "014a07f8a66847098a07f8a668870997",
      "version": "0.0.1",
      "updated": 1531167810568,
      "namespace": "BobsOrg_dev",
      "publish": false,
      "end": 1531433506771,
      "start": 1531433506695
    }
  • {
      "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": 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."
    }

Get activation information

Get information about an activation record that resulted from an action invocation.

GET /namespaces/{namespace}/activations/{activationid}

Request

Custom Headers

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

Path Parameters

  • Activation record ID. To see all activation record IDs for a namespace, use the GET /namespaces/{namespace}/activations 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}/activations/{activationid}   --header 'accept: application/json'   --header 'authorization: <IAM_token>'
  • HttpResponse<String> response = Unirest.get("https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/activations/{activationid}")
    .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}/activations/{activationid}",
      "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}/activations/{activationid}", headers=headers)
    
    res = conn.getresponse()
    data = res.read()
    
    print(data.decode("utf-8"))

Response

Status Code

  • Return output

  • Unauthorized

  • Not Found

  • Internal Server Error

Example responses
  • {
      "duration": 76,
      "name": "myaction",
      "subject": "bob@email.com",
      "activationId": "014a07f8a66847098a07f8a668870997",
      "publish": false,
      "annotations": [
        {
          "key": "path",
          "value": "BobsOrg_dev/myaction"
        },
        {
          "key": "waitTime",
          "value": 98
        },
        {
          "key": "kind",
          "value": "nodejs:6"
        },
        {
          "key": "initTime",
          "value": 58
        }
      ],
      "version": "0.0.1",
      "response": {
        "result": {
          "error": {
            "error": "no name or comment"
          }
        },
        "success": false,
        "status": "application error"
      },
      "end": 1531433506771,
      "logs": "",
      "start": 1531433506695,
      "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."
    }

Get activation logs

Get the logs for an activation.

GET /namespaces/{namespace}/activations/{activationid}/logs

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

  • ID of the namespace that the entity is in

  • curl --request GET   --url https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/activations/{activationid}/logs   --header 'accept: application/json'   --header 'authorization: <IAM_token>'
  • HttpResponse<String> response = Unirest.get("https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/activations/{activationid}/logs")
    .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}/activations/{activationid}/logs",
      "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}/activations/{activationid}/logs", headers=headers)
    
    res = conn.getresponse()
    data = res.read()
    
    print(data.decode("utf-8"))

Response

Status Code

  • Return output

  • Unauthorized

  • Not Found

  • Internal Server Error

Example responses
  • {
      "logs": ""
    }
  • {
      "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."
    }

Get an activation result

Get the results of an activation.

GET /namespaces/{namespace}/activations/{activationid}/result

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 for the activation record

  • ID of the namespace that the entity is in

  • curl --request GET   --url https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/activations/{activationid}/result'   --header 'accept: application/json'  --header 'authorization: <IAM_token>'
  • HttpResponse<String> response = Unirest.get("https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/activations/{activationid}/result")
      .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}/activations/{activationid}/result",
      "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}/activations/{activationid}/result", headers=headers)
    
    res = conn.getresponse()
    data = res.read()
    
    print(data.decode("utf-8"))

Response

Status Code

  • Return output

  • Unauthorized

  • Not Found

  • Internal Server Error

Example responses
  • {
      "result": {
        "payload": "Hello, Fred!"
      },
      "success": true,
      "status": "success"
    }
  • {
      "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."
    }

Get all packages

List all packages in a namespace. Packages are bundles of related actions and feeds. Pre-installed packages are available in the /whisk.system namespace. For more information, see the Cloud Functions packages documentation.

GET /namespaces/{namespace}/packages

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 package is in.

Query Parameters

  • Number of packages to include in the result.

  • Include publicly shared packages in the result.

  • Number of packages to skip in the result.

  • curl --request GET   --url 'https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/packages?limit=0&public=true&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}/packages?limit=0&public=true&skip=0")
    .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}/packages?limit=0&public=true&skip=0",
      "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}/packages?limit=0&public=true&skip=0", headers=headers)
    
    res = conn.getresponse()
    data = res.read()
    
    print(data.decode("utf-8"))

Response

Status Code

  • Packages response

  • Unauthorized

  • Internal Server Error

Example responses
  • {
      "name": "assistant-v1",
      "binding": false,
      "publish": false,
      "annotations": "",
      "version": "0.0.1",
      "updated": 1530812063289,
      "namespace": "BobsOrg_dev",
      "actions": [
        "myAction1",
        "myAction2"
      ],
      "feeds": [
        "myFeed"
      ]
    }
  • {
      "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": 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."
    }

Get package information

Get information on a specified package.

GET /namespaces/{namespace}/packages/{packageName}

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 package is in

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

  • curl --request GET   --url https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/packages/{packageName}'   --header 'accept: application/json'  --header 'authorization: <IAM_token>'
  • HttpResponse<String> response = Unirest.get("https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/packages/{packageName}")
    .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}/packages/{packageName}",
      "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}/packages/{packageName}", headers=headers)
    
    res = conn.getresponse()
    data = res.read()
    
    print(data.decode("utf-8"))

Response

Status Code

  • Returned package

  • Unauthorized

  • Not Found

  • Internal Server Error

Example responses
  • {
      "name": "assistant-v1",
      "binding": false,
      "publish": false,
      "annotations": "",
      "version": "0.0.1",
      "updated": 1530812063289,
      "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."
    }

Create or update a package

Create or update a package. This can include optionally creating a package binding or setting default package-level parameters.

PUT /namespaces/{namespace}/packages/{packageName}

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 package is in

  • The name of the package to update. To list all packages in a namespace, use the GET /namespaces/{namespace}/packages call.

Query Parameters

  • Enter true to overwrite the entity if it exists. The default is false.

    Allowable values: [true,false]

  • curl --request PUT   --url 'https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/packages/{packageName}?overwrite=string'   --header 'accept: application/json'   --header 'content-type: application/json'   --header 'authorization: <IAM_token>'   --data '{"annotations":[{"key":"string","value":{"type":"object"}}],"binding":{"properties":{"name":"string","namespace":"string"},"type":"object"},"parameters":[{"key":"string","value":{"type":"object"}}],"publish":true,"version":"string"}'
  • HttpResponse<String> response = Unirest.put("https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/packages/{packageName}?overwrite=string")
    .header("accept", "application/json")
    .header("authorization", "<IAM token>")
    .header("content-type", "application/json")
    .body("{"annotations":[{"key":"string","value":{"type":"object"}}],"binding":{"properties":{"name":"string","namespace":"string"},"type":"object"},"parameters":[{"key":"string","value":{"type":"object"}}],"publish":true,"version":"string"}")
    .asString();
  • var http = require("https");
    
    var options = {
      "method": "PUT",
      "hostname": "us-south.functions.cloud.ibm.com",
      "port": null,
      "path": "/api/v1/namespaces/{namespace}/packages/{packageName}?overwrite=string",
      "headers": {
        "accept": "application/json",
        "content-type": "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.write(JSON.stringify({ annotations: 
       [ { key: 'string',
           value: 'object' } ],
      binding: 
       { properties: { name: 'string', namespace: 'string' },
         type: 'object' },
      parameters: 
       [ { key: 'string',
           value: 'object' } ],
      publish: true,
      version: 'string' }));
    req.end();
    
  • import http.client
    
    conn = http.client.HTTPSConnection("us-south.functions.cloud.ibm.com")
    
    payload = "{"annotations":[{"key":"string","value":{"type":"object"}}],"binding":{"properties":{"name":"string","namespace":"string"},"type":"object"},"parameters":[{"key":"string","value":{"type":"object"}}],"publish":true,"version":"string"}"
    
    headers = {
        'accept': "application/json",
        'authorization': "<IAM token>",
        'content-type': "application/json"
        }
    
    conn.request("PUT", "/api/v1/namespaces/{namespace}/packages/{packageName}?overwrite=string", payload, headers)
    
    res = conn.getresponse()
    data = res.read()
    
    print(data.decode("utf-8"))

Response

Status Code

  • OK

  • Bad Request

  • Unauthorized

  • Conflict

  • Internal Server Error

Example responses
  • {
      "activationId": "014a07f8a66847098a07f8a668870997"
    }
  • {
      "code": 400,
      "error": "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."
    }
  • {
      "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": 409,
      "error": "The entity is already in the requested state."
    }
  • {
      "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."
    }

Delete a package

Delete a package.

DELETE /namespaces/{namespace}/packages/{packageName}

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 package is in

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

  • curl --request DELETE \n  --url https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/packages/{packageName}'   --header 'accept: application/json'   --header 'content-type: application/json'   --header 'authorization: <IAM_token>'
  • HttpResponse<String> response = Unirest.delete("https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/packages/{packageName}")
    .header("accept", "application/json")
    .header("content-type", "application/json")
    .header("authorization", "<IAM token>")
    .asString();
  • var http = require("https");
    
    var options = {
      "method": "DELETE",
      "hostname": "us-south.functions.cloud.ibm.com",
      "port": null,
      "path": "/api/v1/namespaces/{namespace}/packages/{packageName}",
      "headers": {
        "accept": "application/json",
        "content-type": "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",
        'content-type': "application/json"
        'authorization': "<IAM token>",
        }
    
    conn.request("DELETE", "/api/v1/namespaces/{namespace}/packages/{packageName}", headers=headers)
    
    res = conn.getresponse()
    data = res.read()
    
    print(data.decode("utf-8"))

Response

Status Code

  • OK

  • Unauthorized

  • Not Found

  • Internal Server Error

Example responses
  • {
      "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."
    }

Get all triggers

List all triggers in a namespace. Triggers are a named channel for a class of events. A trigger is a declaration that you want to react to a certain type of event, whether from a user or by an event source. For more information, see the Cloud Functions triggers documentation.

GET /namespaces/{namespace}/triggers

Request

Custom Headers

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

Path Parameters

  • Namespace that you want to list triggers for

Query Parameters

  • Number of triggers to include in the result

  • Number of triggers to skip in the result

  • curl --request GET   --url 'https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/triggers?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}/triggers?limit=0&skip=0")
      .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}/triggers?limit=0&skip=0",
      "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}/triggers?limit=0&skip=0", headers=headers)
    
    res = conn.getresponse()
    data = res.read()
    
    print(data.decode("utf-8"))

Response

Status Code

  • Triggers response

  • Unauthorized

  • Internal Server Error

Example responses
  • {
      "name": "myTrigger",
      "publish": false,
      "annotations": "",
      "version": "0.0.1",
      "updated": 1532446998302,
      "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": 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."
    }

Get trigger information

Get information on a specified trigger.

GET /namespaces/{namespace}/triggers/{triggerName}

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 trigger is in

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

  • curl --request GET   --url 'https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/{triggerName}'   --header 'accept: application/json'   --header 'authorization: <IAM_token>'
  • HttpResponse<String> response = Unirest.get("https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/triggers/{triggerName}")
      .header("accept", "application/json")
      .header("authorization", "<IAM token>")
      .asString();
  • var http = require("https");
    
    var options = {
      "method": "GET",
      "hostname": "us-south.functions.cloud.ibm.com",
      "port": null,
      "path": "/api/v1/namespaces/{namespace}/triggers/{triggerName}",
      "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}/triggers/{triggerName}", headers=headers)
    
    res = conn.getresponse()
    data = res.read()
    
    print(data.decode("utf-8"))

Response

Status Code

  • Returned trigger

  • Unauthorized

  • Not Found

  • Internal Server Error

Example responses
  • {
      "name": "myTrigger",
      "publish": false,
      "annotations": "",
      "version": "0.0.1",
      "rules": {
        "path/ruleName": {
          "action": {
            "path": "BobsOrg_dev",
            "name": "myRule"
          },
          "status": "active"
        }
      },
      "parameters": "",
      "limits": "",
      "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."
    }

Fire a trigger

Manually fire a trigger. If the trigger is associated with a rule, the rule will invoke the associated action.

POST /namespaces/{namespace}/triggers/{triggerName}

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 trigger is in

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

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}/{triggerName}'   --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}/triggers/{triggerName}")
      .header("accept", "application/json")
      .header("content-type", "application/json")
      .header("authorization", "<IAM token>")
      .asString();
  • var http = require("https");
    
    var options = {
      "method": "POST",
      "hostname": "us-south.functions.cloud.ibm.com",
      "port": null,
      "path": "/api/v1/namespaces/{namespace}/triggers/{triggerName}",
      "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();
  • import http.client
    
    conn = http.client.HTTPSConnection("us-south.functions.cloud.ibm.com")
    
    headers = {
        'accept': "application/json",
        'authorization': "<IAM token>",
        'content-type': "application/json"
        }
    
    conn.request("POST", "/api/v1/namespaces/{namespace}/triggers/{triggerName}", headers=headers)
    
    res = conn.getresponse()
    data = res.read()
    
    print(data.decode("utf-8"))

Response

Status Code

  • OK

  • Unauthorized

  • Not Found

  • Request Timeout

  • Internal Server Error

Example responses
  • {
      "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": 408,
      "error": "The connection to the server timed out. Wait a few minutes, then try again."
    }
  • {
      "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."
    }

Create or update a trigger

Create or update a trigger.

PUT /namespaces/{namespace}/triggers/{triggerName}

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 trigger is in

  • The name of the trigger to create or update. To list all triggers in a namespace, use the GET /namespaces/{namespace}/triggers call.

Query Parameters

  • Set to true to overwrite any existing trigger with this name. Default is false.

    Allowable values: [true,false]

Trigger details

  • curl --request PUT   --url 'https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/triggers/{triggerName}?overwrite=string'   --header 'accept: application/json'   --header 'authorization: <IAM_token>'   --header 'content-type: application/json'   --data '{"annotations":[{"key":"string","value":{"description":"Any JSON value","type":"object"}}],"limits":"string","parameters":[{"key":"string","value":{"description":"Any JSON value","type":"object"}}],"publish":true,"version":"string"}'
  • HttpResponse<String> response = Unirest.put("https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/triggers/{triggerName}?overwrite=string")
      .header("accept", "application/json")
      .header("authorization", "<IAM token>")
      .header("content-type", "application/json")
      .body("{"annotations":[{"key":"string","value":{"description":"Any JSON value","type":"object"}}],"limits":"string","parameters":[{"key":"string","value":{"description":"Any JSON value","type":"object"}}],"publish":true,"version":"string"}")
      .asString();
  • var http = require("https");
    
    var options = {
      "method": "PUT",
      "hostname": "us-south.functions.cloud.ibm.com",
      "port": null,
      "path": "/api/v1/namespaces/{namespace}/triggers/{triggerName}?overwrite=string",
      "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.write(JSON.stringify({ annotations: 
       [ { key: 'string',
           value: { description: 'Any JSON value', type: 'object' } } ],
      limits: 'string',
      parameters: 
       [ { key: 'string',
           value: { description: 'Any JSON value', type: 'object' } } ],
      publish: true,
      version: 'string' }));
    req.end();
  • import http.client
    
    conn = http.client.HTTPSConnection("us-south.functions.cloud.ibm.com")
    
    payload = "{"annotations":[{"key":"string","value":{"description":"Any JSON value","type":"object"}}],"limits":"string","parameters":[{"key":"string","value":{"description":"Any JSON value","type":"object"}}],"publish":true,"version":"string"}"
    
    headers = {
        'accept': "application/json",
        'authorization': "<IAM token>",
        'content-type': "application/json"
        }
    
    conn.request("PUT", "/api/v1/namespaces/{namespace}/triggers/{triggerName}?overwrite=string", payload, headers)
    
    res = conn.getresponse()
    data = res.read()
    
    print(data.decode("utf-8"))

Response

Status Code

  • OK

  • Bad Request

  • Unauthorized

  • Conflict

  • Internal Server Error

  • Bad Gateway

Example responses
  • {
      "code": 400,
      "error": "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."
    }
  • {
      "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": 409,
      "error": "The entity is already in the requested state."
    }
  • {
      "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."
    }
  • {
      "code": 502,
      "error": "A call forwarding component received an invalid response while working as a gateway to handle the response."
    }

Delete a trigger

Delete a trigger.

DELETE /namespaces/{namespace}/triggers/{triggerName}

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 trigger is in

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

  • curl --request DELETE   --url 'https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/{triggerName}'   --header 'accept: application/json'   --header 'authorization: <IAM_token>'   --header 'content-type: application/json'
  • HttpResponse<String> response = Unirest.delete("https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/triggers/{triggerName}")
      .header("accept", "application/json")
      --header 'authorization: <IAM_token>' \
      .header("content-type", "application/json")
      .asString();
  • var http = require("https");
    
    var options = {
      "method": "DELETE",
      "hostname": "us-south.functions.cloud.ibm.com",
      "port": null,
      "path": "/api/v1/namespaces/{namespace}/triggers/{triggerName}",
      "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();
  • import http.client
    
    conn = http.client.HTTPSConnection("us-south.functions.cloud.ibm.com")
    
    headers = {
        'accept': "application/json",
        'authorization': "<IAM token>",
        'content-type': "application/json"
        }
    
    conn.request("DELETE", "/api/v1/namespaces/{namespace}/triggers/{triggerName}", headers=headers)
    
    res = conn.getresponse()
    data = res.read()
    
    print(data.decode("utf-8"))

Response

Status Code

  • OK

  • Unauthorized

  • Not Found

  • Internal Server Error

Example responses
  • {
      "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."
    }

Get all rules

List all rules in a namespace. A rule associates a trigger with an action. Every time the trigger fires, the rule invokes the associated action. For more information, see the Cloud Functions rules documentation.

GET /namespaces/{namespace}/rules

Request

Path Parameters

  • ID of the namespace that the rule is in

Query Parameters

  • Number of rules to include in the result

  • Number of rules to skip in the result

  • curl --request GET   --url 'https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/packages?limit=0&public=true&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}/packages?limit=0&public=true&skip=0")
      .header("accept", "application/json")
      .header("authorization", "<IAM token>")
      .asString();
  • var http = require("https");
    
    var options = {
      "method": "GET",
      "hostname": "us-south.functions.cloud.ibm.com",
      "port": null,
      "path": "/api/v1/namespaces/{namespace}/packages?limit=0&public=true&skip=0",
      "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}/packages?limit=0&public=true&skip=0", headers=headers)
    
    res = conn.getresponse()
    data = res.read()
    
    print(data.decode("utf-8"))

Response

Status Code

  • Rules response

  • Unauthorized

  • Internal Server Error

Example responses
  • {
      "name": "myRule",
      "publish": false,
      "annotations": "",
      "version": "0.0.1",
      "action": {
        "path": "BobsOrg_dev",
        "name": "myaction"
      },
      "namespace": "BobsOrg_dev",
      "trigger": {
        "path": "BobsOrg_dev",
        "name": "myTrigger"
      }
    }
  • {
      "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": 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."
    }

Get rule information

Get information on a specified rule.

GET /namespaces/{namespace}/rules/{ruleName}

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 rule is in

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

  • curl --request GET   --url 'https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/rules?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}/rules?limit=0&skip=0")
    .header("accept", "application/json")
    .header("authorization", "<IAM token>")
    .asString();
  • var http = require("https");
    
    var options = {
      "method": "GET",
      "hostname": "us-south.functions.cloud.ibm.com",
      "port": null,
      "path": "/api/v1/namespaces/{namespace}/rules?limit=0&skip=0",
      "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}/rules?limit=0&skip=0", headers=headers)
    
    res = conn.getresponse()
    data = res.read()
    
    print(data.decode("utf-8"))

Response

Status Code

  • Returned rule

  • Unauthorized

  • Not Found

  • Internal Server Error

Example responses
  • {
      "name": "myRule",
      "publish": false,
      "annotations": "",
      "version": "0.0.1",
      "action": {
        "path": "BobsOrg_dev",
        "name": "myaction"
      },
      "namespace": "BobsOrg_dev",
      "trigger": {
        "path": "BobsOrg_dev",
        "name": "myTrigger"
      }
    }
  • {
      "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."
    }

Enable or disable a rule

Enable or disable a rule.

POST /namespaces/{namespace}/rules/{ruleName}

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 rule is in

  • The name of the rule to enable or disable. To list all actions in a namespace, use the GET /namespaces/{namespace}/rules call.

Query Parameters

  • Set to active to enable or inactive to disable

    Allowable values: [inactive,active]

  • curl --request POST   --url 'https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/rules/{ruleName}?status=string'   --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}/rules/{ruleName}?status=string")
      .header("accept", "application/json")
      .header("content-type", "application/json")
      .header("authorization", "<IAM token>")
      .asString();
  • var http = require("https");
    
    var options = {
      "method": "POST",
      "hostname": "us-south.functions.cloud.ibm.com",
      "port": null,
      "path": "/api/v1/namespaces/{namespace}/rules/{ruleName}?status=string",
      "headers": {
        "accept": "application/json",
        "content-type": "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",
        'content-type': "application/json"
        'authorization': "<IAM token>",
        }
    
    conn.request("POST", "/api/v1/namespaces/{namespace}/rules/{ruleName}?status=string", headers=headers)
    
    res = conn.getresponse()
    data = res.read()
    
    print(data.decode("utf-8"))

Response

Status Code

  • OK

  • Accepted

  • Bad Request

  • Unauthorized

  • Internal Server Error

Example responses
  • {
      "code": 400,
      "error": "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."
    }
  • {
      "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": 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."
    }

Create or update a rule

Create or update a rule.

PUT /namespaces/{namespace}/rules/{ruleName}

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 rule is in

  • The name of the rule to update. To list all rules in a namespace, use the GET /namespaces/{namespace}/rules call.

Query Parameters

  • Set to true to overwrite any existing rule with this name. Default is false.

    Allowable values: [true,false]

Details of the rule

  • curl --request PUT   --url 'https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/rules/{ruleName}?overwrite=string'   --header 'accept: application/json'   --header 'authorization: <IAM_token>'   --header 'content-type: application/json'   --data '{"action":"string","publish":true,"trigger":"string","version":"string"}'
  • HttpResponse<String> response = Unirest.put("https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/rules/{ruleName}?overwrite=string")
      .header("accept", "application/json")
      .header("content-type", "application/json")
      .header("authorization", "<IAM token>")
      .body("{"action":"string","publish":true,"trigger":"string","version":"string"}")
      .asString();
  • var http = require("https");
    
    var options = {
      "method": "PUT",
      "hostname": "us-south.functions.cloud.ibm.com",
      "port": null,
      "path": "/api/v1/namespaces/{namespace}/rules/{ruleName}?overwrite=string",
      "headers": {
        "accept": "application/json",
        "content-type": "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.write(JSON.stringify({ action: 'string',
      publish: true,
      trigger: 'string',
      version: 'string' }));
    req.end();
  • import http.client
    
    conn = http.client.HTTPSConnection("us-south.functions.cloud.ibm.com")
    
    payload = "{"action":"string","publish":true,"trigger":"string","version":"string"}"
    
    headers = {
        'accept': "application/json",
        'authorization': "<IAM token>",
        'content-type': "application/json"
        }
    
    conn.request("PUT", "/api/v1/namespaces/{namespace}/rules/{ruleName}?overwrite=string", payload, headers)
    
    res = conn.getresponse()
    data = res.read()
    
    print(data.decode("utf-8"))

Response

Status Code

  • OK

  • Bad Request

  • Unauthorized

  • Conflict

  • Internal Server Error

Example responses
  • {
      "code": 400,
      "error": "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."
    }
  • {
      "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": 409,
      "error": "The entity is already in the requested state."
    }
  • {
      "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."
    }

Delete a rule

Delete a rule.

DELETE /namespaces/{namespace}/rules/{ruleName}

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 rule is in

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

  • curl --request DELETE   --url https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/rules/{ruleName}'   --header 'accept: application/json'   --header 'authorization: <IAM_token>'   --header 'content-type: application/json'
  • HttpResponse<String> response = Unirest.delete("https://us-south.functions.cloud.ibm.com/api/v1/namespaces/{namespace}/rules/{ruleName}")
      .header("accept", "application/json")
      .header("content-type", "application/json")
      .header("authorization", "<IAM token>")
      .asString();
  • var http = require("https");
    
    var options = {
      "method": "DELETE",
      "hostname": "us-south.functions.cloud.ibm.com",
      "port": null,
      "path": "/api/v1/namespaces/{namespace}/rules/{ruleName}",
      "headers": {
        "accept": "application/json",
        "content-type": "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",
        'authorization': "<IAM token>",
        'content-type': "application/json"
        }
    
    conn.request("DELETE", "/api/v1/namespaces/{namespace}/rules/{ruleName}", headers=headers)
    
    res = conn.getresponse()
    data = res.read()
    
    print(data.decode("utf-8"))

Response

Status Code

  • OK

  • Unauthorized

  • Not Found

  • Internal Server Error

Example responses
  • {
      "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."
    }