Apps

Connector app discovery and invocation

Apps (connectors) integrate external services with Codex. They expose tools and data sources that the agent can use during conversations.

List Apps

Fetch available apps with optional pagination and thread context.

Method

app/list

Parameters

cursor · string

Opaque pagination cursor from previous response

limit · number

Page size (server defaults if unset)

threadId · string

Thread ID for feature gating (uses global config if omitted)

forceRefetch · boolean · default: false

Bypass app caches and fetch fresh data from sources

Response

data · AppInfo[]

Array of app metadata

nextCursor · string | null

Cursor for next page (null if no more pages)

Notifications

app/list/updated · notification

Emitted when app sources finish loading

Payload: { data: AppInfo[] }

App Object

id · string

Unique app identifier (connector ID)

name · string

Human-readable app name

description · string

App description

logoUrl · string

Light theme logo URL

logoUrlDark · string | null

Dark theme logo URL

distributionChannel · string | null

Distribution channel identifier

branding · object | null

App branding metadata

appMetadata · object | null

Additional app metadata

labels · string[] | null

App category labels

installUrl · string

URL to install or configure the app

isAccessible · boolean

Whether the user has access to this app

isEnabled · boolean

Whether the app is enabled in config

Example

Request

{
  "method": "app/list",
  "id": 50,
  "params": {
    "cursor": null,
    "limit": 50,
    "threadId": "thr_123",
    "forceRefetch": false
  }
}

Invoking an App

To invoke an app, include $<app-slug> in the text input and add a mention input item with the app path.

The slug is derived from the app name: lowercase with non-alphanumeric characters replaced by -.

Examples:

• “GitHub” becomes $github
• “Demo App” becomes $demo-app

turn/start with app

{
  "method": "turn/start",
  "id": 51,
  "params": {
    "threadId": "thr_123",
    "input": [
      {
        "type": "text",
        "text": "$github List open issues in the main repository."
      },
      {
        "type": "mention",
        "name": "GitHub",
        "path": "app://github"
      }
    ]
  }
}

Always include the mention input item so the server uses the exact app://<connector-id> path rather than guessing by name.

App Sources

Apps are loaded from two sources:

Accessible Apps

Apps the user has authorized and can access

Source: ChatGPT account integrations

Directory Apps

Public apps available in the app directory

Source: ChatGPT app marketplace

The app/list response merges both sources. Cache entries are only replaced when refetches succeed.

App Availability

isAccessible · boolean

Indicates whether the user has authorized this app

false: User needs to install/authorize the app via installUrl

true: App is ready to use

isEnabled · boolean

Indicates whether the app is enabled in Codex config

Apps can be disabled via config.toml even if accessible.

App Configuration

Apps can be configured in config.toml:

[apps.github]
enabled = true
destructive_enabled = true
open_world_enabled = true

[apps.github.tools]
# Per-tool configuration
[apps.github.tools.create_issue]
enabled = true
approval_mode = "auto"  # "auto", "prompt", or "approve"

Configuration Options

enabled · boolean · default: true

Enable or disable the entire app

destructive_enabled · boolean

Allow destructive operations (delete, modify)

open_world_enabled · boolean

Allow operations that affect external systems

default_tools_approval_mode · string

Default approval mode for all tools

• auto - Execute without asking
• prompt - Ask for approval
• approve - Always approve

default_tools_enabled · boolean

Enable all tools by default

Next Steps

Overview

Review the API architecture

Initialization

Initialize your connection