API 参考

Open Connector 有两个 API 平面。请按调用者身份选择：Agent 使用项目 API Key；控制台使用已登录用户的会话。新集成默认使用原生 Agent API。

实时 API 文档

文档	URL	认证方式
Open Connector Scalar UI	api.openconnector.dev/api/v1/	受保护操作使用项目 API Key
Open Connector API	api.openconnector.dev/api/v1/spec.json	文档公开
Console Scalar UI	api.openconnector.dev/api/v1/console	受保护操作使用 Better Auth 会话

服务端从处理请求的同一份运行时 API Contract 生成这些文档。不要复制静态端点清单；部署版本的精确 Schema 以这里为准。

Agent 平面

每次原生 Open Connector API 请求都使用项目 API Key：

curl "https://api.openconnector.dev/api/v1/toolkits?limit=20" \
  -H "x-api-key: $OPEN_CONNECTOR_API_KEY"

原生 API 包含连接器发现、Auth Config、连接与工具调用。已部署版本的准确请求与响应 Schema 请以顶部的实时 Scalar 文档为准。

常见 Agent 流程

为连接器创建 Auth Config。
为用户创建已连接账户（或托管连接链接）。
针对该连接调用工具。

curl -X POST "https://api.openconnector.dev/api/v1/tools/GITHUB_ISSUES_CREATE/execute" \
  -H "x-api-key: $OPEN_CONNECTOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connectedAccountId": "conn_...",
    "arguments": {"owner": "acme", "repo": "support", "title": "Issue created through Open Connector"}
  }'

连接生命周期和错误处理请参阅已连接账户与调用工具。

Composio 兼容性

已有 Composio SDK 集成可使用 https://api.openconnector.dev/composio/api/v3.1/ 兼容层。新集成请使用原生 /api/v1 API 和 Open Connector SDK。

控制台平面

公开的 Console API 挂载在 /api/v1/console，使用 Better Auth Session Cookie，只面向管理控制台或可信的管理工具，不面向 AI Agent。

项目 API Key、组织、项目、账单和设置的管理都属于这个会话认证平面。需要程序化调用时，请先检查 Console Scalar UI，确保路由和请求体与当前部署的 contract 一致。

认证边界

调用者	凭证	范围
Agent / 后端服务	`x-api-key: oc_...`	一个项目及其连接
控制台用户	Better Auth 会话 Cookie	用户拥有权限的组织
OAuth 回调	Open Connector 创建的签名 state	仅正在进行的连接

不要把项目 API Key 交给不受信任的浏览器，也不要让 Agent 代码使用控制台 session cookie。

自托管实例

将 https://api.openconnector.dev 替换为您的服务公开 origin，路由保持不变：

https://connector.example.com/api/v1/spec.json

OAuth 回调 base 也必须可从公网访问。若要迁移 Composio Client，请在相同公开 origin 下增加 /composio/api/v3.1/；请参阅环境变量和部署到 Cloudflare。