Create Application
Create an application — the content unit. Deploy files to it (upload or git) and expose it with an agentless endpoint. To do all of that in one call, use Quick Deploy instead.
With source: "upload" the app starts empty — upload a .zip next. With source: "git" the repo is connected and the first deploy is enqueued automatically.
Application types
The type field selects which components the application carries:
static
Default. A frontend only — your
.zip upload or git repo is built (or served as-is) to static files on the edge. Requires the application_hosting entitlement.managed
A managed backend — a long-running server built from a
Dockerfile into a signed, scanned, digest-pinned container image, run gVisor-isolated and reached through a managed endpoint. Requires the managed_backends entitlement, and creates the runtime spec.fullstack
Both: a static frontend on the edge and a managed backend, with the
backend_paths prefixes (default ["/api"]) path-routed to the backend.function
A serverless function — a handler you write, wrapped in a base runtime image and run scale-to-zero (cold-started by the edge on the first request, reaped back to zero when idle). Requires the functions_enabled entitlement (and honours the max_functions quota); configured with the
function_* fields below. See the Serverless functions guide.
Static builds vs. backend images. A
static app builds to files. A managed / fullstack app builds a container image from your Dockerfile — signed, vulnerability-scanned, and pinned to its digest so a rollback is an immutable pointer. Tune the runtime (port, health check, replicas, cpu/mem) via PUT /runtime. Only MySQL / MariaDB managed databases are available today.
Request body
name string
Required. Unique within the account (1–255 chars).
type string
static (default), managed, fullstack, or function (see above).source string
upload (default) or git.repo_url string
Required for
git. A github.com / gitlab.com URL.branch string
Git only. Default
main. Must be a valid git branch name, at most 255 bytes; otherwise 400 “That isn't a valid branch name. Enter it as it appears in your repository, like main or feature/login.”git_token string
Git only, optional. Token for private repos; encrypted at rest.
git_installation_uuid string (uuid)
Git only, instead of
repo_url / git_token. A GitHub account you connected through the ngris GitHub App (its uuid from GET /v1/git/installations — not GitHub's own installation_id). Use with repo. Builds use a short-lived, read-only token for that repository and pushes deploy without a webhook. See Import from GitHub.repo string
With
git_installation_uuid: "owner/name" of a repository that installation can read. branch defaults to its default branch.root_directory string
Optional. The repository subfolder builds run in (monorepos); default the repository root. Repo-relative: no leading
/, no ... Applied at create for static, managed, fullstack and function apps (change it later with PUT /applications/{uuid}); a wordpress app doesn't use it.install_command string
Optional. Build setting, stored before a git app's first build is queued: the app's own install command, run instead of the detected one.
static and fullstack (the front end), and managed (Node apps only: a Python or Go app's build fails with one). "" = detected.build_command string
Optional. The app's own build command, run after the install.
static and fullstack (the front end), and managed (Python: after the dependencies; Go: must write /app/server). "" = detected.output_dir string
Optional.
static and fullstack (the front end): the folder the build writes the site to, inside the project (e.g. dist); everything in it is published. Leading and trailing slashes are trimmed; no ..; . = the project root; at most 512 bytes. Used only when a build runs. "" = detected.start_command string
Optional.
managed, and fullstack (the backend): how the server starts, run with a shell; the server must listen on $PORT. npm start, npm run <name>, yarn <name> and pnpm <name> run that package.json script. See Backend Apps. "" = detected.backend_paths string[]
fullstack only. URL path prefixes routed to the backend (each /-rooted; max 20). Default ["/api"].port int
managed / fullstack only. The port your server listens on (1–65535). Default 8080.health_check_path string
managed / fullstack only. The absolute path the readiness probe calls; a deploy goes live only once it answers. Default / for managed, the first backend_paths prefix for fullstack.function_runtime string
function only. Base runtime: nodejs24 (Node.js 24, the default). nodejs20 and nodejs22 are still accepted as aliases and run on Node.js 24.function_handler string
function only. Entry as <file>:<export>. Default index.js:default.function_idle_seconds int
function only. Scale to zero after this many idle seconds (0 = never; 0–3600). Default 300.function_timeout_seconds int
function only. Per-request wall-clock cap (1–300). Default 30.function_max_concurrency int
function only. Concurrent requests per instance before scale-up (1–200). Default 40.prod_visibility string
Optional.
public or private — who can reach the production URL. Default public. Change later with PUT /visibility.preview_visibility string
Optional.
public or private — who can reach preview URLs. Default private.The four build settings are trimmed, and each command is one line of at most 1024 bytes (chain steps with &&; control and invisible characters are refused). A function or wordpress app takes none of them. A value the app's type can't take is refused; "" (back to detection) is always accepted. Change them later with PUT /applications/{uuid}.
Deprecated: git_installation_id (integer) is still accepted until the sunset. Send git_installation_uuid; sending both for different objects is a 400 id_uuid_mismatch.
Response (201 Created)
A static app (the default) answers the same object as Get Application: endpoints is [] and primary_endpoint_uuid is omitted until an endpoint serves it. A managed, fullstack or function app answers the application fields plus a runtime object (its runtime spec) in place of the runtime fields, endpoints and the quota_paused fields.
uuid string (uuid)
Stable identifier used in every other
/applications/{uuid} URL.account_uuid string (uuid)
The account that owns the app.
name string
The application name.
type string
static, managed, fullstack or function — whichever you requested.source string
upload or git.current_deploy_uuid string (uuid)?
The live deploy; omitted until the first build is ready.
publish_dir string
Site-root subfolder (empty = archive root).
index_document string
Directory index, default
index.html.spa_fallback boolean
Serve the index for unmatched paths (SPA routing).
prod_visibility string
public or private — production-URL access (default public).preview_visibility string
public or private — preview-URL access (default private).require_manual_promotion, root_directory, skew_protection_enabled, speed_insights_enabled boolean, string
The app's deploy and edge settings, at their defaults (
false, the repository root "" unless you sent root_directory). Change them with PUT /applications/{uuid}.install_command, build_command, output_dir, start_command string
A
static app's answer carries the build settings it was created with ("" = detected). A managed, fullstack or function app's answer doesn't: read them with Get Application.git object?
Git apps only: the
git object of Get Application (repository, branch, auto_deploy, auto_preview, connected, …; token and secret redacted). Omitted for upload apps.created_at, updated_at datetime
RFC 3339 UTC timestamps.
endpoint, url object, string
function apps only: the endpoint created with the function (a generated hostname on the platform domain, made the app's primary) and its https:// URL. It serves the function once the first deploy is ready. No other app type gets an endpoint at create — add one with Create Endpoint, or use Quick Deploy for a static app.endpoint_error string
function apps only, with status 207 instead of 201: why no endpoint could be created (for example, your plan's endpoint limit is reached). The function itself is created and deploys still work; add an endpoint later with Create Endpoint.Deprecated: until the sunset this response also carries the legacy integer id and *_id fields. Don't use them; read uuid and the *_uuid fields.
Errors
400
Missing/too-long name, bad
source, an invalid repo_url, root_directory, backend_paths, port or health_check_path, or a visibility other than public / private; a refused build setting — install_command must be a single line (chain commands with &&) of at most 1024 bytes (the same for build_command and start_command), invalid output_dir: must be a folder inside the project, like dist or build/site (no '..'), or a build setting the app's type can't take, e.g. start_command can only be set on a managed or full-stack app, output_dir can only be set on a static or full-stack app, install_command can only be set on a static, managed or full-stack app (a function takes none); git_installation_uuid is not a uuid or is combined with repo_url / git_token; id_uuid_mismatch.404
git_installation_uuid not found — no such linked installation in your active account.403
Not entitled — application_hosting for static apps, managed_backends for
managed/fullstack, functions_enabled for function — or the applications_max (or max_functions) quota is reached.409
An application with that name already exists.
Request — upload source
curl -X POST "https://api.ngris.com/v1/applications" \
-H "X-API-KEY: <your_api_key>" \
-H "Content-Type: application/json" \
-d '{ "name": "my-site", "source": "upload" }'
Request — git source
curl -X POST "https://api.ngris.com/v1/applications" \
-H "X-API-KEY: <your_api_key>" \
-H "Content-Type: application/json" \
-d '{
"name": "my-site",
"source": "git",
"repo_url": "https://github.com/acme/site",
"branch": "main"
}'
Request — import from GitHub (linked installation)
curl -X POST "https://api.ngris.com/v1/applications" \
-H "X-API-KEY: <your_api_key>" \
-H "Content-Type: application/json" \
-d '{
"name": "my-site",
"git_installation_uuid": "019ac714-01ea-71ee-9bce-e1a9e5abfba1",
"repo": "acme/site"
}'
Request — serverless function
curl -X POST "https://api.ngris.com/v1/applications" \
-H "X-API-KEY: <your_api_key>" \
-H "Content-Type: application/json" \
-d '{
"name": "my-fn",
"type": "function",
"source": "upload",
"function_runtime": "nodejs24"
}'
Response — 201 Created
{
"uuid": "019be838-d261-7d9b-9499-71995a3a91c6",
"account_uuid": "019a68b9-1a79-7820-a884-41f554aba6bd",
"name": "my-site",
"type": "static",
"source": "git",
"publish_dir": "",
"index_document": "index.html",
"spa_fallback": false,
"prod_visibility": "public",
"preview_visibility": "private",
"require_manual_promotion": false,
"root_directory": "",
"skew_protection_enabled": false,
"speed_insights_enabled": false,
"quota_paused": false,
"git": {
"application_uuid": "019be838-d261-7d9b-9499-71995a3a91c6",
"provider": "github",
"repo_url": "https://github.com/acme/site",
"owner": "acme",
"repo": "site",
"branch": "main",
"connected": false,
"auto_deploy": true,
"auto_preview": false
},
"backend_paths": [],
"port": 0,
"cpu_millis": 0,
"memory_mb": 0,
"min_replicas": 0,
"max_replicas": 0,
"health_check_path": "",
"endpoints": [],
"created_at": "2026-07-28T12:00:00Z",
"updated_at": "2026-07-28T12:00:00Z"
}
Was this helpful?