Functions

A Function runs your code when a request arrives and returns a response. Use it for APIs, webhooks, data transformations and tools for AI agents. You write only the handler; Coderunner provides the HTTP endpoint, routing and scaling.

Before you start

• A workspace where you're a Writer, Admin or Owner.
• For the CLI: npm install -g @groundfloorcloud/cli, then gf login and gf workspaces use <workspace-id>.

Write the handler

Every handler receives two arguments:

• payload — the JSON sent by the caller.
• context — reserved for information from the runtime. Don't rely on its contents yet.

Whatever the handler returns becomes the response. You can return anything; this shape is the convention, and every example in these docs uses it:

const handler = async (context, payload) => {
  if (!payload?.name) {
    return {
      statusCode: 400,
      body: { error: "name is required" },
      headers: { "content-type": "application/json" },
    };
  }
  return {
    statusCode: 200,
    body: { greeting: `Hello, ${payload.name}` },
    headers: { "content-type": "application/json" },
  };
};

module.exports = { handler };

You don't create a server, listen on a port, add a /health route or write a Dockerfile. The same handler in Python, .NET, Go and Rust is in each language reference.

Deploy it

gf deploy --name greeter --workload-type function

API=https://platform.groundfloor.cloud/v1/workspaces/$WORKSPACE_ID/coderunners

# 1. Create the Coderunner
curl -X POST "$API" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"title":"greeter","runtime":"node","workload_type":"function"}'

# 2. Upload your ZIP as a new version. The response includes the version's ID.
curl -X POST "$API/$CODERUNNER_ID/upload" -H "Authorization: Bearer $TOKEN" \
  -F "file=@greeter.zip"

# 3. When the version's build has finished (GET $API/$CODERUNNER_ID/versions), deploy it
curl -X POST "$API/$CODERUNNER_ID/deploy" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"version_id":"'"$VERSION_ID"'"}'

Call it

Send a POST with JSON to the Deployment URL, with a bearer token:

curl -X POST "<deployment-url>" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada"}'

Which token to use:

You can also run it without the URL:

• Client Portal: open the Coderunner and use Run with a JSON payload.
• CLI: gf coderunner run -c greeter --payload '{"name":"Ada"}'
• API: POST https://platform.groundfloor.cloud/v1/workspaces/{workspace_id}/coderunners/{coderunner_id}/run with the payload itself as the JSON body.

Scaling

A Function scales with its traffic, between a minimum and a maximum number of instances that you set on the deployment.

• Minimum 0 — no instances run while it's idle, and one starts when a request arrives.
• Minimum 1 or more — instances stay warm, so the first request doesn't wait for one to start.

Set the range in the Client Portal's deploy dialog or with the API. See Configuration and secrets.

Check that it worked

The call returns your handler's response. If it fails, open Observe → Process Log to see your function's output and errors; see Logs and troubleshooting.

Next steps

• Configuration and secrets — environment variables and secrets your handler can read.
• Deploying and versions — redeploy, roll back, deploy from Git, promote between environments.
• Jobs — run code once in the background instead.