Developer docs

Every route is governed. Here they all are.

The endpoint catalog for all five surfaces, grouped by capability — real method+path from the openapi contracts. Auth is one model everywhere: an SS-01 bearer token plus X-Tenant-Id. 146 endpoints documented here; 148 operations across the surfaces.

Auth model

Auth model

Every /api/v1 route takes an SS-01 OIDC bearer token and an X-Tenant-Id header (ADR-0019). Money/usage writes take an Idempotency-Key (ADR-0039). Browser clients never set X-Tenant-Id themselves — tenancy comes from their bearer token.

Authorization: Bearer $TOKENSS-01 OIDC token; carries the tenant on the strong path.
X-Tenant-Id: acmeRequired on every /api/v1 route; must agree with the token.
Idempotency-Key: $(uuidgen)On money/usage writes (deploy, scale, saga).

Public base https://api.skyforge.io/api/v1 · in-mesh http://ss-47-skyforge.shared-services.svc.cluster.local:8047 · external via SS-07 gateway https://gateway.<region>.nexocloud.io/skyforge.

Quickstart

From git repo to a routable TLS URL.

Use the strato CLI for the git-push workflow, or drive the API directly with curl.

strato CLI — git push to deploy
# Install the strato CLI
$ curl -fsSL https://get.skyforge.io/strato | sh
$ strato login            # opens SS-01 OIDC device flow
$ strato tenant use acme

# Connect a repo and turn on hands-off deploys
$ strato apps connect storefront \
    --repo github.com/acme/storefront --branch main
$ strato autodeploy enable storefront --branch main

# Ship. checkout → build → test → scan → gate → admit → roll → route
$ git push origin main
  → run succeeded · deployed revision storefront-r9
  → https://storefront.acme.skyforge.app
curl — crash-safe deploy saga
# Auth is an SS-01 OIDC token + your tenant header.
export TOKEN=...            # from signup / API key
export TENANT=acme
export BASE=https://api.skyforge.io/api/v1

# 1. Create the app
curl -X POST "$BASE/apps" \
  -H "Authorization: Bearer $TOKEN" -H "X-Tenant-Id: $TENANT" \
  -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  -d '{"name":"storefront","repo":"git@github.com:acme/storefront.git","branch":"main"}'

