Introduction

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

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

For help getting started, 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.

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.

Methods

Get all namespaces

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

GET /namespaces
Request

Custom Headers

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

Query Parameters

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

  • The number of namespaces to skip. Default 0.

Response

Successful response when listing namespaces

Status Code

  • Success

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

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

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

Example responses

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 service instance. To see service instances, run ibmcloud resource service-instances.
  • Service ID - For each namespace, a service ID is created which is a functional id representing 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.
  • 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 on how to use apikeys. 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. Also see the action metadata documentation
  • IBM Cloud IAM policies - IAM service policies for the ServiceID to allow other services to work with the namespace service instance. To see service policies, run ibmcloud iam service-policies.
POST /namespaces
Request

Custom Headers

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

The request body to create a namespace.

Response

Successful response when creating or getting a namespace.

Status Code

  • Success

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

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

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

Example responses

Get namespace information

Get detailed information about one IBM Cloud Functions namespace.

GET /namespaces/{id}
Request

Custom Headers

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

Path Parameters

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

Response

Successful response when creating or getting a namespace.

Status Code

  • Success

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

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

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

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

Example responses

Delete a namespace

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

DELETE /namespaces/{id}
Request

Custom Headers

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

Path Parameters

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

Response

Successful response when deleting a namespace

Status Code

  • Success

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

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

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

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

Example responses

Update a namespace

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

PATCH /namespaces/{id}
Request

Custom Headers

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

Path Parameters

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

The request body to update the namespace

Response

Successful response when creating or getting a namespace.

Status Code

  • Success

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

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

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

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

Example responses

Update a namespace API key

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

PATCH /namespaces/{id}/apikey
Request

Custom Headers

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

Path Parameters

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

The request body to update the namespace API key. The request body is optional. However, if specified, it must contain a service ID that will be used to generate the API key.

Response

Successful response when creating or getting a namespace.

Status Code

  • Success

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

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

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

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

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

Example responses

Get all actions

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

GET /namespaces/{namespace}/actions
Request

Custom Headers

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

Path Parameters

  • Namespace that the action is in.

Query Parameters

  • Number of actions to include in the result.

  • Number of actions to skip in the result.

Response

Status Code

  • OK

  • Unauthorized

  • Forbidden

  • Internal Server Error

Example responses

Get action information

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

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

Custom Headers

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

Path Parameters

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

  • Namespace that the entity is in.

Response

Status Code

  • Returned action

  • Unauthorized

  • Not Found

  • Internal Server Error

Example responses

Invoke an action

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

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

Custom Headers

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

Path Parameters

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

  • Namespace that the entity is in.

Query Parameters

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

    Allowable values: [true,false]

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

    Allowable values: [true,false]

Parameter bindings included in the context passed to the entity

Response

Status Code

  • Successful activation

  • Accepted activation request

  • Unauthorized

  • Not Found

  • Request Timeout

  • Internal Server Error

Example responses

Create or update an action

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

PUT /namespaces/{namespace}/actions/{actionName}
Request

Custom Headers

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

Path Parameters

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

  • Namespace that the entity is in.

Query Parameters

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

    Allowable values: [true,false]

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

Response

Status Code

  • OK

  • Bad Request

  • Unauthorized

  • Conflict

  • Internal Server Error

Example responses

Delete an action

Delete an action, web action, or action sequence.

DELETE /namespaces/{namespace}/actions/{actionName}
Request

Custom Headers

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

Path Parameters

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

  • Namespace that the entity is in.

Response

Status Code

  • OK

  • Unauthorized

  • Forbidden

  • Internal Server Error

Example responses

Get activation IDs

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

GET /namespaces/{namespace}/activations
Request

Custom Headers

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

Path Parameters

  • Namespace that you want to see activation records for.

Query Parameters

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

  • Number of records to include in the result.

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

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

  • Number of records to skip in the result.

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

Response

Status Code

  • Activations response

  • Unauthorized

  • Internal Server Error

Example responses

Get activation information

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

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

Custom Headers

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

Path Parameters

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

  • Namespace that the entity is in.

Response

Status Code

  • Return output

  • Unauthorized

  • Not Found

  • Internal Server Error

Example responses

Get activation logs

Get the logs for an activation.

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

Custom Headers

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

Path Parameters

  • ID of the activation record

  • Namespace that the entity is in

