API Endpoints

A script, behind a URL

Sometimes the thing you want is a small endpoint — take some JSON, do something, return some JSON. Publish a script at a URL and you have exactly that, without standing up a service for it.

JSON in, JSON out

A URL that runs your code

A script becomes an endpoint at a stable path. POST a JSON body or GET with query parameters — either way it lands on the script's input — and whatever the script returns comes back as the JSON response.

Reachable by GET or POST at a stable, key-based path.
The request body or query becomes the script's input.
The script's result is serialized straight to the response.

POST · lead-capture

POST/api/v1/s/lead-capture

{ "email": "a@example.com" }

{ "ok": true, "id": "9f3c…" }

Open or gated

Public, or permission-gated

Mark an endpoint public and anyone can call it — handy for a webhook receiver or a public form. Leave it private and a caller needs execute permission on the script, enforced before a line of it runs. Either way, a run is bounded by a timeout.

Public endpoints take no auth; private ones require execute permission.
Permission is checked before the script executes.
Each request runs under a hard timeout.

access

publicanyone can call it

privateexecute permission required

timeoutevery request is bounded

You own the request

Shape it in the script

Because it's real code, the endpoint's behavior is yours. Validate the body, verify a webhook signature, branch on a header, decide what to return — it's all just Kotlin, right where the request arrives.

Validate and reject bad input yourself, with clear errors.
Verify a signature or token when you're receiving a webhook.
Return exactly the shape a caller expects.

lead-capture.bosca.kts

val email = context.input.jsonObject["email"]
require(email != null) { "email required" }

val leads = provide<MetadataService>()
// …store the lead, return a result

Keep exploring

A script, behind a URL

A URL that runs your code

Public, or permission-gated

Shape it in the script

More on Scripts

Scripts overview

Authoring

Script Library

Triggers