Skip to main content
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 loadingPayload: { 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

{
  "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
{
  "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 accessSource: ChatGPT account integrations

Directory Apps

Public apps available in the app directorySource: 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 appfalse: User needs to install/authorize the app via installUrltrue: App is ready to use
​
isEnabled
boolean
Indicates whether the app is enabled in Codex configApps 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