Skip to content

Projects, environments and releases ​

This internal API prepares deployable applications without altering the DSL catalogue or publishing infrastructure. Its operational routes require a platform user session and a live OWNER/ADMIN membership in the active company. Direct promotion requires Nimo's confidential OAuth principal and the nimo:application-projects:promote scope; a USER JWT receives 403. The SPA promotes through the cookie-only BFF. The assignment remains shareable=false and publicSafe=false; it is not exposed to API keys, app clients, the public SDK, external MCP or the embeddable chat.

MethodRouteInputResult
GET/app-projects?page=1&limit=20page ≥ 1; limit 1–100 (default 20)200: { data, total, page, limit }, the active company's projects
POST/app-projects{ name, sourceType: "dsl", applicationRef } or { name, sourceType: "git-static" }201: project; creates preview and production with configuration revision 1 and different namespaces
POST/app-projects/:id/releasesDSL: { sourceVersion: 1 }; Git: { commitSha: "<full 40/64 hex SHA>" }201: release with snapshot, hash and format version
POST/app-projects/:projectId/releases/:releaseId/artifactNo bodyCompiles an immutable DSL bundle; requires a live OWNER/ADMIN. sourceHash stays separate from artifactHash
GET/app-projects/:projectId/releases/:releaseId/artifactProject and release UUIDsManifest and artifact URL; requires a live OWNER/ADMIN
GET/app-projects/:id/environmentsProject UUID200: environments with configRevision, releaseGeneration, dataNamespace, currentRelease
GET/app-projects/:projectId/environments/:environmentId/connectionsProject and environment UUIDsFour policies and a diagnostic; never returns credentials
PUT/app-projects/:projectId/environments/:environmentId/connectionsexpectedRevision and the policy for payment/email/push/webhookNew revision with references to active tenant providers. Preview rejects productive connections; sandbox without an adapter and push/webhook fail 422 without writing; stale revision: 409
GET/app-projects/:projectId/environments/:environmentId/runtime-originsProject and environment UUIDsList of exact active and retired origins
POST/app-projects/:projectId/environments/:environmentId/runtime-origins{ origin }Registers an exact HTTPS origin (localhost/loopback HTTP only in development); no wildcard, credentials, path, query or fragment
DELETE/app-projects/:projectId/environments/:environmentId/runtime-origins/:originIdProject, environment and origin UUIDsRetires the origin and immediately denies bound sessions
POST/app-projects/:projectId/environments/:environmentId/runtime-sessions{ originId, expiresInSeconds?: 60..3600 }Issues a single-use opaque nrs_… credential with 15 min by default, bound to user/app/company/project/environment/release/origin
DELETE/app-projects/runtime-sessions/:idUUID of the current user's sessionImmediate revocation; the next request returns 401
POST/app-operationsIdempotency-Key + { projectId, environmentId, releaseId, operationType: deployment|hosting-migration|hosting-rollback, expectedGeneration }201: operationId persisted before dispatch; migration/rollback only on the current release; a repeated key with the same input returns the operation, different input: 409
POST/app-environments/:id/promotionsInternal Nimo OAuth with the nimo:application-projects:promote scope; promotion payload201: activates the release tested in Preview; a normal USER JWT: 403; stale revision or active operation: 409
GET/app-operations/:idOperation UUID200: state and sanitized evidence for the active company; another company or nonexistent: 404
POST/app-operations/:id/cancelOperation UUID200: cancelled; finished operation: 409

The operations require a platform user with a live OWNER/ADMIN membership and are not exposed to the public SDK, external MCP or the embeddable chat. The durable table keeps the operation if the process restarts; an idempotency key cannot be reused with a different input. Migration and rollback store a snapshot of release, route, configuration revision and data namespace. If any of them changes before the cut, the operation fails without changing the active route. WfP never executes customer code, and temporary asset JWTs are not stored on the operation.

These routes are part of neither OpenAPI nor the public SDKs. They require the exact Origin from NIMO_INTERNAL_BFF_ORIGIN and the host-only __Secure-nimo_bff_session cookie with Secure, HttpOnly, SameSite=Lax, Path=/ai/internal/bff and a 15-minute TTL. Login validates the password and an active OWNER/ADMIN membership. It issues no JWT and no OAuth bearer. Every mutation uses X-Nimo-CSRF-Token; membership is revalidated on each request, and logout or rotation revokes the previous session.

MethodRouteInput / headersResult
POST/ai/internal/bff/sessionOrigin; { username, password, companyId }BFF cookie and { csrfToken, expiresAt, user }; bad credentials: 401
POST/ai/internal/bff/session/bootstrapCookie + OriginRenews the CSRF token for the session; invalid/expired/replayed session: 401
POST/ai/internal/bff/session/rotateCookie + Origin + X-Nimo-CSRF-TokenRotates the opaque session; the previous one is revoked
POST/ai/internal/bff/session/logoutCookie + Origin + X-Nimo-CSRF-TokenRevokes the session and clears the cookie; 204
POST/ai/internal/bff/promotions/environments/:environmentIdCookie + Origin + X-Nimo-CSRF-Token; promotion payload201: same promotion service with live OWNER/ADMIN revalidation

The BFF is a first-party browser boundary. A client that already holds an OWNER/ADMIN's credentials can still authenticate against the ordinary API routes; the promotion endpoint with a direct USER JWT stays denied.

DSL projects require either their own definition or a platform definition followed by the company. For platform definitions only the exact currently followed version can be pinned. No session: 401; revoked permission or external token: 403; someone else's, nonexistent or unauthorized project/definition/version: 404; invalid input: 400. Denied operations leave no partial writes.

The operations above require a platform JWT and a live OWNER/ADMIN role. Runtime sessions are restricted to an explicit allowlist of DSL execution routes and methods; the guard denies them on administrative endpoints, including @Public() routes. Every request revalidates membership, application role, release, expiry/revocation and the exact registered origin. The context is derived from the session and header selectors cannot change it. CORS reflects active origins for browser transport but grants no authority. This capability stays internal and is not added to the public SDK, external MCP or the embeddable chat.

Publishing another DSL version changes no releases and deploys nothing. A release is not edited; creating another one keeps the previous. currentRelease starts at null. Connections are stored as opaque references to existing providers in immutable revisions; credentials stay in the vault. Only production payment/Stripe and email/SMTP may reference active tenant providers. Preview uses no productive credentials and falls back to no built-in platform provider; without a sandbox adapter it returns a 422 diagnostic and does not execute the effect. Push and webhook stay blocked until approved adapters exist. The DSL runtime uses the authorized environment as the namespace for instances and relationships: preview and production share no data. Received IDs are accepted only after verifying membership, project ownership and the assigned release. The file namespace is still pending.

In Git, the SHA is a declarative reference: the repository is not queried or verified yet, nothing is built and nothing is deployed. repositoryBindingId is rejected until repositories are integrated and authorized. toolchain.snapshotSchemaVersion describes the capture format, not an executed build.

Promotion requires a live OWNER/ADMIN session and Preview's active release with a confirmed successful deployment. It verifies the configuration revision and the tenant provider references, creates an immutable assignment in Production and switches the active release in a transaction with generation control. It keeps the previous assignments. The confirmation indicates backend runtime activation; it does not deploy to Pages nor check Production's remote health. sourceHash, artifactHash and configurationHash describe the source snapshot, the compiled bytes and the private configuration revision, respectively.