OpenMax
Free Trial

Apps API · Connect

Connect: 21 endpoints

← All groups

GET /api/v1/connect/agents/me/connections

List available connections

Scope: connections:connection:read · Called with: appToken · operationId: list-connect-available-connections

Required app scope: connections:connection:read.

Responses

POST /api/v1/connect/agents/usable-connections/query

Query the connections agents can use

Scope: connections:connection:read · Called with: 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.

Request body

application/json · QueryConnectAgentUsableConnectionsRequestBody

Field Type Required Description
agent_member_ids array of string (uuid) yes 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.

Responses

GET /api/v1/connect/agents/{agent_member_id}/connections

List connections an agent is authorized to use

Scope: connections:connection:read · Called with: 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.

Parameters

Name In Type Required Description
agent_member_id path string (uuid) yes Agent member UUID
conversation_id query string (uuid) yes Conversation the panel is opened in; the server derives display scope (group hides personal-scope connectors) and verifies caller membership from it

Responses

GET /api/v1/connect/connections

List connections

Scope: connections:connection:read · Called with: appToken · operationId: list-connect-connections

Required app scope: connections:connection:read.

Parameters

Name In Type Required Description
application_id query string (uuid) Application UUID
status query string Connection status filter

Responses

POST /api/v1/connect/connections

Create OAuth connection

Scope: connections:connection:write · Called with: appToken · operationId: create-connect-connection

Required app scope: connections:connection:write.

Request body

application/json · CreateConnectConnectionRequestBody

Field Type Required Description
application_slug string yes 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 yes Owner scope

Responses

POST /api/v1/connect/connections/api-key

Create API key connection

Scope: connections:connection:write · Called with: appToken · operationId: create-connect-api-key-connection

Required app scope: connections:connection:write.

Request body

application/json · CreateConnectAPIKeyConnectionRequestBody

Field Type Required Description
api_key string API key credential (single-value shortcut; optional when the multi-field 'fields' map is used instead)
application_slug string yes 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 yes Owner scope
username string Username (required when the application's api_key_auth_style is 'basic', e.g. Jenkins)

Responses

GET /api/v1/connect/connections/{connection_id}

Get connection

Scope: connections:connection:read · Called with: appToken · operationId: get-connect-connection

Required app scope: connections:connection:read.

Parameters

Name In Type Required Description
connection_id path string (uuid) yes Connection UUID

Responses

PATCH /api/v1/connect/connections/{connection_id}

Update connection

Scope: connections:connection:write · Called with: appToken · operationId: update-connect-connection

Required app scope: connections:connection:write.

Parameters

Name In Type Required Description
connection_id path string (uuid) yes Connection UUID

Request body

application/json · UpdateConnectConnectionRequestBody

Field Type Required Description
display_name string yes 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.

Responses

GET /api/v1/connect/connections/{connection_id}/actions

List actions

Scope: connections:connection:read · Called with: appToken · operationId: list-connect-actions

Required app scope: connections:connection:read.

Parameters

Name In Type Required Description
connection_id path string (uuid) yes 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.

Responses

POST /api/v1/connect/connections/{connection_id}/actions/execute

Execute action

Scope: connections:action:execute · Called with: appToken · operationId: execute-connect-action

Required app scope: connections:action:execute.

Parameters

Name In Type Required Description
connection_id path string (uuid) yes Connection UUID

Request body

application/json · ExecuteConnectActionRequestBody

Field Type Required Description
action string yes Action name
params any Action parameters

Responses

GET /api/v1/connect/connections/{connection_id}/agents

List authorized agents

Scope: connections:connection:read · Called with: appToken · operationId: list-connect-authorized-agents

Required app scope: connections:connection:read.

Parameters

Name In Type Required Description
connection_id path string (uuid) yes Connection UUID

Responses

POST /api/v1/connect/connections/{connection_id}/agents

Authorize agent

Scope: connections:grant:write · Called with: 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.

Parameters

Name In Type Required Description
connection_id path string (uuid) yes Connection UUID

Request body

application/json · AuthorizeConnectAgentRequestBody

Field Type Required Description
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) yes 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.

Responses

POST /api/v1/connect/connections/{connection_id}/agents/batch

Authorize agents (batch)

Scope: connections:grant:write · Called with: 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).

Parameters

Name In Type Required Description
connection_id path string (uuid) yes Connection UUID

Request body

application/json · BatchAuthorizeConnectAgentsRequestBody

Field Type Required Description
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) yes 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.

Responses

DELETE /api/v1/connect/connections/{connection_id}/agents/{agent_member_id}

Revoke agent

Scope: connections:grant:write · Called with: appToken · operationId: revoke-connect-agent

Required app scope: connections:grant:write.

Parameters

Name In Type Required Description
connection_id path string (uuid) yes Connection UUID
agent_member_id path string (uuid) yes 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.

Responses

POST /api/v1/connect/connections/{connection_id}/disconnect

Disconnect connection

Scope: connections:connection:write · Called with: appToken · operationId: disconnect-connect-connection

Required app scope: connections:connection:write.

Parameters

Name In Type Required Description
connection_id path string (uuid) yes Connection UUID

Request body

application/json · DisconnectConnectConnectionRequestBody

Field Type Required Description
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.

Responses

POST /api/v1/connect/connections/{connection_id}/proxy

Call an API through a connection

Scope: connections:action:execute · Called with: appToken · operationId: proxy-connect-forward

Required app scope: connections:action:execute.

Parameters

Name In Type Required Description
connection_id path string (uuid) yes Connection UUID

Request body

application/json · ProxyConnectForwardRequestBody

Field Type Required Description
body any Request body
headers object Headers to forward
method string yes HTTP method
url string yes Target URL/path

Responses

POST /api/v1/connect/connections/{connection_id}/reauth

Initiate reauth

Scope: connections:connection:write · Called with: appToken · operationId: initiate-connect-reauth

Required app scope: connections:connection:write.

Parameters

Name In Type Required Description
connection_id path string (uuid) yes Connection UUID

Responses

POST /api/v1/connect/connections/{connection_id}/reauth/complete

Complete reauth

Scope: connections:connection:write · Called with: appToken · operationId: complete-connect-reauth

Required app scope: connections:connection:write.

Parameters

Name In Type Required Description
connection_id path string (uuid) yes Connection UUID

Request body

application/json · CompleteConnectReauthRequestBody

Field Type Required Description
code string yes OAuth code
raw_params object Verbatim reauth OAuth callback query parameters
state string yes OAuth state

Responses

GET /api/v1/connect/connections:with-agents

List connections with their authorized agents

Scope: connections:connection:read · Called with: 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.

Parameters

Name In Type Required Description
application_id query string (uuid) Application UUID
status query string Connection status filter

Responses

POST /api/v1/connect/shopify-app/installs/claim

Claim a Shopify public app install

Scope: connections:connection:write · Called with: 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).

Request body

application/json · ClaimConnectShopifyAppInstallRequestBody

Field Type Required Description
display_name string Optional connection display name; defaults to "Shopify · "
ticket string yes One-time claim ticket from the claim page URL (/connect/shopify/claim?ticket=...)

Responses

POST /api/v1/connect/shopify-app/installs/resolve

Resolve a Shopify public app claim ticket

Scope: connections:connection:read · Called with: 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).

Request body

application/json · ResolveConnectShopifyAppInstallRequestBody

Field Type Required Description
ticket string yes One-time claim ticket from the claim page URL (/connect/shopify/claim?ticket=...); not consumed

Responses