> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://contentful.com/developers/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful.com/_mcp/server.

`AppDefinition` is an entity type that stores all information about a single [app](/extensibility/app-framework) on the organization level. By itself this entity does not do anything. To use an app you need to create an [`AppInstallation`](/references/content-management-api/app-installations) in a selected space-environment pointing to your definition.

Definitions centralize app management within an organization. Changes to a definition will automatically be propagated to all of its installations. There is no need to update installations when updating a definition.

A definition contains information about whether the app frontend is hosted by Contentful or outside of Contentful. If the app frontend is hosted outside of Contentful, the definition will have a `src` (Third party URL or `localhost` for development as a `string`) property.
If the app is hosted by Contentful, the definition will have a `bundle` property, which is a link to an [`AppBundle`](/references/content-management-api/overview) entity. The `AppBundle` can contain just frontend assets, [Functions](/extensibility/app-framework/functions) code, or both.
It is possible for an app to have both a `bundle` and `src` property only when the app has a bundle containing just functions code (no frontend) and then is using a Third Party URL to host the frontend.

#### App definition properties

* `name`: a human-readable name of the app
* `src`: publicly available source URL of the app; requires HTTPS with exception of `localhost` (for development)
* `bundle`: a link to an `AppBundle` if hosted on Contentful
* `locations`: list of places in the web app where the app can be rendered; see below
* `parameters`: definitions of [configuration parameters](/extensibility/app-framework/app-parameters)

#### App locations

Locations are described in more detail in the [App SDK reference](/extensibility/app-framework/sdk#locations).

The `locations` property is an array of one or more of:

| Location                             | `locations` array item                                            | Description                                                                            |
| ------------------------------------ | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| [Entry field](#entry-field-location) | `{ "location": "entry-field", "fieldTypes": { "type": "Symbol" }` | Renders as an entry field editor; requires at least one field type (see below)         |
| Entry sidebar                        | `{ "location": "entry-sidebar" }`                                 | Renders in the entry sidebar                                                           |
| Entry editor                         | `{ "location": "entry-editor" }`                                  | Replaces the entire entry editor                                                       |
| Dialog                               | `{ "location": "dialog" }`                                        | Renders in a dialog window                                                             |
| App configuration                    | `{ "location": "app-config" }`                                    | Renders on the app configuration screen                                                |
| [Page](#page-location)               | `{ "location": "page" }`                                          | Renders a separate page. You can add an optional `navigationItem` property, see below. |

#### Entry field location

All valid `fieldTypes` are:

* Short text: `{ "type": "Symbol" }`
* Short text, list: `{ "type": "Array", "items": { "type": "Symbol" } }`
* Long text: `{ "type": "Text" }`
* Rich text: `{ "type": "RichText" }`
* Number, integer: `{ "type": "Integer"}`
* Number, decimal: `{ "type": "Number" }`
* Boolean: `{ "type": "Boolean" }`
* Date and time: `{ "type": "Date" }`
* Location: `{ "type": "Location" }`
* JSON object: `{ "type": "Object" }`
* Entry reference: `{ "type": "Link", "linkType": "Entry" }`
* Entry reference, list: `{ "type": "Array", "items": { "type": "Link", "linkType": "Entry" } }`
* Media reference: `{ "type": "Link", "linkType": "Asset" }`
* Media reference, list: `{ "type": "Array", "items": { "type": "Link", "linkType": "Asset" } }`

### Page location

When you add a page location in your AppDefinition, there is the possibility to add an optional `navigationItem` property to it.

```json
{
  "location": "page",
  "navigationItem": {
    "name": "My app",
    "path": "/my-app"
  }
}
```

```json
{
  "location": "page",
  "navigationItem": {
    "name": "My app",
    "path": "/my-app"
  }
}
```

If provided, a link will be added to the "Apps" navigation item in the Contentful web app pointing to your app installation.

#### Example

The following app definition is called "Hello world" which is served from `https://example.com/hello-app.html` and can be rendered both as an editing widget for short text fields and as an app configuration screen:

```json
{
  "name": "Hello world",
  "src": "https://example.com/hello-app.html",
  "locations": [
    {
      "location": "entry-field",
      "fieldTypes": [
        { "type": "Symbol" }
      ]
    },
    {
      "location": "app-config"
    }
  ]
}
```

## App definitions collection

[Get all app definitions](/references/content-management-api/app-definitions/get-all-app-definitions)

[Create a new app definition](/references/content-management-api/app-definitions/create-a-new-app-definition)

## App definition

[Get an app definition](/references/content-management-api/app-definitions/get-an-app-definition)

[Update an app definition](/references/content-management-api/app-definitions/update-an-app-definition)

[Delete an app definition](/references/content-management-api/app-definitions/delete-an-app-definition)


## API Docs

- App definitions [Get all app definitions](https://contentful.com/developers/docs/references/content-management-api/app-definitions/get-all-app-definitions.md)
- App definitions [Create a new app definition](https://contentful.com/developers/docs/references/content-management-api/app-definitions/create-a-new-app-definition.md)
- App definitions [Get an app definition](https://contentful.com/developers/docs/references/content-management-api/app-definitions/get-an-app-definition.md)
- App definitions [Update an app definition](https://contentful.com/developers/docs/references/content-management-api/app-definitions/update-an-app-definition.md)
- App definitions [Delete an app definition](https://contentful.com/developers/docs/references/content-management-api/app-definitions/delete-an-app-definition.md)

## OpenAPI Specification

The raw OpenAPI 3.1 specification for this API is available at:
- [OpenAPI JSON](https://contentful.com/developers/docs/openapi.json)
- [OpenAPI YAML](https://contentful.com/developers/docs/openapi.yaml)