Apps API · Connect
Connect: 21 个接口
GET /api/v1/connect/agents/me/connections
List available connections
权限(scope): connections:connection:read · 调用方式: appToken · operationId: list-connect-available-connections
Required app scope: connections:connection:read.
回包
200OK —application/json·DataResponseListConnectConnectionItemBodydefaultError —application/problem+json·D8Error
POST /api/v1/connect/agents/usable-connections/query
Query the connections agents can use
权限(scope): connections:connection:read · 调用方式: appToken · operationId: query-connect-agent-usable-connections
Required app scope: connections:connection:read.
Read-only (POST for the request body), batch, metadata-only lookup of the connections each requested agent can actually use in the caller's org: exactly the set the agent's own GET /api/v1/connect/agents/me/connections returns (a live authorization of the agent on a live connection of the org — org connections are not implicitly usable without authorization), filtered by statuses (default ["active"]). No credentials. data has one entry per requested agent after de-duplication, in request order, each carrying exactly one of connections or error: MEMBER_NOT_FOUND (unknown, foreign-org, removed or departed — not distinguished), MEMBER_NOT_AN_AGENT, or FORBIDDEN (the caller is not the agent itself, not its owner and lacks ai.manage; an agent caller may only read itself). Whole-request errors: 400 for an invalid body (empty or missing list, more than 50 ids, malformed UUID, unknown status; syntactically malformed JSON or wrong JSON types are the framework's 422), 401/403 for authentication / org membership, 503 when the platform is unavailable. PAT-authenticated requests are additionally scope-gated (connections:connection:read); sessions and agent keys are not scope-checked. org_id is derived from the principal, never client-supplied.
请求体
application/json · QueryConnectAgentUsableConnectionsRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
agent_member_ids |
array of string (uuid) | 是 | Agent member UUIDs, 1..50 as sent. Duplicates are collapsed (first occurrence keeps its position). An empty list, more than 50 ids or a malformed UUID rejects the whole request with 400. |
statuses |
array of string: active, needs_reauth, error, expired, pending, revoked |
Connection status filter; a connection is returned when it matches any value. Omitted or empty = ["active"]. needs_reauth = status error WITH a pending re-authorization; error = status error WITHOUT one; the rest match the stored status. An unknown value rejects the whole request with 400. |
回包
200OK —application/json·DataResponseListConnectAgentUsableConnectionsEntryBodydefaultError —application/problem+json·D8Error
GET /api/v1/connect/agents/{agent_member_id}/connections
List connections an agent is authorized to use
权限(scope): connections:connection:read · 调用方式: appToken · operationId: list-connect-agent-connections
Required app scope: connections:connection:read.
Forward lookup: the connectors a specific agent is authorized to use, for the composer connector panel in a DM. Gated on the caller being allowed to DM the agent (the agent's DM policy — owner always passes); callers who cannot DM the agent get CONNECT_AGENT_DM_NOT_AUTHORIZED (403). An unknown or foreign-org agent_member_id is 404 MEMBER_NOT_FOUND (not distinguished). org_id is derived from the principal, never client-supplied.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
agent_member_id |
path | string (uuid) | 是 | Agent member UUID |
conversation_id |
query | string (uuid) | 是 | Conversation the panel is opened in; the server derives display scope (group hides personal-scope connectors) and verifies caller membership from it |
回包
200OK —application/json·DataResponseListConnectConnectionItemBodydefaultError —application/problem+json·D8Error
GET /api/v1/connect/connections
List connections
权限(scope): connections:connection:read · 调用方式: appToken · operationId: list-connect-connections
Required app scope: connections:connection:read.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
application_id |
query | string (uuid) | Application UUID | |
status |
query | string | Connection status filter |
回包
200OK —application/json·DataResponseListConnectConnectionItemBodydefaultError —application/problem+json·D8Error
POST /api/v1/connect/connections
Create OAuth connection
权限(scope): connections:connection:write · 调用方式: appToken · operationId: create-connect-connection
Required app scope: connections:connection:write.
请求体
application/json · CreateConnectConnectionRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
application_slug |
string | 是 | Application slug |
display_name |
string | Connection display name | |
mcp_server |
ConnectCreateConnectionMcpServerInput |
Per-connection MCP server configuration (connector_kind=mcp only); omit for http, provider-hosted and managed connections | |
oauth_client_id |
string | Per-connection (BYO) OAuth client ID; required only for applications that need per-connection client credentials (e.g. Shopify custom apps) | |
oauth_client_secret |
string | Per-connection (BYO) OAuth client secret; required only for applications that need per-connection client credentials (e.g. Shopify custom apps). Stored encrypted, never returned in any response. | |
oauth_config_id |
string | Per-connection Facebook Login for Business configuration ID; required only for applications that declare requires_oauth_config_id (e.g. Meta with your own app). Stored encrypted and not returned in connection records; it appears only as the config_id parameter of the returned redirect_url. | |
oauth_instance_host |
string | Per-connection OAuth host for per-tenant connectors (e.g. Shopify's {shop}.myshopify.com); required only when the application declares requires_oauth_instance_host | |
org_id |
string (uuid) | Organization UUID | |
owner_member_id |
string (uuid) | Owner member UUID | |
owner_scope |
string | 是 | Owner scope |
回包
200OK —application/json·DataResponseConnectCreateConnectionDataBodydefaultError —application/problem+json·D8Error
POST /api/v1/connect/connections/api-key
Create API key connection
权限(scope): connections:connection:write · 调用方式: appToken · operationId: create-connect-api-key-connection
Required app scope: connections:connection:write.
请求体
application/json · CreateConnectAPIKeyConnectionRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
api_key |
string | API key credential (single-value shortcut; optional when the multi-field 'fields' map is used instead) | |
application_slug |
string | 是 | Application slug |
base_url |
string | Per-connection base URL (required for applications with no fixed host, e.g. Jenkins) | |
display_name |
string | Connection display name | |
fields |
object | Multi-field API key credential values keyed by connect-field name (see the application's connect-fields schema: the provider's field names for provider-hosted api_key toolkits, or api_key/username/base_url for managed api_key connectors); used exactly as sent | |
mcp_server |
ConnectCreateConnectionMcpServerInput |
Per-connection MCP server configuration (connector_kind=mcp, none/bearer auth only; bearer/api_key is remote_http-only — a stdio server must use auth_type=none with no api_key); omit for ordinary api_key and provider-hosted connections | |
org_id |
string (uuid) | Organization UUID | |
owner_member_id |
string (uuid) | Owner member UUID | |
owner_scope |
string | 是 | Owner scope |
username |
string | Username (required when the application's api_key_auth_style is 'basic', e.g. Jenkins) |
回包
200OK —application/json·DataResponseConnectConnectionItemBodydefaultError —application/problem+json·D8Error
GET /api/v1/connect/connections/{connection_id}
Get connection
权限(scope): connections:connection:read · 调用方式: appToken · operationId: get-connect-connection
Required app scope: connections:connection:read.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
connection_id |
path | string (uuid) | 是 | Connection UUID |
回包
200OK —application/json·DataResponseConnectConnectionItemBodydefaultError —application/problem+json·D8Error
PATCH /api/v1/connect/connections/{connection_id}
Update connection
权限(scope): connections:connection:write · 调用方式: appToken · operationId: update-connect-connection
Required app scope: connections:connection:write.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
connection_id |
path | string (uuid) | 是 | Connection UUID |
请求体
application/json · UpdateConnectConnectionRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
display_name |
string | 是 | Connection display name |
mcp_headers |
array of ConnectMcpHeaderInput |
Full-replace custom-header set for a remote_http MCP connection: each {name, value, is_secret}. Omit to leave headers unchanged; send (even an empty array) to replace the full set. An is_secret=true entry with an empty value keeps the existing stored secret. Validated server-side. |
回包
200OK —application/json·DataResponseConnectConnectionItemBodydefaultError —application/problem+json·D8Error
GET /api/v1/connect/connections/{connection_id}/actions
List actions
权限(scope): connections:connection:read · 调用方式: appToken · operationId: list-connect-actions
Required app scope: connections:connection:read.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
connection_id |
path | string (uuid) | 是 | Connection UUID |
cursor |
query | string | Pagination cursor (opaque, from a previous response's next_cursor; omit for the first page). Only provider-hosted connectors page; others return their full catalog and ignore it | |
limit |
query | integer (int32) | Maximum actions per page for a paged (provider-hosted) catalog (omit for the backend default) | |
X-Connect-Client-Capabilities |
header | string | Comma-separated request_spec capabilities the calling client can execute (e.g. "request_spec.v1, body_template, prefetch, file_source"). Actions whose request_spec needs a capability not listed are omitted (list/search) or refused with 412 Precondition Failed (describe). Omit for an older client: no request_spec action is returned. |
回包
200OK —application/json·ConnectCursorListResponseConnectActionItemBodydefaultError —application/problem+json·D8Error
POST /api/v1/connect/connections/{connection_id}/actions/execute
Execute action
权限(scope): connections:action:execute · 调用方式: appToken · operationId: execute-connect-action
Required app scope: connections:action:execute.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
connection_id |
path | string (uuid) | 是 | Connection UUID |
请求体
application/json · ExecuteConnectActionRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
action |
string | 是 | Action name |
params |
any | Action parameters |
回包
200OK —application/json·DataResponseConnectExecuteActionDataBodydefaultError —application/problem+json·D8Error
GET /api/v1/connect/connections/{connection_id}/agents
List authorized agents
权限(scope): connections:connection:read · 调用方式: appToken · operationId: list-connect-authorized-agents
Required app scope: connections:connection:read.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
connection_id |
path | string (uuid) | 是 | Connection UUID |
回包
200OK —application/json·DataResponseListConnectAgentItemBodydefaultError —application/problem+json·D8Error
POST /api/v1/connect/connections/{connection_id}/agents
Authorize agent
权限(scope): connections:grant:write · 调用方式: appToken · operationId: authorize-connect-agent
Required app scope: connections:grant:write.
Binds an agent of the caller's org to a visible connection's credentials. The actor is always the authenticated human caller. An unknown or foreign-org agent_member_id is 404 MEMBER_NOT_FOUND (not distinguished), the same as batch-authorize-connect-agents.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
connection_id |
path | string (uuid) | 是 | Connection UUID |
请求体
application/json · AuthorizeConnectAgentRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
actor_member_id |
string | Optional acting member UUID. The actor is always the authenticated caller: if provided it must equal the caller's member UUID (case-insensitive), otherwise the request is rejected with 403 AUTH_FORBIDDEN. Omit to use the caller. | |
agent_member_id |
string (uuid) | 是 | Agent member UUID |
confirm |
boolean | Set true to authorize an agent whose runtime version is unknown (acknowledges the CONNECT_AGENT_VERSION_UNCONFIRMED prompt). Ignored for agents whose version is known — a too-old version is always rejected. |
回包
200OK —application/json·DataResponseMapStringBoolBodydefaultError —application/problem+json·D8Error
POST /api/v1/connect/connections/{connection_id}/agents/batch
Authorize agents (batch)
权限(scope): connections:grant:write · 调用方式: appToken · operationId: batch-authorize-connect-agents
Required app scope: connections:grant:write.
Authorizes up to 50 agents onto one connection in one request, with a result per agent (partial success). Each agent is checked with authorize-connect-agent's rules: MEMBER_NOT_FOUND (unknown, foreign-org, removed or departed — not distinguished), MEMBER_NOT_AN_AGENT, CONNECT_AGENT_TYPE_NOT_ALLOWED, CONNECT_AGENT_VERSION_TOO_OLD (hard block, meta version + minVersion) and CONNECT_AGENT_VERSION_UNCONFIRMED (only when confirm is false, meta minVersion). Eligible agents are written atomically; an agent that already holds a grant is already_authorized, which counts as success. data.results has one entry per requested agent after de-duplication, in request order. Whole-request errors: 400 for an invalid body (empty or missing list, more than 50 ids, malformed UUID; syntactically malformed JSON or wrong JSON types are the framework's 422), 401/403 for authentication / org membership / an actor_member_id other than the caller / an agent caller (only human members may authorize agents), 404 when the connection is not visible to the caller, 412 when the connection is not usable, 503 when the org service or the platform is unavailable. PAT-authenticated requests are additionally scope-gated (connections:grant:write).
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
connection_id |
path | string (uuid) | 是 | Connection UUID |
请求体
application/json · BatchAuthorizeConnectAgentsRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
actor_member_id |
string | Optional acting member UUID. The actor is always the authenticated caller: if provided it must equal the caller's member UUID (case-insensitive), otherwise the request is rejected with 403 AUTH_FORBIDDEN. Omit to use the caller. | |
agent_member_ids |
array of string (uuid) | 是 | Agent member UUIDs to authorize, 1..50 as sent. Duplicates are collapsed (first occurrence keeps its position). An empty list, more than 50 ids or a malformed UUID rejects the whole request with 400. |
confirm |
boolean | Set true to authorize agents whose runtime version is unknown (acknowledges CONNECT_AGENT_VERSION_UNCONFIRMED). Applies to every agent of the request; resubmit only the unconfirmed agents with it. A too-old version is always rejected. |
回包
200OK —application/json·DataResponseConnectAgentBatchAuthorizeDataBodydefaultError —application/problem+json·D8Error
DELETE /api/v1/connect/connections/{connection_id}/agents/{agent_member_id}
Revoke agent
权限(scope): connections:grant:write · 调用方式: appToken · operationId: revoke-connect-agent
Required app scope: connections:grant:write.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
connection_id |
path | string (uuid) | 是 | Connection UUID |
agent_member_id |
path | string (uuid) | 是 | Agent member UUID |
actor_member_id |
query | string | Optional acting member UUID. The actor is always the authenticated caller: if provided it must equal the caller's member UUID (case-insensitive), otherwise the request is rejected with 403 AUTH_FORBIDDEN. Omit to use the caller. |
回包
200OK —application/json·DataResponseMapStringBoolBodydefaultError —application/problem+json·D8Error
POST /api/v1/connect/connections/{connection_id}/disconnect
Disconnect connection
权限(scope): connections:connection:write · 调用方式: appToken · operationId: disconnect-connect-connection
Required app scope: connections:connection:write.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
connection_id |
path | string (uuid) | 是 | Connection UUID |
请求体
application/json · DisconnectConnectConnectionRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
actor_member_id |
string | Optional acting member UUID. The actor is always the authenticated caller: if provided it must equal the caller's member UUID (case-insensitive), otherwise the request is rejected with 403 AUTH_FORBIDDEN. Omit to use the caller. |
回包
200OK —application/json·DataResponseMapStringBoolBodydefaultError —application/problem+json·D8Error
POST /api/v1/connect/connections/{connection_id}/proxy
Call an API through a connection
权限(scope): connections:action:execute · 调用方式: appToken · operationId: proxy-connect-forward
Required app scope: connections:action:execute.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
connection_id |
path | string (uuid) | 是 | Connection UUID |
请求体
application/json · ProxyConnectForwardRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
body |
any | Request body | |
headers |
object | Headers to forward | |
method |
string | 是 | HTTP method |
url |
string | 是 | Target URL/path |
回包
200OK —application/json·DataResponseConnectProxyForwardDataBodydefaultError —application/problem+json·D8Error
POST /api/v1/connect/connections/{connection_id}/reauth
Initiate reauth
权限(scope): connections:connection:write · 调用方式: appToken · operationId: initiate-connect-reauth
Required app scope: connections:connection:write.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
connection_id |
path | string (uuid) | 是 | Connection UUID |
回包
200OK —application/json·DataResponseConnectInitiateReauthDataBodydefaultError —application/problem+json·D8Error
POST /api/v1/connect/connections/{connection_id}/reauth/complete
Complete reauth
权限(scope): connections:connection:write · 调用方式: appToken · operationId: complete-connect-reauth
Required app scope: connections:connection:write.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
connection_id |
path | string (uuid) | 是 | Connection UUID |
请求体
application/json · CompleteConnectReauthRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
code |
string | 是 | OAuth code |
raw_params |
object | Verbatim reauth OAuth callback query parameters | |
state |
string | 是 | OAuth state |
回包
200OK —application/json·DataResponseConnectConnectionItemBodydefaultError —application/problem+json·D8Error
GET /api/v1/connect/connections:with-agents
List connections with their authorized agents
权限(scope): connections:connection:read · 调用方式: appToken · operationId: list-connect-connections-with-agents
Required app scope: connections:connection:read.
The connections visible to the caller (org connections of the caller's org ∪ the caller's own personal connections; same items, filters and order — created_at DESC — as list-connect-connections), each with authorized_agents: the live agents authorized on it, most recently authorized first. Deleted and departed agent members are filtered out, exactly as list-connect-authorized-agents does; if that member lookup fails the whole request fails (no unfiltered list is returned). org and member are derived from the principal. Errors: 400 malformed filter, 401/403 authentication / org membership, 503 when the platform or the member lookup is unavailable.
参数
| 名字 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
application_id |
query | string (uuid) | Application UUID | |
status |
query | string | Connection status filter |
回包
200OK —application/json·DataResponseListConnectConnectionWithAgentsItemBodydefaultError —application/problem+json·D8Error
POST /api/v1/connect/shopify-app/installs/claim
Claim a Shopify public app install
权限(scope): connections:connection:write · 调用方式: appToken · operationId: claim-connect-shopify-app-install
Required app scope: connections:connection:write.
Called by the OpenMax web app's claim page (/connect/shopify/claim?ticket=...) after a merchant installed the OpenMax Shopify public app: binds the authorized install to the caller's current organization, creating the org-scope shopify-app connection owned by the caller, or re-authorizing the organization's existing connection for that shop. The organization and owner come from the session, never the body; the one-time ticket travels in the body. Agents are refused (403). Errors: 404 CONNECT_SHOPIFY_INSTALL_TICKET_INVALID (ticket unknown, already used or expired after 30 minutes: reopen the app from the Shopify admin), 409 CONNECT_SHOPIFY_SHOP_ALREADY_CONNECTED (the shop is connected to another organization), 400 (malformed install), 503 (a credential refresh of the existing connection is in flight; retry).
请求体
application/json · ClaimConnectShopifyAppInstallRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
display_name |
string | Optional connection display name; defaults to "Shopify · |
|
ticket |
string | 是 | One-time claim ticket from the claim page URL (/connect/shopify/claim?ticket=...) |
回包
200OK —application/json·DataResponseConnectConnectionItemBodydefaultError —application/problem+json·D8Error
POST /api/v1/connect/shopify-app/installs/resolve
Resolve a Shopify public app claim ticket
权限(scope): connections:connection:read · 调用方式: appToken · operationId: resolve-connect-shopify-app-install
Required app scope: connections:connection:read.
Called by the OpenMax web app's claim page (/connect/shopify/claim?ticket=...) before it offers the claim: returns the shop the one-time ticket is bound to, so the page shows that shop and never the URL's shop parameter (which is not bound to the ticket). Read-only: the ticket is not consumed and stays claimable. Same authentication and errors as claim-connect-shopify-app-install: the caller's session must carry an organization, agents are refused (403), and the ticket travels in the body. Errors: 404 CONNECT_SHOPIFY_INSTALL_TICKET_INVALID (ticket unknown, already used or expired after 30 minutes: reopen the app from the Shopify admin), 400 (malformed request).
请求体
application/json · ResolveConnectShopifyAppInstallRequestBody
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
ticket |
string | 是 | One-time claim ticket from the claim page URL (/connect/shopify/claim?ticket=...); not consumed |
回包
200OK —application/json·DataResponseConnectShopifyAppInstallItemBodydefaultError —application/problem+json·D8Error
