---
title: "Create an App"
method: POST
path: "/smartapps"
tags: ["SmartApps"]
---

# Create an App

`POST /smartapps`

## Request

- Base URL: `https://api.smartthings.com/v1`
- URL: `https://api.smartthings.com/v1/smartapps`
- Auth: OAuth 2
  - Implicit: `https://auth-global.api.smartthings.com`
  - Scopes: `w:smartapps`
- TypeScript: <https://skmtc.dev/smartthings/apis/smartthings-api/docs/smartapps/post.ts> (a function with typed inputs; its response is checked against the schema)

Create an app owned by an account with the provided details. If the accountId query param
is not provided, the app will be created under the default account of the user making the request.

## Query parameters

- `accountId` string, uuid

## Headers

- `Authorization` string, string, required

## Request body

- CreateSmartAppRequest
  - `appName` string, ^[a-z0-9.-_]{1,250}$, required: A globally unique, developer-defined identifier for an app. It is alpha-numeric, may contain dashes, underscores, periods, and must be less then 250 characters long.
  - `displayName` string, required: A default display name for an app.
  - `description` string, required: A default description for an app.
  - `singleInstance` boolean: Inform the installation systems that a particular app can only be installed once within a user's account.
  - `iconImage` IconImage: A default icon image for the app.
    - `url` string, uri: A default icon image url for an app. https url required.
  - `appType` 'API_ONLY', required: Denotes the type of app. Only API_ONLY is supported.
  - `principalType` 'LOCATION': Denotes the principal type to be used with the app. Only the LOCATION principal type is supported.
  - `classifications` AppClassification[], required: An App maybe associated to many classifications. A classification drives how the integration is presented to the user in the SmartThings mobile clients. These classifications include: * AUTOMATION - Denotes an integration that should display under the "Automation" tab in mobile clients. * SERVICE - Denotes an integration that is classified as a "Service". * DEVICE - Denotes an integration that should display under the "Device" tab in mobile clients. * CONNECTED_SERVICE - Denotes an integration that should display under the "Connected Services" menu in mobile clients. * HIDDEN - Denotes an integration that should not display in mobile clients * LABS - Denotes an ingration that should display under the "Labs" menu in the modile clients.
  - `apiOnly` CreateOrUpdateApiOnlyRequest: Details related to an ApiOnly implementation. This model should only be specified for apps of type API_ONLY.
    - `targetUrl` string: Optional target url to receive events. Url scheme must be https.
    - `privacyPolicyUrl` string: Link to the apps privacy policy. Url scheme must be https.
  - `oauth` AppOAuth
    - `clientName` string: A name given to the OAuth Client.
    - `scope` string[]: A list of SmartThings API OAuth scope identifiers that may be required to execute your integration.
    - `redirectUris` string[]: A list of redirect URIs for API_ONLY apps.
    - `corsDomains` string[]: A list of CORS domains.
  - `ui` AppUISettings: A collection of settings to drive user interface in SmartThings clients. Currently, only applicable for LAMBDA_SMART_APP and WEBHOOK_SMART_APP app types.
    - `pluginId` string, ^[a-zA-Z._]{1,99}$
    - `pluginUri` string, uri
    - `dashboardCardsEnabled` boolean, required
    - `preInstallDashboardCardsEnabled` boolean, required

## Response `200`

An app model.

- CreateSmartAppResponse: A response object containing the newly created App and OAuth client details.
  - `app` SmartApp
    - `appName` string, ^[a-z0-9.-_]{1,250}$: A user defined unique identifier for an app. It is alpha-numeric, may contain dashes, underscores, periods, and be less then 250 characters long. It must be unique within your account.
    - `appId` string, uuid: A globally unique identifier for an app.
    - `appType` 'API_ONLY': Denotes the type of app. Only API_ONLY is supported.
    - `principalType` 'LOCATION': Denotes the principal type to be used with the app. Only the LOCATION principal type is supported.
    - `classifications` AppClassification[]: An App maybe associated to many classifications. A classification drives how the integration is presented to the user in the SmartThings mobile clients. These classifications include: * AUTOMATION - Denotes an integration that should display under the "Automation" tab in mobile clients. * SERVICE - Denotes an integration that is classified as a "Service". * DEVICE - Denotes an integration that should display under the "Device" tab in mobile clients. * CONNECTED_SERVICE - Denotes an integration that should display under the "Connected Services" menu in mobile clients. * HIDDEN - Denotes an integration that should not display in mobile clients * LABS - Denotes an ingration that should display under the "Labs" menu in the modile clients.
    - `displayName` string: A default display name for an app.
    - `description` string: A default description for an app.
    - `singleInstance` boolean: Inform the installation systems that a particular app can only be installed once within a user's account.
    - `iconImage` IconImage: A default icon image for the app.
      - `url` string, uri: A default icon image url for an app. https url required.
    - `installMetadata` object: System generated metadata that impacts eligibility requirements around installing an App.
    - `owner` Owner: A typed model which provides information around ownership of a specific domain.
      - `ownerType` 'USER' | 'SYSTEM' | 'IMPLICIT' | 'ACCOUNT', required: The type of owner that owns this entity. "Account" refers specifically to a coterie account ID.
      - `ownerId` string, required: A global identifier for owner.
    - `createdDate` string, date-time: A UTC ISO-8601 Date-Time String
    - `lastUpdatedDate` string, date-time: A UTC ISO-8601 Date-Time String
    - `apiOnly` ApiOnly: Details specific to an ApiOnly implementation.
      - `subscription` AppSubscription: A subscription that defines where you would like to receive events.
        - `targetUrl` string: The url endpoint that you want to receive events. Url scheme must be https.
        - `targetStatus` 'PENDING' | 'CONFIRMED': The registration status of a target url.
      - `privacyPolicyUrl` string: Link to the apps privacy policy. Url scheme must be https.
    - `ui` AppUISettings: A collection of settings to drive user interface in SmartThings clients. Currently, only applicable for LAMBDA_SMART_APP and WEBHOOK_SMART_APP app types.
      - `pluginId` string, ^[a-zA-Z._]{1,99}$
      - `pluginUri` string, uri
      - `dashboardCardsEnabled` boolean, required
      - `preInstallDashboardCardsEnabled` boolean, required
  - `oauthClientId` string, uuid: The OAuth Client ID.
  - `oauthClientSecret` string, uuid: The OAuth Client Secret.

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden
- `422`: Unprocessable Entity
- `429`: Too many requests
- `default`: Unexpected error

## Changes

- **2026-11-07** `2788a4236800`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/smartthings/apis/smartthings-api/changes/smartapps/post.md)

---

[API](https://skmtc.dev/smartthings/apis/smartthings-api.md) - [All operations](https://skmtc.dev/smartthings/apis/smartthings-api/llms.txt) - [OpenAPI document](https://skmtc.dev/smartthings/apis/smartthings-api/revisions/2788a4236800?raw)