Developer docs
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
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
Use the strato CLI for the git-push workflow, or drive the API directly with curl.
# 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# 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
Every path below is a real route from services/<svc>/openapi.json. Jump into a surface for its worked example and architecture.
Push a repo; get a governed, routable app.
/api/v1/appsList the tenant's apps (cross-tenant rows never returned)/api/v1/appsRegister a new app within the tenant/api/v1/apps/{app}Fetch one app's definition/api/v1/apps/{app}/exportSovereign-exit: portable desired state (ADR-0055)/api/v1/apps/{app}/deployidempotentOne-shot deploy: build → gate → admit → roll → route/api/v1/apps/{app}/deploy/sagaidempotentStart the resumable staged deploy saga/api/v1/apps/{app}/deploy/saga/{id}/advanceApply one step, or ?run=all to a terminal state/api/v1/apps/{app}/deploy/saga/{id}Fetch one saga's persisted state/api/v1/apps/{app}/deploy/sagasList every deploy saga for the app/api/v1/apps/{app}/buildsList build records with gate verdict + admission status/api/v1/apps/{app}/revisionsList immutable, monotonically numbered revisions/api/v1/apps/{app}/rolloutActive / last-good revision, status and history/api/v1/apps/{app}/rollout/healthReport health; unhealthy auto-rolls-back to last-good/api/v1/apps/{app}/rollbackRe-point to an existing revision (no new build)/api/v1/incidentsThe tenant's auto-rollback incidents (SS-08 feed)/api/v1/apps/{app}/scaleInstall a scaling policy (clamped, quota-reserved)/api/v1/apps/{app}/scalePolicy, applied replicas and event history/api/v1/apps/{app}/scale/observeFeed an SS-06 metrics tick; apply behind quota/api/v1/quotaSet the tenant's total replica quota/api/v1/quotaReport quota and current ledger usage/api/v1/providerspublicThe ten-provider git catalog + signature schemes/api/v1/apps/{app}/gitConnect a repository to an app/api/v1/apps/{app}/gitRead the repo connection + auto-deploy policy/api/v1/apps/{app}/detectidempotentDetect deployable app types from the repo tree/api/v1/apps/{app}/deployablesRead stored deployable-detection results/api/v1/apps/{app}/autodeploySet continuous-deployment policy (branch glob, gates)/api/v1/webhooks/{provider}Inbound git-webhook listener (signature verified first)/api/v1/apps/{app}/cicd/runRun the pipeline manually (recorded whatever the outcome)/api/v1/apps/{app}/cicd/runsList pipeline runs, newest first/api/v1/apps/{app}/cicd/runs/{id}One run's full stage trace/api/v1/apps/{app}/cicd/flakyFlaky-test detection over run history/api/v1/apps/{app}/gatesReplace the app's quality-gate rules/api/v1/apps/{app}/gatesRead gate rules + most recent evaluation/api/v1/cicd/doraThe four DORA keys from the rollout spine/api/v1/cicd/insightsPer-stage duration analytics + top-failing stage/api/v1/cicd/alertsRegister a pipeline alert rule/api/v1/cicd/alertsList alert rules + fired alerts/api/v1/runnersList registered linux build runners/api/v1/runnersRegister a self-hosted linux runner/api/v1/runners/{id}/heartbeatLiveness heartbeat from the runner agent/api/v1/runners/{id}/onlineMark a runner online / available for offload/api/v1/apps/{app}/previewsCreate/renew a per-PR preview with a TTL lease/api/v1/apps/{app}/previewsList an app's previews (lapsed reads as expired)/api/v1/apps/{app}/previews/{pr}/closeTear down on merge/close, erase SS-02 claims/api/v1/previews/sweepSweeper: reclaim every lease-expired preview/api/v1/apps/{app}/addonsProvision an SS-02 claim + SS-05 secret ref/api/v1/apps/{app}/addonsList bound + erased addons (erasure retained)/api/v1/apps/{app}/addons/{name}Erase the addon's claim, record the erasure/api/v1/apps/{app}/cronsDefine a recurring job (SS-21 schedule)/api/v1/apps/{app}/cronsList crons with applied effect counts/api/v1/apps/{app}/crons/{name}/fireRecord a slot delivery (exactly-once effect)/api/v1/apps/{app}/crons/{name}/firesFire records incl. deduped redeliveries/api/v1/apps/{app}/gpugatedRequest a GPU workload (feature-gated, ADR-0060)/api/v1/apps/{app}/gpuList GPU workload requests/api/v1/apps/{app}/pipelineDefine ordered promotion stages/api/v1/apps/{app}/pipelineRead stages + revision promoted into each/api/v1/apps/{app}/pipeline/promotePromote a revision; gated stages park pending/api/v1/apps/{app}/pipeline/promotionsPromotion history incl. refusals (evidence)/api/v1/apps/{app}/pipeline/promotions/{id}/approveHuman approval; an agent is refused 403 (OPS09)Hermetic builds with waved agent autonomy.
/api/v1/runsidempotentOpen an agent-driven build run in a change class/api/v1/runsList runs with phase, class, wave and gate stack/api/v1/runs/{id}One run's full record incl. digest + attestation/api/v1/runs/{id}/buildidempotentRun the hermetic build (fails closed on non-cache dep)/api/v1/runs/{id}/attestAttach signed provenance (FAC03)/api/v1/runs/{id}/classifyValidate declared class vs actual diff (FAC07)/api/v1/runs/{id}/gatesRecord a gate-stack verdict (FAC10)/api/v1/runs/{id}/approveHuman merge approval (self-approval impossible, FAC09)/api/v1/runs/{id}/decideRun the merge decision on a signed, gated run/api/v1/runs/{id}/overrideT3 break-glass merge past a red gate (paged + audited)/api/v1/classesThe change-class taxonomy + autonomy ceilings/api/v1/classes/{class}/ceilingSet a class's autonomy ceiling (human-owned)/api/v1/classes/{class}/unfreezeUnfreeze a frozen class (audit-recorded)A leased environment per PR — reclaimed on its own.
/api/v1/environmentsList the tenant's environments/api/v1/environmentsCreate an environment/api/v1/environments/{id}Fetch one environment/api/v1/environments/{id}/costCost estimate for an environment/api/v1/environments/{id}/evidenceAttach evidence to an environment/api/v1/environments/{id}/lease/extendExtend an environment lease/api/v1/environments/{id}/refreshRefresh an environment/api/v1/environments/{id}/teardownTear down an environment/api/v1/previewsCreate a PR preview environment/api/v1/previewsList PR previews/api/v1/previews/{id}Get a PR preview/api/v1/previews/{id}/promotePromote a preview to a longer-lived target/api/v1/sandboxesCreate a seeded sandbox/api/v1/sandboxesList seeded sandboxes/api/v1/sandboxes/{id}Get a seeded sandbox/api/v1/demosCreate a demo environment/api/v1/demosList demo environments/api/v1/datasetsRegister a seed dataset/api/v1/guardrailsCreate a cost guardrail/api/v1/guardrailsList cost guardrails/api/v1/guardrails/{id}/breachRecord a cost guardrail breach/api/v1/policiesCreate a teardown policy/api/v1/policiesList teardown policies/api/v1/leases/expiringList leases due to expire (sweep candidates)/api/v1/usageTenant usage ledger + SS-10 delivery status/api/v1/infoService info + capability envelopeDeclare a backend; get collections, functions and an SDK.
/api/v1/claimsidempotentProvision a complete backend from one declaration/api/v1/appsCreate an empty tenant-scoped backend namespace/api/v1/apps/{app}/planDiff a desired claim → the plan apply would take/api/v1/apps/{app}/applyApply a plan, creating a new revision/api/v1/apps/{app}/revisionsList the app's applied revisions/api/v1/apps/{app}/collectionsDefine a schema-bound collection with row policies/api/v1/apps/{app}/collections/{coll}/recordsCreate a record (schema-validated, owner-stamped)/api/v1/apps/{app}/collections/{coll}/recordsList records (PostgREST-style filters, policy-filtered)/api/v1/apps/{app}/collections/{coll}/records/{id}Fetch a record (denied row reads as 404)/api/v1/apps/{app}/collections/{coll}/records/{id}Update a record (policy-enforced)/api/v1/apps/{app}/collections/{coll}/records/{id}Delete a record (policy-enforced)/api/v1/apps/{app}/collections/{coll}/feedPolicy-filtered change feed (resumable cursor)/api/v1/apps/{app}/functionsList function statuses (0 instances = scaled to zero)/api/v1/apps/{app}/functions/{fn}/invokeHTTP trigger with an optional JSON payload/api/v1/apps/{app}/functions/{fn}/eventsBus→function delivery (dedup by event_id)/api/v1/apps/{app}/functions/{fn}/invocationsA function's execution history/api/v1/apps/{app}/functions/{fn}/dlqDead-lettered deliveries + reasons/api/v1/apps/{app}/usagePer-function metering for the SS-10 usage line/api/v1/enginesThe engine catalog (Hasura, Directus, Cosmo, …)/api/v1/apps/{app}/enginesidempotentCompose/refresh the app's engine bindings/api/v1/apps/{app}/enginesRead the app's stored engine bindingsRun a suite; produce signed release evidence.
/api/v1/suitesList test suites/api/v1/suitesDefine a test suite/api/v1/suites/{id}Fetch one suite/api/v1/test-runsList test runs/api/v1/test-runsOpen a test run against a suite/api/v1/test-runs/{id}Fetch one test run/api/v1/test-runs/{id}/resultsPost results into a run/api/v1/test-runs/{id}/retryRetry a run/api/v1/test-runs/{id}/evidenceAttach evidence to a run/api/v1/device-farm/reservationsList device reservations/api/v1/device-farm/reservationsReserve real devices/api/v1/device-sessionsOpen a device session/api/v1/hil-sessionsList human-in-the-loop sessions/api/v1/hil-sessionsOpen a human-in-the-loop session/api/v1/quality-gates/evaluateEvaluate results into a pass/fail verdict/api/v1/performance-budgetsDeclare a performance budget/api/v1/performance-runsList performance runs/api/v1/performance-runsRun against a performance budget/api/v1/accessibility-auditsList accessibility audits/api/v1/accessibility-auditsRun an accessibility audit/api/v1/accessibility-audits/{id}Fetch one accessibility audit/api/v1/flaky-testsList detected flaky tests/api/v1/flaky-testsRecord a flaky-test signal/api/v1/flaky-tests/{id}/quarantineQuarantine a flaky test/api/v1/evidence/{release}Retrieve signed release evidence/api/v1/usageTenant usage ledger + SS-10 delivery status/api/v1/infoService info + capability envelope