Getting Started

1. Sign In And Create A Project

The public APIs expect a Firebase ID token in the Authorization header. After sign-in, create or select a tenant project and use that project ID for uploads, integrations, and deployments.

2. Load Runtime And Trigger Metadata

Before saving a draft, the frontend should load:

  • GET /api/v1/functions/trigger-types

  • GET /api/v1/runtimes

/api/v1/runtimes is the canonical runtime catalog. Only the versions in its supported array are selectable for new drafts.

3. Upload Artifacts

Stage your function artifacts first:

  • POST /api/v1/functions/upload/code

  • POST /api/v1/functions/upload/docker

  • POST /api/v1/functions/upload/yaml

Current upload contract:

  • content type must be multipart/form-data

  • the file field name is file

  • projectId is required in the same multipart request

  • if multiple storage integrations exist, send provider

Recommended files:

  • main.dart

  • Dockerfile

  • pubspec.yaml

4. Save The Draft Function

Create or update the function record after upload:

  • POST /api/v1/functions

  • POST /api/v1/functions/save

  • PUT /api/v1/functions/update

For current frontend work, the cleaner pattern is:

  1. upload the files

  2. keep the returned storage paths

  3. save or update the draft function

  4. build the deployment request from the saved function and explicit artifact inputs

5. Connect A Cloud Integration

Each project must connect the target cloud provider before deployment.

  • Azure uses Workload Identity registration and verification plus optional resource-template flows.

  • AWS uses OIDC setup commands and verification.

  • GCP uses Workload Identity Federation with the strict split-field contract documented in Cloud Integrations.

6. Start The Deployment

Use the canonical async deployment endpoint:

POST /api/v1/projects/\{projectId\}/deployments

Preferred request shape includes:

  • functionId

  • provider

  • artifactFiles.code_file

  • artifactFiles.docker_file

  • artifactFiles.pubspec_yaml

  • provider-specific target

  • provider-specific auth

The backend validates the selected runtime and checks pubspec.yaml against the currently deployable Dart runtime windows before queueing the deployment.

7. Poll Status And Events

Use these endpoints after queueing:

  • GET /api/v1/projects/{projectId}/deployments/{deploymentId}

  • GET /api/v1/projects/{projectId}/deployments/{deploymentId}/events

For teardown, call:

  • POST /api/v1/projects/{projectId}/deployments/{deploymentId}/undeploy

Notes About pubspec.yaml

The cleanest contract is to send an explicit environment.sdk constraint that matches the selected runtime window. The backend can normalize a missing constraint for deployment packaging, but runtime-window enforcement still applies and mismatched constraints are rejected.