Build your first API

Create a small GET endpoint that returns JSON, test its sandbox URL, and learn the controller, action, and workflow model without connecting an external service.

Before you begin#

Sign in to your Cloudgate workspace with permission to create controllers and edit workflows. Use a new controller or a dedicated learning controller so the exercise is easy to identify later.

1. Create a controller and action#

1. Open Workflows → Controllers and create a controller named Getting Started with path getting-started.
2. Create an action in that controller. Name it Hello, set its route to hello, and select the GET method.
3. Open the action in Go to Flow Builder. If you are editing a published action, open a draft first.

The route field is only hello. Do not paste a hostname, /sbx, or the controller path into it.

2. Add a Function node#

Add a Function node named HelloResponse and make it the workflow's entry node. Use this script:

import json

return json.dumps({
    "message": "Hello from Cloudgate",
    "ready": True
})

Cloudgate runs the script inside its function runtime, so a top-level return is valid here. Leave this node's outgoing connection empty: its result is the final response. Select JSON as the action's response format and save the draft.

3. Test the sandbox route#

Use the action's test panel to send a GET request. The response should contain:

{
  "message": "Hello from Cloudgate",
  "ready": true
}

Then copy the action's public sandbox URL and test it from your own client. Its shape is:

https://YOUR-API-HOST/sbx/getting-started/hello

Use the authentication configured for the action. For a signed endpoint, follow request signing. An internal test can behave differently from an external request; checking the public route confirms routing and gateway access together.

4. Inspect the run#

Open Workflows → API Action Logs, select the sandbox environment, and find the request. Check its method, route, status, and workflow result. This is the same starting point you will use when debugging a larger workflow.

Next steps#

Add request input, call an external API, or follow the release workflow when you are ready to expose a production version.