Apps (connectors)

Use app/installed to read the latest committed installed app runtime snapshot. Each result includes the app id, runtimeName (or null), effective enabled state, and callable state. An app is callable only when effective configuration enables it and at least one model-visible tool complies with the app and tool policies.

{
  "method": "app/installed",
  "id": 49,
  "params": {
    "threadId": "thread-1",
    "forceRefresh": false
  }
}
{
  "id": 49,
  "result": {
    "apps": [
      {
        "id": "demo-app",
        "runtimeName": "Demo App",
        "enabled": true,
        "callable": true
      }
    ]
  }
}

Omit threadId to use the global configuration instead of a loaded thread's configuration. Set forceRefresh: true to refresh the connector runtime snapshot before reading it. When global or workspace policy blocks app access, an observed app can still appear with enabled and callable set to false.

Use app/list to fetch available apps. In the CLI/TUI, /apps is the user-facing picker; in custom clients, call app/list directly. Each entry includes both isAccessible (available to the user) and isEnabled (enabled in config.toml) so clients can distinguish install/access from local enabled state. App entries can also include optional branding, appMetadata, and labels fields.

{ "method": "app/list", "id": 50, "params": {
  "cursor": null,
  "limit": 50,
  "threadId": "thread-1",
  "forceRefetch": false
} }
{ "id": 50, "result": {
  "data": [
    {
      "id": "demo-app",
      "name": "Demo App",
      "description": "Example connector for documentation.",
      "logoUrl": "https://example.com/demo-app.png",
      "logoUrlDark": null,
      "distributionChannel": null,
      "branding": null,
      "appMetadata": null,
      "labels": null,
      "installUrl": "https://chatgpt.com/apps/demo-app/demo-app",
      "isAccessible": true,
      "isEnabled": true
    }
  ],
  "nextCursor": null
} }

If you provide threadId, app feature gating (features.apps) uses that thread's config snapshot. When omitted, app-server uses the latest global config.

app/list returns after both accessible apps and directory apps load. Set forceRefetch: true to bypass app caches and fetch fresh data. Cache entries are only replaced when refreshes succeed.

The server also emits app/list/updated notifications whenever either source (accessible apps or directory apps) finishes loading. Each notification includes the latest merged app list.

{
  "method": "app/list/updated",
  "params": {
    "data": [
      {
        "id": "demo-app",
        "name": "Demo App",
        "description": "Example connector for documentation.",
        "logoUrl": "https://example.com/demo-app.png",
        "logoUrlDark": null,
        "distributionChannel": null,
        "branding": null,
        "appMetadata": null,
        "labels": null,
        "installUrl": "https://chatgpt.com/apps/demo-app/demo-app",
        "isAccessible": true,
        "isEnabled": true
      }
    ]
  }
}

Use app/read when you already know the app ids and need app metadata rather than installed runtime state. Pass at most 100 appIds. The server keeps only the first occurrence of each repeated id and preserves that order in both apps and missingAppIds. Unknown or inaccessible apps are returned in missingAppIds without failing the entire request.

{
  "method": "app/read",
  "id": 52,
  "params": {
    "appIds": ["demo-app", "missing-app"],
    "includeTools": true
  }
}
{
  "id": 52,
  "result": {
    "apps": [
      {
        "id": "demo-app",
        "name": "Demo App",
        "description": "Example connector for documentation.",
        "iconUrl": null,
        "iconUrlDark": null,
        "distributionChannel": null,
        "installUrl": null,
        "pluginDisplayNames": [],
        "toolSummaries": [
          {
            "name": "search",
            "title": "Search",
            "description": "Search the app.",
            "isEnabled": true,
            "disabledReason": null,
            "isReadOnly": true
          }
        ]
      }
    ],
    "missingAppIds": ["missing-app"]
  }
}

Set includeTools: true to request display-only public tool summaries. The metadata response doesn't include installed app runtime state or authorize a tool call; use app/installed to check effective enabled and callable state.