Response

Status Code

  • Return output

  • Unauthorized

  • Not Found

  • Internal Server Error

Example responses

Get an activation result

Get the results of an activation.

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

Custom Headers

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

Path Parameters

  • ID for the activation record

  • Namespace that the entity is in

Response

Status Code

  • Return output

  • Unauthorized

  • Not Found

  • Internal Server Error

Example responses

Get all packages

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

GET /namespaces/{namespace}/packages
Request

Custom Headers

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

Path Parameters

  • Namespace that the package is in.

Query Parameters

  • Number of packages to include in the result.

  • Include publicly shared packages in the result.

  • Number of packages to skip in the result.

Response

Status Code

  • Packages response

  • Unauthorized

  • Internal Server Error

Example responses

Get package information

Get information on a specified package.

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

Custom Headers

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

Path Parameters

  • Namespace that the package is in

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

Response

Status Code

  • Returned package

  • Unauthorized

  • Not Found

  • Internal Server Error

Example responses

Create or update a package

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

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

Custom Headers

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

Path Parameters

  • Namespace that the package is in

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

Query Parameters

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

    Allowable values: [true,false]

Response

Status Code

  • OK

  • Bad Request

  • Unauthorized

  • Conflict

  • Internal Server Error

Example responses

Delete a package

Delete a package.

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

Custom Headers

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

Path Parameters

  • Namespace that the package is in

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

Response

Status Code

  • OK

  • Unauthorized

  • Not Found

  • Internal Server Error

Example responses

Get all triggers

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

GET /namespaces/{namespace}/triggers
Request

Custom Headers

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

Path Parameters

  • Namespace that you want to list triggers for

Query Parameters

  • Number of triggers to include in the result

  • Number of triggers to skip in the result

Response

Status Code

  • Triggers response

  • Unauthorized

  • Internal Server Error

Example responses

Get trigger information

Get information on a specified trigger.

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

Custom Headers

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

Path Parameters

  • The namespace that the trigger is in

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

Response

Status Code

  • Returned trigger

  • Unauthorized

  • Not Found

  • Internal Server Error

Example responses

Fire a trigger

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

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

Custom Headers

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

Path Parameters

  • Namespace that the trigger is in

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

Parameter bindings included in the context passed to the entity

Response

Status Code

  • OK

  • Unauthorized

  • Not Found

  • Request Timeout

  • Internal Server Error

Example responses

Update a trigger

Update a trigger.

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

Custom Headers

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

Path Parameters

  • Namespace that the trigger is in

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

Query Parameters

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

    Allowable values: [true,false]

Trigger details

Response

Status Code

  • OK

  • Bad Request

  • Unauthorized

  • Conflict

  • Internal Server Error

Example responses

Delete a trigger

Delete a trigger.

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

Custom Headers

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

Path Parameters

  • The namespace that the trigger is in

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

Response

Status Code

  • OK

  • Unauthorized

  • Not Found

  • Internal Server Error

Example responses

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

Query Parameters

  • Number of rules to include in the result

  • Number of rules to skip in the result

Response

Status Code

  • Rules response

  • Unauthorized

  • Internal Server Error

Example responses

Get rule information

Get information on a specified rule.

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

Custom Headers

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

Path Parameters

  • Namespace that the rule is in

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

Response

Status Code

  • Returned rule

  • Unauthorized

  • Not Found

  • Internal Server Error

Example responses

Enable or disable a rule

Enable or disable a rule.

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

Custom Headers

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

Path Parameters

  • Namespace that the rule is in

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

Query Parameters

  • Set to active to enable or inactive to disable

    Allowable values: [inactive,active]

Response

Status Code

  • OK

  • Accepted

  • Bad Request

  • Unauthorized

  • Internal Server Error

Example responses

Update a rule

Update a rule.

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

Custom Headers

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

Path Parameters

  • Namespace that the rule is in

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

Query Parameters

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

    Allowable values: [true,false]

Details of the rule

Response

Status Code

  • OK

  • Bad Request

  • Unauthorized

  • Conflict

  • Internal Server Error

Example responses

Delete a rule

Delete a rule.

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

Custom Headers

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

Path Parameters

  • Namespace that the rule is in

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

Response

Status Code

  • OK

  • Unauthorized

  • Not Found

  • Internal Server Error

Example responses