Apps API

Overview

The Apps API lets you create and list applications in your Stormkit account. It is useful for automating app provisioning and for discovering appId values that are required by other API endpoints.

---

POST /v1/app

Creates a new application and links it to a source-code repository.

Base URL: https://api.stormkit.io

Authentication: Team-level or user-level API key passed as the Authorization header. To generate one: Profile → Account → API Keys or Team → Settings. When using a user-level key, include teamId in the request body to specify which team the application belongs to.

Request body

Field	Type	Required	Description
teamId	string	No	ID of the team to create the application under. Required when using a user-level API key; ignored when using a team-level key (the team is derived from the key).
repo	string	No	Repository path in owner/slug format (e.g. acme/my-app). Omit to create a bare application.
provider	string	No	Source-code provider. One of github, gitlab, bitbucket. Required when repo is set.
displayName	string	No	Human-readable application name. Must contain only alphanumeric characters, hyphens, and underscores, with no consecutive hyphens. Auto-generated when omitted.

Response — 200 OK

Field	Type	Description
app	App	The newly created application.

App object:

Field	Type	Description
id	string	Unique application ID.
displayName	string	Human-readable name of the application.
repo	string	Repository path (e.g. github/acme/my-app). Empty when isBare is true.
isBare	boolean	true when no repository is linked.
userId	string	ID of the user who owns the application.
teamId	string	ID of the team the application belongs to.
defaultEnvId	string	ID of the default environment. Use this as envId in environment-scoped endpoints.
createdAt	string	Unix timestamp (seconds) when the application was created.

Error responses

Status	Condition
400	Invalid displayName (regex mismatch or reserved word), or unsupported provider.
403	Missing/invalid API key, or the key scope is below team level.
500	Internal server error.

Examples

# Create an app linked to a GitHub repository
curl -X POST \
     -H 'Authorization: <team_api_key>' \
     -H 'Content-Type: application/json' \
     -d '{"repo":"acme/my-app","provider":"github"}' \
     'https://api.stormkit.io/v1/app'

# Create a bare application (no repository) with a custom display name
curl -X POST \
     -H 'Authorization: <team_api_key>' \
     -H 'Content-Type: application/json' \
     -d '{"displayName":"my-bare-app"}' \
     'https://api.stormkit.io/v1/app'

// Example response
{
  "app": {
    "id": "1510",
    "displayName": "my-app",
    "repo": "github/acme/my-app",
    "isBare": false,
    "userId": "42",
    "teamId": "7",
    "defaultEnvId": "305",
    "createdAt": "1742723400"
  }
}

Notes

• After creating the app, use GET /v1/app with the returned id to poll for the defaultEnvId once the first environment has been provisioned.
• For GitHub, the GitHub App must be installed on the target account/organisation before deployments can access the repository. If the repository does not appear when deploying, go to Home → Create New App → Import From GitHub → Connect more repositories to grant Stormkit access to additional repos.
• For GitLab and Bitbucket, an OAuth token for the account must be connected via the Stormkit UI before deployments can clone the repository.

---

GET /v1/apps

Returns a paginated list of applications belonging to the authenticated user.

Base URL: https://api.stormkit.io

Authentication: User or Team level API key passed as the Authorization header (no Bearer prefix required). To generate one: Profile → Account → API Keys.

Query parameters

Parameter	Type	Required	Default	Description
teamId	number	Yes	—	ID of the team to scope results to. The API key owner must be a member.
from	number	No	0	Pagination offset. Must be ≥ 0.
repo	string	No	—	Exact case-insensitive match on the repository path (e.g. github/org/repo).
displayName	string	No	—	Exact case-insensitive match on the application display name.

repo and displayName can be combined and are applied as AND conditions.

Response — 200 OK

Field	Type	Description
apps	App[]	Array of application objects for the current page.
hasNextPage	boolean	true when more results exist. To fetch the next page, add from=<current_offset + len(apps)>.

App object:

Field	Type	Description
id	string	Unique application ID. Use this as appId in other endpoints.
displayName	string	Human-readable name of the application.
repo	string	Repository path (e.g. github/org/repo). Empty when isBare is true.
isBare	boolean	true when no repository is linked.
userId	string	ID of the user who owns the application.
teamId	string	ID of the team the application belongs to.
defaultEnvId	string	ID of the default environment. Use this as envId in environment-scoped endpoints.
createdAt	string	Unix timestamp (seconds) when the application was created.

Error responses

Status	Condition
400	Missing or invalid parameter (e.g. teamId omitted, non-integer).
403	Missing/invalid API key, or user is not a member of the given team.
500	Internal server error.

Pagination

The page size is fixed at 20 items. To iterate all pages:

1. Start with from=0.
2. If hasNextPage is true, set from = from + len(apps) and repeat.
3. Stop when hasNextPage is false.

Examples

