OpenMax
免费试用

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.

回包

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.

回包

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

回包

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

回包

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

回包

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)

回包

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

回包

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.

回包

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.

回包

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

回包

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

回包

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.

回包

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.

回包

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.

回包

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.

回包

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

回包

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

回包

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

回包

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

回包

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=...)

回包

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

回包