IBM Cloud API Docs

Introduction

Last updated: 2021-03-01

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

  • Authorization
    Required*
    string

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

Query Parameters

  • limit
    int32

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

  • skip
    int32

    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

Response Body

NamespaceList

Successful response when listing namespaces

Status Code

  • 200

    Success

  • 401

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

  • 403

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

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

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

  • Authorization
    Required*
    string

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

Request Body

NamespaceCreate

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

Response Body

Namespace

Successful response when creating or getting a namespace.

Status Code

  • 200

    Success

  • 401

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

  • 403

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

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

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

  • Authorization
    Required*
    string

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

Path Parameters

  • id
    Required*
    string

    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

Response Body

Namespace

Successful response when creating or getting a namespace.

Status Code

  • 200

    Success

  • 401

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

  • 403

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

  • 404

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

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

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

  • Authorization
    Required*
    string

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

Path Parameters

  • id
    Required*
    string

    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

Response Body

NamespaceDelete

Successful response when deleting a namespace

Status Code

  • 200

    Success

  • 401

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

  • 403

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

  • 404

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

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

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

  • Authorization
    Required*
    string

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

Path Parameters

  • id
    Required*
    string

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

Request Body

NamespaceUpdate

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

Response Body

Namespace

Successful response when creating or getting a namespace.

Status Code

  • 200

    Success

  • 401

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

  • 403

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

  • 404

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

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

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

  • Authorization
    Required*
    string

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

Path Parameters

  • id
    Required*
    string

    The ID of the namespace to update the API key.

Request Body

NamespaceUpdateAPIKey

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

Response Body

Namespace

Successful response when creating or getting a namespace.

Status Code

  • 200

    Success

  • 400

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

  • 401

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

  • 403

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

  • 404

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

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

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

  • Authorization
    Required*
    string

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

Path Parameters

  • namespace
    Required*
    string

    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

  • limit
    integer

    Number of actions to include in the result.

  • skip
    integer

    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

Response Body

Action[]

Status Code

  • 200

    OK

  • 401

    Unauthorized

  • 403

    Forbidden

  • 500

    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

  • Authorization
    Required*
    string

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

Path Parameters

  • actionName
    Required*
    string

    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.

  • namespace
    Required*
    string

    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

Response Body

Action

Status Code

  • 200

    Returned action

  • 401

    Unauthorized

  • 404

    Not Found

  • 500

    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

  • Authorization
    Required*
    string

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

Path Parameters

  • actionName
    Required*
    string

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

  • namespace
    Required*
    string

    ID of the namespace that the entity is in.

Query Parameters

  • blocking
    boolean

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

    Allowable values: [true,false]

  • result
    boolean

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

    Allowable values: [true,false]

Request Body

Parameters

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

  • 200

    Successful activation

  • 202

    Accepted activation request

  • 401

    Unauthorized

  • 404

    Not Found

  • 408

    Request Timeout

  • 500

    Internal Server Error

  • 502

    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

  • Authorization
    Required*
    string

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

Path Parameters

  • actionName
    Required*
    string

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

  • namespace
    Required*
    string

    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

  • overwrite
    boolean

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

    Allowable values: [true,false]

Request Body

ActionPut

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

Response Body

ItemId

Status Code

  • 200

    OK

  • 400

    Bad Request

  • 401

    Unauthorized

  • 409

    Conflict

  • 500

    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

  • Authorization
    Required*
    string

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

Path Parameters

  • actionName
    Required*
    string

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

  • namespace
    Required*
    string

    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

  • 200

    OK

  • 401

    Unauthorized

  • 404

    Forbidden

  • 500

    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

  • Authorization
    Required*
    string

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

Path Parameters

  • namespace
    Required*
    string

    Namespace that you want to see activation records for.

Query Parameters

  • docs
    boolean

    Whether to include the full description for each activation record.

  • limit
    integer

    Number of records to include in the result.

  • name
    string

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

  • since
    integer

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

  • skip
    integer

    Number of records to skip in the result.

  • upto
    integer

    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

Response Body

ActivationID[]

Status Code

  • 200

    Activations response

  • 401

    Unauthorized

  • 500

    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

  • Authorization
    Required*
    string

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

Path Parameters

  • activationid
    Required*
    string

    Activation record ID. To see all activation record IDs for a namespace, use the GET /namespaces/{namespace}/activations call.

  • namespace
    Required*
    string

    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

Response Body

Activation

Status Code

  • 200

    Return output

  • 401

    Unauthorized

  • 404

    Not Found

  • 500

    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

  • Authorization
    Required*
    string

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

Path Parameters

  • activationid
    Required*
    string

    ID of the activation record

  • namespace
    Required*
    string

    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

Response Body

ActivationLogs

Status Code

  • 200

    Return output

  • 401

    Unauthorized

  • 404

    Not Found

  • 500

    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

  • Authorization
    Required*
    string

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

Path Parameters

  • activationid
    Required*
    string

    ID for the activation record

  • namespace
    Required*
    string

    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

Response Body

ActivationResponse

