Quickstart

A function in 15 lines of code.

1. Write the function

functions/hello.ts:

export default {
  async fetch(req: Request, env: Env, _ctx: ExecutionContext): Promise<Response> {
    const userId = req.headers.get('X-Amba-User-Id') || 'anonymous';
    return Response.json({ hello: userId, project: env.AMBA_PROJECT_ID });
  },
};
 
interface Env {
  AMBA_API_URL: string;
  AMBA_PROJECT_ID: string;
  AMBA_INTERNAL_TOKEN: string;
  EDGE_HEADER_SIGNING_SECRET: string;
  AMBA_AI_GATEWAY_URL: string;
  STORAGE?: unknown; // object storage handle; type depends on the storage client you choose
}

The default export is the Amba runtime module shape ({ async fetch(req, env, ctx) }). The runtime injects env bindings at deploy time — see Runtime for the full list. There is no @layers/amba-* import; the bundle stays self-contained.

2. Deploy

amba functions deploy ./functions/hello.ts

Output (abridged):

  Bundle:
    size: 0.4KB compressed (0.7KB raw)

  ✓ Deployed hello v1
  ✓ URL: https://<project_id>.fn.amba.host/hello

amba functions deploy bundles with esbuild (--bundle --format=esm --platform=browser --target=es2022), checks the size against the 8 MB cap, POSTs to the admin API, and waits for the runtime to acknowledge.

3. Call it

Call it at the URL the deploy printed: the project id is the subdomain and the function name is the first path segment.

curl "https://${AMBA_PROJECT_ID}.fn.amba.host/hello" \
  -H "X-Api-Key: ${AMBA_CLIENT_KEY}"
# {"hello":"anonymous","project":"b61415c0-…"}

Functions require an API key by default; a request without X-Api-Key gets 401. A valid client key with no session token runs the function with an empty X-Amba-User-Id, so this handler answers anonymous. Add the end-user session token (Authorization: Bearer <session token>) and Amba signs that user's id into X-Amba-User-Id. To accept requests with no API key at all (an inbound webhook, for example), deploy with amba functions deploy --public and verify the caller inside the function.

4. Call back into Amba

To read a collection, send a push, grant currency, etc., fetch the project-scoped admin API using env.AMBA_INTERNAL_TOKEN. This token is scoped to this project only — it authenticates /v1/admin/projects/${env.AMBA_PROJECT_ID}/* and nothing else. Global admin operations (creating projects, listing developer-owned projects) require a developer PAT instead. See Token reference for the full breakdown.

const res = await fetch(
  `${env.AMBA_API_URL}/v1/admin/projects/${env.AMBA_PROJECT_ID}/collections/configs/rows?key=launch_config`,
  { headers: { Authorization: `Bearer ${env.AMBA_INTERNAL_TOKEN}` } },
);
const { data } = await res.json();

Full endpoint catalog: /api-reference/admin.

Next

• Runtime contract — every binding, every header, every error code → fix.
• Local dev — iterate on a function without deploying.
• Deploy — the deploy lifecycle, rollback, scheduled invocations.