---
sidebar_label: Application settings
toc_max_heading_level: 3
doc_id: a6288845-0843-4c8b-a939-b7e31d0b5eaa
description: >-
  Read and update an application's settings object: default branch and
  environment, asset storage location, and the linked code repository provider.
keywords:
  - application settings
  - default branch
  - default environment
  - asset repository
  - ECR
  - code repository
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Application settings

Every application carries a `settings` object: **configuration values nullplatform keeps for the application**, such as its default branch and environment, where its build assets are stored, and which code repository it's linked to. Keeping them accurate lets nullplatform resolve the right defaults and find your build assets.

You can read and update these values through the Application API. **All settings are optional**, so any field may be empty if it hasn't been set yet.

## What's in the settings object

The `settings` object groups related configuration into three blocks. A fully populated object looks like this:

```json
{
  "settings": {
    "defaults": {
      "branch": "main",
      "environment": "staging"
    },
    "asset": {
      "docker_server": {
        "uri": "registry.example.com/acme-corp/billing-api"
      },
      "ecr": {
        "uri": "123456789012.dkr.ecr.us-east-1.amazonaws.com/billing-api",
        "arn": "arn:aws:ecr:us-east-1:123456789012:repository/billing-api"
      }
    },
    "code_repository": {
      "specification_id": "7f3c910e-8138-4d65-9d09-b97d89f2c509",
      "specification_slug": "github-configuration",
      "specification_name": "GitHub",
      "specification_icon": "github",
      "provider_id": "82eee42c-46c9-4bb7-a53d-c08b027817f3"
    }
  }
}
```

### Defaults

**`defaults`** holds the values nullplatform falls back to when one isn't specified explicitly.

| Field | Description |
|---|---|
| `branch` | Default branch name for the application. |
| `environment` | Default environment name for the application. |

### Asset location

**`asset`** records where the application's build assets are stored, so nullplatform knows where to find the images it deploys.

| Field | Description |
|---|---|
| `docker_server.uri` | Location of the application's Docker server assets. |
| `asset.ecr.uri` | Amazon ECR repository URI for the application's assets. |
| `asset.ecr.arn` | Amazon ECR repository ARN for the application's assets. |

### Code repository

**`code_repository`** describes the repository provider the application is linked to. It references the [provider specification](/docs/providers/overview) (`specification_id`, `specification_slug`, `specification_name`, `specification_icon`) and the provider instance (`provider_id`).

## Read the settings

Send a [GET request](/docs/api/application-read) to the Application API. The `settings` object is included in the application's response body.

<Tabs
defaultValue="read-settings-cli"
values={[
{ label: 'CLI', value: 'read-settings-cli' },
{ label: 'cURL', value: 'read-settings-curl' },
]}>
<TabItem value="read-settings-cli">

```bash
np application get --id 123
```

</TabItem>
<TabItem value="read-settings-curl">

```bash
curl -L 'https://api.nullplatform.com/application/123' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <token>'
```

</TabItem>
</Tabs>

## Update the settings

Send a [PATCH request](/docs/api/application-update) to the Application API with the keys you want to change. For example, to set the default branch and environment:

<Tabs
defaultValue="update-settings-cli"
values={[
{ label: 'CLI', value: 'update-settings-cli' },
{ label: 'cURL', value: 'update-settings-curl' },
]}>
<TabItem value="update-settings-cli">

```bash
np application patch
  --id 123
  --body '{
    "settings": {
      "defaults": {
        "branch": "main",
        "environment": "staging"
      }
    }
  }'
```

</TabItem>
<TabItem value="update-settings-curl">

```bash
curl -L -X PATCH 'https://api.nullplatform.com/application/123' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{
  "settings": {
    "defaults": {
      "branch": "main",
      "environment": "staging"
    }
  }
}'
```

</TabItem>
</Tabs>

:::tip Updates use JSON Merge Patch
Updates to `settings` follow [JSON Merge Patch (RFC 7396)](https://datatracker.ietf.org/doc/html/rfc7396). This means you only send the keys you want to change:

- A key with a non-null value is **created or updated**.
- A key set to `null` is **deleted**.
- A key you omit is **left untouched**.
:::

:::note Deleting a setting
To clear a value, send the key with `null` rather than an empty string. For example, `{ "settings": { "defaults": { "branch": null } } }` removes the default branch while preserving every other setting.
:::

## Related resources

- [Create a new application](creating-new-application.md): set up an application and its repository
- [Update the name of your repository](update-repository-name.md): keep `repository_url` in sync after renaming