LIGHTCLOUD
DOCS
Documentation menu

Application endpoints - list, retrieve, create, deploy, rename, move, delete, and manage custom domains.

Applications

An application is one deployed project. Creating one also creates its production environment, so a single call gets you a live URL.

With an API key the organisation is inferred. Session tokens must add targetOrganisationId to every body.

List applications#

POST/api/applications

Applications in the organisation, newest first, paginated.

permission
read:projects

Parameters

pagenumberdefault 1
1-based page number
limitnumberdefault 10
Between 1 and 100
filterstringoptional
Free text, matched against the name
sortColumnstringdefault created_at
Field to order by
sortOrderstringdefault desc
asc or desc
targetOrganisationIdstringsession only
Required when using a session token
curl -X POST https://api.light-cloud.com/api/applications \
  -H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 100}'
200ResponsePaginated envelope
{
  "items": [
    {
      "id": "app_4kQ2",
      "name": "shop",
      "slug": "shop",
      "deployment_type": "container",
      "framework": "nextjs",
      "runtime": "nodejs",
      "github_repo_url": "https://github.com/acme/shop",
      "github_branch": "main",
      "source_type": "github",
      "status": "healthy",
      "url": "https://main-shop-acme.light-cloud.io",
      "created_at": "2026-08-01T09:14:00.000Z",
      "updated_at": "2026-08-28T07:02:00.000Z"
    }
  ],
  "totalItems": 1,
  "totalPages": 1,
  "currentPage": 1
}

Retrieve an application#

POST/api/applications/get

One application with its environments. status is one of pending, building, deploying, healthy, degraded, failed, deleting.

permission
read:projects

Parameters

applicationIdstringrequired
The application to read
targetOrganisationIdstringsession only
Required when using a session token
curl -X POST https://api.light-cloud.com/api/applications/get \
  -H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"applicationId": "app_4kQ2"}'
200ResponseAn application
{
  "id": "app_4kQ2",
  "name": "shop",
  "status": "healthy",
  "url": "https://main-shop-acme.light-cloud.io",
  "environments": [
    { "id": "env_7Tz", "name": "production", "is_production": true }
  ]
}

Retrieve status#

POST/api/applications/status

The same shape as retrieve, cheaper. Use it when polling a deploy rather than re-reading the whole record.

permission
read:projects

Parameters

applicationIdstringrequired
The application to poll
targetOrganisationIdstringsession only
Required when using a session token
until [ "$(curl -sS -X POST https://api.light-cloud.com/api/applications/status \
  -H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"applicationId\":\"$APP_ID\"}" | jq -r .status)" = "healthy" ]; do
  sleep 10
done
200ResponseCurrent status
{
  "id": "app_4kQ2",
  "status": "building",
  "url": "https://main-shop-acme.light-cloud.io"
}

Detect a framework#

POST/api/applications/detect-framework

Reads a repository the way the console's create page does and returns the settings it would fill in. Call this before create rather than guessing.

permission
read:projects

Parameters

ownerstringrequired
Repository owner
repostringrequired
Repository name
branchstringrequired
Branch to inspect
rootDirectorystringoptional
Subdirectory, for a monorepo
targetOrganisationIdstringsession only
Required when using a session token
curl -X POST https://api.light-cloud.com/api/applications/detect-framework \
  -H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"owner": "acme", "repo": "shop", "branch": "main"}'
200ResponseDetected build settings
{
  "framework": "nextjs",
  "runtime": "nodejs",
  "deploymentType": "container",
  "buildCommand": "npm run build",
  "outputDirectory": ".next"
}

Create an application#

POST/api/applications/create

Creates the application and its production environment, and starts the first build. Creates are not idempotent — if one times out, list before retrying.

permission
create:projects

Parameters

namestringrequired
Becomes part of the generated subdomain
githubRepoUrlstringrequired
Repository URL on GitHub, GitLab or Bitbucket - must be reachable
gitProviderstringdefault github
github, gitlab or bitbucket; a gitlab.com or bitbucket.org URL implies its provider
gitlabProjectIdnumberdefault resolved
GitLab only - the numeric project id; resolved from the URL when omitted
bitbucketRepoUuidstringdefault resolved
Bitbucket only - the repository uuid (braced); resolved from the URL when omitted
githubBranchstringdefault main
The production environment's branch
isPrivatebooleandefault false
Private repositories need an installation (GitHub) or a connected GitLab or Bitbucket user
projectIdstringoptional
Folder to file it under
deploymentTypestringdefault static
static or container
frameworkstringdefault react
See Frameworks
runtimestringoptional
Container only
buildCommandstringdefault detected
Command that produces the build
outputDirectorystringdefault detected
Static only
rootDirectorystringoptional
Monorepo subdirectory
environmentVarsobjectoptional
String values only
containerPortnumberdefault detected
Container only
memorystringdefault 512Mi
See Limits
cpustringoptional
Container only
minInstancesnumberdefault 0
0 to 5
maxInstancesnumberdefault 10
1 to 100, plan-capped
concurrencynumberdefault 80
Requests served per instance
cpuTargetnumberdefault 80
Percentage that triggers a scale-up
regionstringoptional
See Limits
customDomainstringoptional
Can be added later
autoDeployOnPushbooleanoptional
Deploy on every push
autoDeployBranchesstring[]optional
Branches that auto-deploy
autoDeleteStaleEnvsbooleanoptional
Remove environments for deleted branches
curl -X POST https://api.light-cloud.com/api/applications/create \
  -H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "shop",
    "githubRepoUrl": "https://github.com/acme/shop",
    "githubBranch": "main",
    "deploymentType": "container",
    "framework": "nextjs",
    "runtime": "nodejs",
    "buildCommand": "npm run build",
    "environmentVars": { "NODE_ENV": "production" },
    "memory": "512Mi",
    "maxInstances": 5
  }'