# 2. Start the crash-safe deploy saga
SAGA=$(curl -sX POST "$BASE/apps/storefront/deploy/saga" \
  -H "Authorization: Bearer $TOKEN" -H "X-Tenant-Id: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{"git_sha":"9b2c867","image":{"digest":"sha256:9f2c","signed":true,"sbom":true,"scanned":true},"gate":"pass"}')

# 3. Drive it to a terminal state — crash-safe, resumes at the failed step
curl -X POST "$BASE/apps/storefront/deploy/saga/$(echo "$SAGA" | jq -r .id)/advance?run=all" \
  -H "Authorization: Bearer $TOKEN" -H "X-Tenant-Id: $TENANT"

Full request/response examples for every SS-47 route live in the platform API reference (docs/product/api-reference/SS-47-skyforge.md); the sibling surfaces have their own references (SS-31, SS-52, SS-11, SS-53).

Endpoint catalog

Grouped by capability.

Every path below is a real route from services/<svc>/openapi.json. Jump into a surface for its worked example and architecture.

PaaS app plane SS-47 · 61 ops

Push a repo; get a governed, routable app.

Deep-dive →

Apps

  • GET/api/v1/appsList the tenant's apps (cross-tenant rows never returned)
  • POST/api/v1/appsRegister a new app within the tenant
  • GET/api/v1/apps/{app}Fetch one app's definition
  • GET/api/v1/apps/{app}/exportSovereign-exit: portable desired state (ADR-0055)

Deploy saga

  • POST/api/v1/apps/{app}/deployidempotentOne-shot deploy: build → gate → admit → roll → route
  • POST/api/v1/apps/{app}/deploy/sagaidempotentStart the resumable staged deploy saga
  • POST/api/v1/apps/{app}/deploy/saga/{id}/advanceApply one step, or ?run=all to a terminal state
  • GET/api/v1/apps/{app}/deploy/saga/{id}Fetch one saga's persisted state
  • GET/api/v1/apps/{app}/deploy/sagasList every deploy saga for the app
  • GET/api/v1/apps/{app}/buildsList build records with gate verdict + admission status

Rollout, revisions & rollback

  • GET/api/v1/apps/{app}/revisionsList immutable, monotonically numbered revisions
  • GET/api/v1/apps/{app}/rolloutActive / last-good revision, status and history
  • POST/api/v1/apps/{app}/rollout/healthReport health; unhealthy auto-rolls-back to last-good
  • POST/api/v1/apps/{app}/rollbackRe-point to an existing revision (no new build)
  • GET/api/v1/incidentsThe tenant's auto-rollback incidents (SS-08 feed)

Scaling & quota

  • PUT/api/v1/apps/{app}/scaleInstall a scaling policy (clamped, quota-reserved)
  • GET/api/v1/apps/{app}/scalePolicy, applied replicas and event history
  • POST/api/v1/apps/{app}/scale/observeFeed an SS-06 metrics tick; apply behind quota
  • PUT/api/v1/quotaSet the tenant's total replica quota
  • GET/api/v1/quotaReport quota and current ledger usage

CI/CD control plane

  • GET/api/v1/providerspublicThe ten-provider git catalog + signature schemes
  • POST/api/v1/apps/{app}/gitConnect a repository to an app
  • GET/api/v1/apps/{app}/gitRead the repo connection + auto-deploy policy
  • POST/api/v1/apps/{app}/detectidempotentDetect deployable app types from the repo tree
  • GET/api/v1/apps/{app}/deployablesRead stored deployable-detection results
  • PUT/api/v1/apps/{app}/autodeploySet continuous-deployment policy (branch glob, gates)
  • POST/api/v1/webhooks/{provider}Inbound git-webhook listener (signature verified first)
  • POST/api/v1/apps/{app}/cicd/runRun the pipeline manually (recorded whatever the outcome)
  • GET/api/v1/apps/{app}/cicd/runsList pipeline runs, newest first
  • GET/api/v1/apps/{app}/cicd/runs/{id}One run's full stage trace
  • GET/api/v1/apps/{app}/cicd/flakyFlaky-test detection over run history
  • PUT/api/v1/apps/{app}/gatesReplace the app's quality-gate rules
  • GET/api/v1/apps/{app}/gatesRead gate rules + most recent evaluation
  • GET/api/v1/cicd/doraThe four DORA keys from the rollout spine
  • GET/api/v1/cicd/insightsPer-stage duration analytics + top-failing stage
  • PUT/api/v1/cicd/alertsRegister a pipeline alert rule
  • GET/api/v1/cicd/alertsList alert rules + fired alerts

Self-hosted runners (ADR-0070)

  • GET/api/v1/runnersList registered linux build runners
  • POST/api/v1/runnersRegister a self-hosted linux runner
  • POST/api/v1/runners/{id}/heartbeatLiveness heartbeat from the runner agent
  • POST/api/v1/runners/{id}/onlineMark a runner online / available for offload

Preview environments

  • POST/api/v1/apps/{app}/previewsCreate/renew a per-PR preview with a TTL lease
  • GET/api/v1/apps/{app}/previewsList an app's previews (lapsed reads as expired)
  • POST/api/v1/apps/{app}/previews/{pr}/closeTear down on merge/close, erase SS-02 claims
  • POST/api/v1/previews/sweepSweeper: reclaim every lease-expired preview

Addons, crons & GPU

  • POST/api/v1/apps/{app}/addonsProvision an SS-02 claim + SS-05 secret ref
  • GET/api/v1/apps/{app}/addonsList bound + erased addons (erasure retained)
  • DELETE/api/v1/apps/{app}/addons/{name}Erase the addon's claim, record the erasure
  • POST/api/v1/apps/{app}/cronsDefine a recurring job (SS-21 schedule)
  • GET/api/v1/apps/{app}/cronsList crons with applied effect counts
  • POST/api/v1/apps/{app}/crons/{name}/fireRecord a slot delivery (exactly-once effect)
  • GET/api/v1/apps/{app}/crons/{name}/firesFire records incl. deduped redeliveries
  • POST/api/v1/apps/{app}/gpugatedRequest a GPU workload (feature-gated, ADR-0060)
  • GET/api/v1/apps/{app}/gpuList GPU workload requests

Pipelines & promotion

  • POST/api/v1/apps/{app}/pipelineDefine ordered promotion stages
  • GET/api/v1/apps/{app}/pipelineRead stages + revision promoted into each
  • POST/api/v1/apps/{app}/pipeline/promotePromote a revision; gated stages park pending
  • GET/api/v1/apps/{app}/pipeline/promotionsPromotion history incl. refusals (evidence)
  • POST/api/v1/apps/{app}/pipeline/promotions/{id}/approveHuman approval; an agent is refused 403 (OPS09)

CI/CD factory SS-31 · 13 ops

Hermetic builds with waved agent autonomy.

Deep-dive →

Build runs

  • POST/api/v1/runsidempotentOpen an agent-driven build run in a change class
  • GET/api/v1/runsList runs with phase, class, wave and gate stack
  • GET/api/v1/runs/{id}One run's full record incl. digest + attestation
  • POST/api/v1/runs/{id}/buildidempotentRun the hermetic build (fails closed on non-cache dep)
  • POST/api/v1/runs/{id}/attestAttach signed provenance (FAC03)
  • POST/api/v1/runs/{id}/classifyValidate declared class vs actual diff (FAC07)
  • POST/api/v1/runs/{id}/gatesRecord a gate-stack verdict (FAC10)

Merge decision

  • POST/api/v1/runs/{id}/approveHuman merge approval (self-approval impossible, FAC09)
  • POST/api/v1/runs/{id}/decideRun the merge decision on a signed, gated run
  • POST/api/v1/runs/{id}/overrideT3 break-glass merge past a red gate (paged + audited)

Change classes (FAC07/08)

  • GET/api/v1/classesThe change-class taxonomy + autonomy ceilings
  • POST/api/v1/classes/{class}/ceilingSet a class's autonomy ceiling (human-owned)
  • POST/api/v1/classes/{class}/unfreezeUnfreeze a frozen class (audit-recorded)

Ephemeral environments & sandboxes SS-52 · 26 ops

A leased environment per PR — reclaimed on its own.

Deep-dive →

Environments

  • GET/api/v1/environmentsList the tenant's environments
  • POST/api/v1/environmentsCreate an environment
  • GET/api/v1/environments/{id}Fetch one environment
  • GET/api/v1/environments/{id}/costCost estimate for an environment
  • POST/api/v1/environments/{id}/evidenceAttach evidence to an environment
  • POST/api/v1/environments/{id}/lease/extendExtend an environment lease
  • POST/api/v1/environments/{id}/refreshRefresh an environment
  • POST/api/v1/environments/{id}/teardownTear down an environment

Previews, sandboxes & demos

  • POST/api/v1/previewsCreate a PR preview environment
  • GET/api/v1/previewsList PR previews
  • GET/api/v1/previews/{id}Get a PR preview
  • POST/api/v1/previews/{id}/promotePromote a preview to a longer-lived target
  • POST/api/v1/sandboxesCreate a seeded sandbox
  • GET/api/v1/sandboxesList seeded sandboxes
  • GET/api/v1/sandboxes/{id}Get a seeded sandbox
  • POST/api/v1/demosCreate a demo environment
  • GET/api/v1/demosList demo environments
  • POST/api/v1/datasetsRegister a seed dataset

Governance

  • POST/api/v1/guardrailsCreate a cost guardrail
  • GET/api/v1/guardrailsList cost guardrails
  • POST/api/v1/guardrails/{id}/breachRecord a cost guardrail breach
  • POST/api/v1/policiesCreate a teardown policy
  • GET/api/v1/policiesList teardown policies
  • GET/api/v1/leases/expiringList leases due to expire (sweep candidates)
  • GET/api/v1/usageTenant usage ledger + SS-10 delivery status
  • GET/api/v1/infoService info + capability envelope

BaaS application platform SS-11 · 21 ops

Declare a backend; get collections, functions and an SDK.

Deep-dive →

Backends & revisions

  • POST/api/v1/claimsidempotentProvision a complete backend from one declaration
  • POST/api/v1/appsCreate an empty tenant-scoped backend namespace
  • POST/api/v1/apps/{app}/planDiff a desired claim → the plan apply would take
  • POST/api/v1/apps/{app}/applyApply a plan, creating a new revision
  • GET/api/v1/apps/{app}/revisionsList the app's applied revisions

Collections & data API

  • POST/api/v1/apps/{app}/collectionsDefine a schema-bound collection with row policies
  • POST/api/v1/apps/{app}/collections/{coll}/recordsCreate a record (schema-validated, owner-stamped)
  • GET/api/v1/apps/{app}/collections/{coll}/recordsList records (PostgREST-style filters, policy-filtered)
  • GET/api/v1/apps/{app}/collections/{coll}/records/{id}Fetch a record (denied row reads as 404)
  • PUT/api/v1/apps/{app}/collections/{coll}/records/{id}Update a record (policy-enforced)
  • DELETE/api/v1/apps/{app}/collections/{coll}/records/{id}Delete a record (policy-enforced)
  • GET/api/v1/apps/{app}/collections/{coll}/feedPolicy-filtered change feed (resumable cursor)

Functions

  • GET/api/v1/apps/{app}/functionsList function statuses (0 instances = scaled to zero)
  • POST/api/v1/apps/{app}/functions/{fn}/invokeHTTP trigger with an optional JSON payload
  • POST/api/v1/apps/{app}/functions/{fn}/eventsBus→function delivery (dedup by event_id)
  • GET/api/v1/apps/{app}/functions/{fn}/invocationsA function's execution history
  • GET/api/v1/apps/{app}/functions/{fn}/dlqDead-lettered deliveries + reasons
  • GET/api/v1/apps/{app}/usagePer-function metering for the SS-10 usage line

Engines

  • GET/api/v1/enginesThe engine catalog (Hasura, Directus, Cosmo, …)
  • POST/api/v1/apps/{app}/enginesidempotentCompose/refresh the app's engine bindings
  • GET/api/v1/apps/{app}/enginesRead the app's stored engine bindings

Continuous TestGrid & device lab SS-53 · 27 ops

Run a suite; produce signed release evidence.

Deep-dive →

Suites & test runs

  • GET/api/v1/suitesList test suites
  • POST/api/v1/suitesDefine a test suite
  • GET/api/v1/suites/{id}Fetch one suite
  • GET/api/v1/test-runsList test runs
  • POST/api/v1/test-runsOpen a test run against a suite
  • GET/api/v1/test-runs/{id}Fetch one test run
  • POST/api/v1/test-runs/{id}/resultsPost results into a run
  • POST/api/v1/test-runs/{id}/retryRetry a run
  • POST/api/v1/test-runs/{id}/evidenceAttach evidence to a run

Device farm & HIL

  • GET/api/v1/device-farm/reservationsList device reservations
  • POST/api/v1/device-farm/reservationsReserve real devices
  • POST/api/v1/device-sessionsOpen a device session
  • GET/api/v1/hil-sessionsList human-in-the-loop sessions
  • POST/api/v1/hil-sessionsOpen a human-in-the-loop session

Quality, performance & a11y

  • POST/api/v1/quality-gates/evaluateEvaluate results into a pass/fail verdict
  • POST/api/v1/performance-budgetsDeclare a performance budget
  • GET/api/v1/performance-runsList performance runs
  • POST/api/v1/performance-runsRun against a performance budget
  • GET/api/v1/accessibility-auditsList accessibility audits
  • POST/api/v1/accessibility-auditsRun an accessibility audit
  • GET/api/v1/accessibility-audits/{id}Fetch one accessibility audit

Flaky tests & evidence

  • GET/api/v1/flaky-testsList detected flaky tests
  • POST/api/v1/flaky-testsRecord a flaky-test signal
  • POST/api/v1/flaky-tests/{id}/quarantineQuarantine a flaky test
  • GET/api/v1/evidence/{release}Retrieve signed release evidence
  • GET/api/v1/usageTenant usage ledger + SS-10 delivery status
  • GET/api/v1/infoService info + capability envelope