HTTP Invoke

Call a deployed function on-demand from your Flutter app using the SDK. The function receives your request body and returns a response synchronously.

Invoke from Flutter

Use Koolbase.functions.invoke() to call a function by name. Pass any JSON-serialisable map as the request body.

lib/functions.dartDart

final result = await Koolbase.functions.invoke(
  'send-welcome-email',
  body: {'userId': currentUser.id},
);

print(result.status);  // HTTP status code
print(result.data);    // parsed JSON response from your function

Accessing the request in the function

Inside the function, ctx.request contains your body and headers:

send-welcome-email/index.tsTypeScript

export async function handler(ctx) {
  // ctx.request contains the body your Flutter app sent
  const { userId } = ctx.request;

  // ctx.request.headers contains request headers
  const authHeader = ctx.request.headers?.authorization;

  return { received: userId };
}

Return values

Whatever your function returns is sent back as JSON. Return any JSON-serialisable object. Throw an error to return a 500 status.

index.tsTypeScript

export async function handler(ctx) {
  // Return success
  return { ok: true, message: 'Done' };

  // Return with specific data
  return { userId: '123', email: 'user@example.com', processed: true };

  // Throw to signal failure (returns 500)
  throw new Error('Something went wrong');
}

Response status

A successful function return maps to HTTP 200. An uncaught exception or timeout maps to HTTP 500. The Flutter SDK exposes both result.status and result.data so you can handle both cases.

Error handling in Flutter

lib/functions.dartDart

try {
  final result = await Koolbase.functions.invoke(
    'process-payment',
    body: {'amount': 4999, 'currency': 'usd'},
  );

  if (result.status == 200) {
    showSuccess('Payment processed');
  } else {
    showError('Function returned error: ${result.data['error']}');
  }
} on KoolbaseFunctionException catch (e) {
  showError('Invocation failed: ${e.message}');
}

Direct API call

You can also invoke functions directly via the REST API without the Flutter SDK:

POST https://api.koolbase.com/v1/sdk/functions/{function_name}
x-api-key: pk_live_your_key_here
Content-Type: application/json

{
  "userId": "abc123"
}

Payload limit

The maximum request payload for HTTP invocations is 1MB. Requests exceeding this limit return a 413 error before the function executes.