201ResponseThe created application
{
  "id": "app_4kQ2",
  "name": "shop",
  "status": "pending",
  "url": "https://main-shop-acme.light-cloud.io"
}

Create from an upload#

POST/api/applications/create-from-upload

Builds an application from an archive instead of a repository. Nothing auto-deploys afterwards, since there is no repository to watch.

permission
create:projects

Parameters

namestringrequired
Becomes part of the generated subdomain
uploadIdstringrequired
From the uploads flow
deploymentTypestringrequired
static or container
projectIdstringoptional
Folder to file it under
frameworkstringoptional
Overrides detection
runtimestringoptional
Container only
buildCommandstringoptional
Command that produces the build
outputDirectorystringoptional
Static only
startCommandstringoptional
Container only
environmentVarsobjectoptional
String values only
curl -X POST https://api.light-cloud.com/api/applications/create-from-upload \
  -H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "marketing-site",
    "uploadId": "upl_8Xa1",
    "deploymentType": "static",
    "outputDirectory": "."
  }'
201ResponseThe created application
{
  "id": "app_9Lm3",
  "name": "marketing-site",
  "source_type": "upload",
  "status": "pending"
}

Deploy#

POST/api/applications/deploy

Builds the current head of the environment's branch and releases it. Returns as soon as the deployment starts — poll status for the outcome.

permission
update:projects

Parameters

applicationIdstringrequired
The application to deploy
environmentIdstringoptional
Defaults to production
targetOrganisationIdstringsession only
Required when using a session token
curl -X POST https://api.light-cloud.com/api/applications/deploy \
  -H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"applicationId": "app_4kQ2"}'
200ResponseThe deployment that just started
{
  "id": "dep_9f2a",
  "environment_id": "env_7Tz",
  "status": "pending",
  "commit_sha": "9f3c1ab",
  "started_at": "2026-08-28T07:00:12.000Z"
}

Rename#

POST/api/applications/rename

Renaming changes the generated subdomain, and the old URL stops resolving.

permission
update:projects

Parameters

applicationIdstringrequired
The application to rename
namestringrequired
The new name
curl -X POST https://api.light-cloud.com/api/applications/rename \
  -H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"applicationId": "app_4kQ2", "name": "storefront"}'
200ResponseThe updated application
{ "id": "app_4kQ2", "name": "storefront", "url": "https://main-storefront-acme.light-cloud.io" }

Move#

POST/api/applications/move

Files the application under a different folder.

permission
update:projects

Parameters

applicationIdstringrequired
The application to move
targetFolderIdstringrequired
Folder id, or null for the root
curl -X POST https://api.light-cloud.com/api/applications/move \
  -H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"applicationId": "app_4kQ2", "targetFolderId": "prj_2Bd"}'
200ResponseThe updated application
{ "id": "app_4kQ2", "project_id": "prj_2Bd" }

Delete#

DELETE/api/applications/delete

Tears down every environment. Not reversible, and issued as a POST despite the verb shown here.

permission
delete:projects

Parameters

applicationIdstringrequired
The application to delete
targetOrganisationIdstringsession only
Required when using a session token
curl -X POST https://api.light-cloud.com/api/applications/delete \
  -H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"applicationId": "app_4kQ2"}'
200ResponseDeletion accepted
{ "message": "Application deleted" }

Custom domains#

Each of these takes either applicationId (which targets the production environment) or environmentId. See Custom domains for the DNS records to create.

POST/api/applications/add-domain

Attaches a domain and starts certificate issuance. Certificates are issued asynchronously — poll check-domain for progress.

permission
update:projects

Parameters

applicationIdstringone of two
Targets the production environment
environmentIdstringone of two
Targets a specific environment
domainstringrequired
The hostname to attach
curl -X POST https://api.light-cloud.com/api/applications/add-domain \
  -H "Authorization: Bearer $LIGHT_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"applicationId": "app_4kQ2", "domain": "shop.example.com"}'
200ResponseDomain attached, verification pending
{
  "domain": "shop.example.com",
  "dns_verified": false,
  "certificate_status": "provisioning"
}
EndpointExtra parametersDescription
POST /api/applications/check-domainReports DNS and certificate state
POST /api/applications/update-domainnewDomainReplaces the attached domain
POST /api/applications/retry-domainRetries a failed verification
POST /api/applications/remove-domainrevertToAutoSubdomain (default true)Detaches it

Repository helpers#

EndpointDescription
POST /api/applications/list-repo-directoriesFolders in a repository, for root-directory pickers
POST /api/applications/public-branchesBranches of a public repository, no installation needed
GET /api/applications/lookup/:subdomainWhich application owns a subdomain

Related#

EnvironmentsBranches, variables, scaling, and logs.DeploymentsHistory and rollback.GitHubMaking a private repository reachable.