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 And Verify The Cloud Identity

Each project must connect the target cloud provider before deployment.

Current provider expectations:

  • Azure uses Workload Identity registration and verification, then optional resource bootstrap and resource verification.

  • AWS uses generated OIDC setup commands plus role verification.

  • GCP uses the public WIF contract plus a customer-managed service account that DCF can impersonate. Cloud Run is the standard GCP runtime target; GKE is an advanced enterprise option for customers that already provide the cluster and workload references.

Identity verification confirms the trust path is working. It does not automatically mean artifact storage is ready.

6. Verify And Save Artifact Storage

After identity setup, verify the bucket or container that will hold function artifacts:

  • POST /api/v1/projects/{projectId}/integrations/aws/bucket/check

  • POST /api/v1/projects/{projectId}/integrations/aws/bucket/config

  • POST /api/v1/projects/{projectId}/integrations/gcp/bucket/check

  • POST /api/v1/projects/{projectId}/integrations/gcp/bucket/config

  • POST /api/v1/projects/{projectId}/integrations/azure/bucket/check

  • GET /api/v1/projects/{projectId}/integrations/azure/bucket/config

  • POST /api/v1/projects/{projectId}/integrations/azure/bucket/config

Important distinction:

  • Azure needs both management-plane access and Blob data-plane access.

  • AWS OIDC verification does not replace S3 bucket access requirements.

  • GCP verification does not create the bucket or grant bucket permissions by itself.

  • GCP bucket config also stores the deployment region and existing Artifact Registry Docker repository name. For Cloud Run, it also stores the selected runtimeTarget and optional fixed serviceName. The repository entered in the UI must match a repository in the customer’s selected GCP project and region.

See Cloud Integrations for provider-specific permissions and failure modes.

7. 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

For GCP, set target.runtimeTarget explicitly. Use cloud_run with target.serviceName for standard deployments. Use gke only when the customer has the GKE entitlement and can supply namespace, deploymentName, and containerName.

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

8. 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.