# First page
curl -X GET \
     -H 'Authorization: <api_key>' \
     'https://api.stormkit.io/v1/apps?teamId=7'

# Second page
curl -X GET \
     -H 'Authorization: <api_key>' \
     'https://api.stormkit.io/v1/apps?teamId=7&from=20'

# Exact match by repository
curl -X GET \
     -H 'Authorization: <api_key>' \
     'https://api.stormkit.io/v1/apps?teamId=7&repo=github/acme/my-app'

# Exact match by display name
curl -X GET \
     -H 'Authorization: <api_key>' \
     'https://api.stormkit.io/v1/apps?teamId=7&displayName=my-app-abc123'

// Example response
{
  "apps": [
    {
      "id": "1510",
      "displayName": "my-app-abc123",
      "repo": "github/acme/my-app",
      "isBare": false,
      "userId": "42",
      "teamId": "7",
      "defaultEnvId": "305",
      "createdAt": "1700489144"
    }
  ],
  "hasNextPage": false
}

---

GET /v1/app/{id}

Returns a single application. This is also an alias for GET /v1/app with an app-level API key.

Base URL: https://api.stormkit.io

Authentication: App-level, user-level, or team-level API key passed as the Authorization header. When using a user or team-level key, provide the application ID in the request path (for example, GET /v1/app/{appId}), and the authenticated principal must be a member of the team that owns the application. For backwards compatibility, the server also accepts appId as a query parameter.

Response — 200 OK

Field	Type	Description
app	App	The application object.

App object:

Field	Type	Description
id	string	Unique application ID.
displayName	string	Human-readable name of the application.
repo	string	Repository path (e.g. github/org/repo). Empty when isBare is true.
isBare	boolean	true when no repository is linked.
userId	string	ID of the user who owns the application.
teamId	string	ID of the team the application belongs to.
defaultEnvId	string	ID of the default environment. Use this as envId in environment-scoped endpoints.
createdAt	string	Unix timestamp (seconds) when the application was created.

Error responses

Status	Condition
403	Missing/invalid API key, or the authenticated principal is not a team member.
404	No application found with the given ID.
500	Internal server error.

Examples

# Using an app-level key (appId is derived from the token)
curl -X GET \
     -H 'Authorization: <app_api_key>' \
     -H 'Content-type: application/json' \
     'https://api.stormkit.io/v1/app'

# Using a user or team-level key (appId must be provided in the URL)
curl -X GET \
     -H 'Authorization: <user_or_team_api_key>' \
     -H 'Content-Type: application/json' \
     'https://api.stormkit.io/v1/app/1510'

// Example response
{
  "app": {
    "id": "1510",
    "displayName": "my-app-abc123",
    "repo": "github/acme/my-app",
    "isBare": false,
    "userId": "42",
    "teamId": "7",
    "defaultEnvId": "305",
    "createdAt": "1700489144"
  }
}

---

GET /v1/app/config

Returns the runtime configuration for published deployment matching a given hostname. This endpoint is primarily used to debug the application config.

Base URL: https://api.stormkit.io

Authentication: App-level API key passed as the Authorization header. To generate one: Your App → Your Environment → Config → Other → API Keys (app scope).

Query parameters

Parameter	Type	Required	Description
hostName	string	Yes	The hostname of the deployed application (e.g. my-app.stormkit.io).

Response — 200 OK

Returns an array of configuration objects for all matching published deployments.

Field	Type	Description
configs	Config[]	Array of runtime configuration objects.

Config object:

Field	Type	Description
deploymentId	string	ID of the published deployment.
appId	string	ID of the application.
envId	string	ID of the environment.
percentage	number	Traffic percentage routed to this deployment (0–100).
apiPathPrefix	string	URL path prefix under which serverless API functions are served.
domains	string[]	Custom domains associated with this deployment. null if none are configured.
staticFiles	object	Map of URL paths to static file metadata.
envVariables	object	Map of environment variable names to their values injected at runtime.
updatedAt	string	Unix timestamp (seconds) of the last configuration update. null if not set.

Error responses

Status	Condition
204	No published deployment found for the hostname.
403	Missing or invalid API key.
500	Internal server error.

Example

curl -X GET \
     -H 'Authorization: <app_api_key>' \
     'https://api.stormkit.io/v1/app/config?hostName=my-app.stormkit.io'

// Example response
{
  "configs": [
    {
      "deploymentId": "8241",
      "appId": "1510",
      "envId": "305",
      "percentage": 100,
      "apiPathPrefix": "/api",
      "domains": null,
      "staticFiles": {
        "/index": {
          "fileName": "index",
          "headers": {
            "content-type": "text/html; charset=utf-8"
          }
        }
      },
      "envVariables": {
        "NODE_ENV": "production",
        "SK_APP_ID": "1510",
        "SK_ENV": "production"
      },
      "updatedAt": null
    }
  ]
}