# How to Add Apps to a Plugin in the OpenAI Plugins Repository

> Learn how to add apps to a plugin in the OpenAI plugins repository. Edit the .app.json file to register your new app ID and boost your plugin's functionality.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-06-28

---

**To add an app to a plugin in the OpenAI Plugins repository, edit the [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) file in the plugin directory to register the new app ID, then optionally bump the version in [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json).**

Adding apps to a plugin requires no code changes in the OpenAI Plugins monorepo. Each plugin stores its app registry in a JSON configuration file that the runtime loads at startup, making app registration a pure data-entry task. This guide explains the exact file paths and JSON structures required to extend any plugin with new apps.

## Understanding the Plugin App Registry

In the `openai/plugins` repository, every plugin is a self-contained directory under `plugins/`. The app registry lives in a file named [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) at the root of the plugin folder. The plugin metadata file located at `plugins/<plugin>/.codex-plugin/plugin.json` points to this registry via the field:

```json
"apps": "./.app.json"

```

At runtime, the generic loader reads [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) and exposes the app IDs to the OpenAI Connector service. Because the system reads these IDs dynamically, you only need to update the JSON file to add functionality.

## Step-by-Step Guide: How to Add Apps to a Plugin

Follow these four steps to register a new app in any plugin.

### 1. Obtain a New App ID

App IDs are generated by the OpenAI Connector service when you register a new app in the Marketplace. For internal development, you may use a placeholder following the format `connector_<random-hex>` or `asdk_app_<hash>`.

### 2. Edit the Plugin's [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json)

Navigate to `plugins/<plugin>/.app.json` and insert a new entry under the top-level `"apps"` object. Use snake-case naming that matches the plugin's internal naming convention.

### 3. Update the Plugin's [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) (Optional)

If the new app changes the plugin's public API or you intend to publish a new version, increment the `"version"` field in `plugins/<plugin>/.codex-plugin/plugin.json`.

### 4. Commit the Changes

Submit your changes to the repository. The CI pipeline runs validation checks to ensure the JSON is well-formed and that all referenced app IDs are unique across the registry.

## Code Examples: Adding Apps to Existing Plugins

### Adding an App to the Google Calendar Plugin

To add a new app named `google-calendar-export` to the Google Calendar plugin, edit [`plugins/google-calendar/.app.json`](https://github.com/openai/plugins/blob/main/plugins/google-calendar/.app.json):

```json
{
  "apps": {
    "google-calendar": {
      "id": "connector_947e0d954944416db111db556030eea6"
    },
    "google-calendar-export": {
      "id": "connector_5f3a1b2c9d7e4a8b9c0d1e2f3a4b5c6d"
    }
  }
}

```

Optionally bump the version in [`plugins/google-calendar/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/google-calendar/.codex-plugin/plugin.json):

```json
{
  "name": "google-calendar",
  "version": "1.0.3",
  "description": "Google Calendar connector",
  "apps": "./.app.json"
}

```

### Adding an App to the ZoomInfo Plugin

For the ZoomInfo plugin located at `plugins/zoominfo/`, add entries to [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) following the same structure:

```json
{
  "apps": {
    "zoominfo": {
      "id": "asdk_app_698a340b9230819188ba5a5eea79022d"
    },
    "zoominfo-company-search": {
      "id": "asdk_app_9f1c2d3e4b5a6c7d8e9f0a1b2c3d4e5f"
    }
  }
}

```

## Summary

- **App registry location**: Each plugin stores its apps in `plugins/<plugin>/.app.json`.
- **Metadata reference**: The file `plugins/<plugin>/.codex-plugin/plugin.json` links to the registry via `"apps": "./.app.json"`.
- **No code required**: Adding an app is a data-entry task; the runtime loads IDs from JSON at startup.
- **Validation**: The repository CI ensures JSON validity and ID uniqueness automatically.
- **Versioning**: Update the `version` field in [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) only when publishing API changes.

## Frequently Asked Questions

### What is the [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) file?

The [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) file is the app registry for a specific plugin. It contains a top-level `"apps"` object that maps snake-case app names to their connector IDs, which the OpenAI Connector service uses to route requests at runtime.

### Do I need to write code to add a new app to a plugin?

No. According to the openai/plugins source code, the repository contains no custom code for handling individual apps. The generic loader reads the [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) file at runtime, so adding an app requires only editing that JSON file.

### Where do app IDs come from?

Production app IDs are generated by the OpenAI Connector service when you register the app in the Marketplace. For local development or testing, you can use placeholder IDs following the patterns `connector_<random-hex>` or `asdk_app_<hash>`.

### When should I update the plugin version?

Increment the `"version"` field in `plugins/<plugin>/.codex-plugin/plugin.json` only when the new app changes the plugin's public API or when you are ready to publish a new release. Pure app additions that do not affect the API surface do not require version bumps.