Status Code

  • 200

    Return output

  • 401

    Unauthorized

  • 404

    Not Found

  • 500

    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

  • Authorization
    Required*
    string

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

Path Parameters

  • namespace
    Required*
    string

    ID of the namespace that the package is in.

Query Parameters

  • limit
    integer

    Number of packages to include in the result.

  • public
    boolean

    Include publicly shared packages in the result.

  • skip
    integer

    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

Response Body

Package[]

Status Code

  • 200

    Packages response

  • 401

    Unauthorized

  • 500

    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

  • Authorization
    Required*
    string

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

Path Parameters

  • namespace
    Required*
    string

    ID of the namespace that the package is in

  • packageName
    Required*
    string

    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

Response Body

Package

Status Code

  • 200

    Returned package

  • 401

    Unauthorized

  • 404

    Not Found

  • 500

    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

  • Authorization
    Required*
    string

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

Path Parameters

  • namespace
    Required*
    string

    ID of the namespace that the package is in

  • packageName
    Required*
    string

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

Query Parameters

  • overwrite
    string

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

    Allowable values: [true,false]

Request Body

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

Response Body

ItemId

Status Code

  • 200

    OK

  • 400

    Bad Request

  • 401

    Unauthorized

  • 409

    Conflict

  • 500

    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

  • Authorization
    Required*
    string

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

Path Parameters

  • namespace
    Required*
    string

    ID of the namespace that the package is in

  • packageName
    Required*
    string

    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

  • 200

    OK

  • 401

    Unauthorized

  • 404

    Not Found

  • 500

    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

  • Authorization
    Required*
    string

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

Path Parameters

  • namespace
    Required*
    string

    Namespace that you want to list triggers for

Query Parameters

  • limit
    integer

    Number of triggers to include in the result

  • skip
    integer

    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

Response Body

TriggerShort[]

Status Code

  • 200

    Triggers response

  • 401

    Unauthorized

  • 500

    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

  • Authorization
    Required*
    string

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

Path Parameters

  • namespace
    Required*
    string

    ID of the namespace that the trigger is in

  • triggerName
    Required*
    string

    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

Response Body

Trigger

Status Code

  • 200

    Returned trigger

  • 401

    Unauthorized

  • 404

    Not Found

  • 500

    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

  • Authorization
    Required*
    string

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

Path Parameters

  • namespace
    Required*
    string

    ID of the namespace that the trigger is in

  • triggerName
    Required*
    string

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

Request Body

Parameters

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

  • 200

    OK

  • 401

    Unauthorized

  • 404

    Not Found

  • 408

    Request Timeout

  • 500

    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

  • Authorization
    Required*
    string

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

Path Parameters

  • namespace
    Required*
    string

    ID of the namespace that the trigger is in

  • triggerName
    Required*
    string

    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

  • overwrite
    string

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

    Allowable values: [true,false]

Request Body

TriggerPut

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

  • 200

    OK

  • 400

    Bad Request

  • 401

    Unauthorized

  • 409

    Conflict

  • 500

    Internal Server Error

  • 502

    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

  • Authorization
    Required*
    string

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

Path Parameters

  • namespace
    Required*
    string

    ID of the namespace that the trigger is in

  • triggerName
    Required*
    string

    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

  • 200

    OK

  • 401

    Unauthorized

  • 404

    Not Found

  • 500

    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

  • namespace
    Required*
    string

    ID of the namespace that the rule is in

Query Parameters

  • limit
    integer

    Number of rules to include in the result

  • skip
    integer

    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

Response Body

Rule[]

Status Code

  • 200

    Rules response

  • 401

    Unauthorized

  • 500

    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

  • Authorization
    Required*
    string

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

Path Parameters

  • namespace
    Required*
    string

    ID of the namespace that the rule is in

  • ruleName
    Required*
    string

    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

Response Body

Rule

Status Code

  • 200

    Returned rule

  • 401

    Unauthorized

  • 404

    Not Found

  • 500

    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

  • Authorization
    Required*
    string

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

Path Parameters

  • namespace
    Required*
    string

    ID of the namespace that the rule is in

  • ruleName
    Required*
    string

    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

  • status
    Required*
    string

    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

  • 200

    OK

  • 202

    Accepted

  • 400

    Bad Request

  • 401

    Unauthorized

  • 500

    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

  • Authorization
    Required*
    string

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

Path Parameters

  • namespace
    Required*
    string

    ID of the namespace that the rule is in

  • ruleName
    Required*
    string

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

Query Parameters

  • overwrite
    string

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

    Allowable values: [true,false]

Request Body

RulePut

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

  • 200

    OK

  • 400

    Bad Request

  • 401

    Unauthorized

  • 409

    Conflict

  • 500

    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

  • Authorization
    Required*
    string

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

Path Parameters

  • namespace
    Required*
    string

    ID of the namespace that the rule is in

  • ruleName
    Required*
    string

    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

  • 200

    OK

  • 401

    Unauthorized

  • 404

    Not Found

  • 500

    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."
}
id=curlclassName=tab-item-selected