API reference
Everything the console and the CLI do goes through this HTTP API. 2004 operations, grouped by what they manage.
Basics
Base URL
https://api.gregale.dev. Every path below starts with /v1.
Authentication
Send an API key as Authorization: Bearer <key>. Create one in the console under Settings → API keys. The CLI reads it from FAAS_TOKEN.
Errors
Failures are application/problem+json with a stable code to branch on. Error codes
Retries
Operations that list an Idempotency-Key header store the response for 24 hours; a retry with the same key gets it back instead of acting twice.
Find an operation
By area
- AppsApp lifecycle (create, update, delete, wake, park).252 operations
- DeploymentsDeployments & build status.78 operations
- ProjectsMulti-workload repo decomposition. /v1/projects/scan is the dry-run that returns the PlanResponse (can_apply, plan_token); /v1/projects is the transactional apply that creates the project, its apps, and its crons in one Tx.143 operations
- InvocationsSync / async function invocations (event-driven surface, Move 2).40 operations
- JobsRun-to-completion batch jobs. Customers POST a stored image + command + env; the platform boots a Firecracker microVM, runs the command to completion, captures the exit code, and reports back. Lifecycle (created → running → succeeded | failed | timeout | oom | cancelled), per-task retry with backoff, dead-letter accounting on exhaustion.25 operations
- CronsScheduled HTTP-path requests or deployment-attached command runs.13 operations
- QueuesPer-app FIFO queues (send / receive / ack).54 operations
- SecretsPer-app sealed secrets, injected into authorized app VMs at wake.11 operations
- NetworkingEffective app networking and provider-neutral private-network attachment intent.14 operations
- Edge rulesEdge rules (route, rewrite, redirect, headers, cors, jwt, ip, validate, geo, async) per app.24 operations
- StoragePrivate customer object-storage preview, separate from runtime snapshots and image layers.83 operations
- Managed PostgresProvider-neutral managed PostgreSQL databases and workload bindings.52 operations
- ObservabilityPer-app observability surfaces — structured event timelines a customer or operator can query for a single wake. Cross-tagged with `apps` so a tag filter of `apps` surfaces lifecycle endpoints alongside the wake timeline.24 operations
- WebhooksOutbound webhook subscriptions. One row per (app, target_url) customer subscription; the dispatcher in the scheduler POSTs signed payloads to the target with exponential backoff + jitter and DLQs at attempt 7. The deliveries subroute surfaces the per-attempt retry state + a manual retry endpoint that clears status='dead' back to 'pending'.24 operations
- API keysAPI key management. ships the org-scoped surface under `/v1/orgs/{slug}/keys` — use those paths when minting/rotating/revoking keys for a specific org. The legacy `/v1/keys/*` paths stamp `org_id = caller's personal org` and dual-emit for one release cycle; drops them.22 operations
- AccountAccount & billing (self-service, GDPR, plan).42 operations
- OrganizationsOrganization surface. Path-scoped org CRUD, member management, invitations, and ownership transfer. The active-org hint is accepted via `X-Active-Org` / `?org=` on every org-scoped route (matches LoadOrg middleware precedence); path-scoped routes resolve via `{slug}` regardless.79 operations
- BillingBilling surface. Portal URLs are generated by the configured billing provider when supported, with the operator- configured URL as a fallback. Customer-facing mutations live inside the provider portal. Future endpoints (invoice list, etc.) share this tag.19 operations
- Alert rulesCustomer-configurable alert rules. A rule pins a metric (latency_p99_ms, error_rate_pct, …) to a threshold + comparison + window; when the threshold is breached the metering service dispatcher POSTs a signed payload to webhook_url. Account-wide rules (app_id == "") are visible in every per-app listing but the create/update/delete endpoints pin to a specific app.18 operations
- AuditCustomer-facing security event timeline. Append-only; read-only.4 operations
- AuthDashboard authentication. Email + password (Argon2id), Google OAuth, GitHub OAuth, password reset, session lifecycle. Cookies carry the session artifact; the device-code flow is the SDK programmatic-auth path.17 operations
- ConsumersStable end-customer identities and credentials for monetized APIs.54 operations
- Cors presetsCORS presets. A preset is a customer-owned, named, reusable CORS configuration (allow_origins, allow_methods, allow_headers, expose_headers, allow_credentials, max_age_seconds). A preset is referenced by a kind=cors edge rule via EdgeRuleCORSAction.cors_preset_id; the gateway merges the preset into the rule's resolved action at compile time (state. MergeCorsPresetIntoRule). Presets are account-scoped (app_id is null on the wire) or app-scoped (app_id is set). Free plan: feature gated off (402 plan_cors_preset_not_allowed). Hobby/ Pro/Scale: per-account and per-app caps enforced via plan_cors_preset_quota_reached.5 operations
- Data pipelinesStaged managed PostgreSQL mirrors with encrypted source registration and read-only application access.10 operations
- Delayed tasksScheduled future invocations (cron-style, one-shot).4 operations
- DeploydiffRead-only pre-deploy preview.1 operation
- DevStable, expiring remote developer environments used by `gregale dev`.28 operations
- DomainsCustom domain bindings.14 operations
- EnvPer-app plaintext env vars. Non-sensitive runtime config — credentials stay on /secrets. Values are stored as-is and applied on next wake.11 operations
- EventsTenant-scoped internal event ingress (EPIC #1278).132 operations
- Exclusive operations14 operations
- FlagsCustomer-aware application behavior releases and decision evidence.9 operations
- GitHubGitHub App integration. The dashboard bind picker surfaces the (installation_id, repo, branch) edge; /v1/auth/github + /oauth/callback handle the OAuth handshake and ownership proof.19 operations
- Inbound webhooksProvider-verified webhook ingress that persists an app invocation before returning 202, then uses the normal wake, retry, and dead-letter path. Stripe is the initial provider adapter.17 operations
- InstancesRead-only instance view.2 operations
- MCPMCP hosting health and catalog integrity checks for app deployments.40 operations
- MetaSelf-description endpoints (this spec). Anonymous.2 operations
- MfaOptional TOTP MFA on dashboard sessions. Five POST endpoints: enroll (one-shot secret + recovery codes), confirm (first TOTP code), verify (step-up for an mfa_pending session), recover (burn a recovery code), and disable (opt-out via password or recovery code). Enrollment is never triggered automatically by plan, billing, or deploy events.8 operations
- MirrorTraffic mirroring rules. Each rule pins a source deployment to a mirror deployment; the gateway fans out a percentage of live traffic to the mirror VM without influencing the source response. Plan caps: Pro = 1, Scale = 3, Free/Hobby = 0.7 operations
- Openapi discoveryCaptured OpenAPI documents per deployment.3 operations
- Openapi importImported OpenAPI documents per app + auto-generated merged spec.7 operations
- OperationsStaged customer-owned HTTP work, scoped status and durable progress; production admission is disabled.104 operations
- OutboundBind apps to account-owned, operator-provisioned managed outbound integrations without exposing provider credentials.61 operations
- Platform tenantsAccount-level end customers spanning app consumers and tenant surfaces.84 operations
- PreviewsPreview environments. A preview is a per-PR child app created by the GitHub bridge; the customer wakes the preview URL to exercise the change before merge. This tag groups the customer-facing destroy route (POST /v1/preview/{slug}/destroy) — the dashboard surface is under `apps` (the preview panel) and the build-pipeline surface is under `deployments` (preview kind deployments). Cross-tagged with `apps` so a tag filter of `apps` surfaces preview-destroy alongside the parent-app lifecycle.4 operations
- RealtimeDurable managed realtime endpoint configuration for long-lived WebSocket clients.125 operations
- RegistryPer-app private-registry Basic Auth credentials. Password is sealed at rest with secretbox under the host X25519 recipient (namespace `registry_creds`); the image service transiently unseals in the pull path. The plaintext never lands in PG.3 operations
- RunsDisposable, one-shot execution of caller-supplied Node.js or Python source inside a fresh, networkless Firecracker microVM. The VM is destroyed after every terminal result; no customer storage disk or persistent sandbox state is exposed by this API.15 operations
- SecurityPer-app security surfaces: the customer-scoped GET posture report, plus operator-only PATCH /v1/apps/{slug}/security (admin + MFA) for the require_signed flag and trusted_signers CRUD for the per-app cosign trusted-publisher list.9 operations
- StatusPublic platform status and operator-managed incident timelines.3 operations
- SupportGregale customer assistance, public conversations and resolution episodes.22 operations
- TelemetryProduction-debugger telemetry ingestion. The OTel spans writer is a sidecar protocol consumed by OTel SDKs, not a customer REST surface; the SDK does not model this route (routeExclude on both sdk-coverage and spec_compliance gates). OTLP/HTTP body shape is externally defined by the OpenTelemetry proto — the spec deliberately documents the endpoint metadata only.1 operation
- TemplatesStarter template catalog. The dashboard's /dashboard/apps/new wizard renders the GET /v1/templates response as the "Starting template" dropdown; the CLI's `gregale deploy --template NAME` and `gregale init --template NAME` validators reference the same source on the CLI side. Cookie-session-authenticated (NOT API-key) — the dashboard is the install-token trust root.1 operation
- Tenant surfacesTenant hostname groupings. One surface holds N hostnames under one SAN bundle. Soft-deleted surfaces are filtered out of list/get; the cert engine picks up pending-state surfaces via pg_notify('tenant_surface_changed') to mint the cert. Returns 503 when the `FAAS_TENANT_SURFACES_ENABLED` flag is off.6 operations
- TriggersEvent source mappings. A trigger is a unified resource that pulls records from a broker (kafka, nats, redis_streams, sqs_compat, queue) or a schedule (cron) and fans them into the function via batched invocations. The cron kind is a thin alias over /v1/crons — see the `crons` tag for the canonical cron API. Records carry ReportBatchItemFailures semantics stolen verbatim from AWS Lambda (the function returns `{"batchItemFailures":[{"item_identifier":"..."}]}`).17 operations
- UploadsResumable upload sessions. A session opens at POST /v1/uploads, accepts byte-range PATCHes, and finalizes via POST /v1/uploads/{id}/commit. Per-account open- session cap is 5; per-plan SourceTarballMaxMB caps total_size (Free/Hobby 100 MB, Pro/Scale 250 MB). The legacy single-shot `source-tarball` endpoint stays active during the migration and advertises RFC 9745 Deprecation, RFC 8594 Sunset, and RFC 8288 successor/deprecation links on every response.5 operations
- UpstreamsCustomer-managed data upstreams. Each row is an outbound connection the platform probes for RTT before biasing wake-time placement toward the region with the lowest observed latency. The probe loop in the metering service dials `host:port` via `crypto/tls.Dial` (never `http.Get`) and records per-region samples in `data_upstream_probes`; the chooser in the scheduler reads them synchronously at wake via `upstreamAffinity.Score(appID, deploymentScope)` (each deployment reads its own probe bias). Plaintext host is never emitted on the wire — only the sha256(salt||host) 8-hex prefix appears as a metric label.6 operations
- UsageUsage roll-up and metering.7 operations
- WorkflowsDurable multi-step workflow runs and external events.106 operations
Generating a client? The machine-readable spec is at /v1/openapi.yaml.