OpenMax
免费试用

Apps API · Connect Applications

Connect Applications: 17 个接口

← 全部分组

GET /api/v1/connect/applications

List applications

权限(scope): connections:application:read · 调用方式: appToken · operationId: list-connect-applications

Required app scope: connections:application:read.

参数

名字 位置 类型 必填 说明
category query string Application category filter
query query string Optional free-text filter over applications
cursor query string Pagination cursor (opaque, from a previous response's next_cursor; omit for the first page)
limit query integer (int32) Maximum applications to return (omit for the backend default)
page query string 1-based page number for numbered pagination (integer >= 1); presence selects numbered mode (offset/limit) instead of cursor
page_size query string Items per numbered page (integer 1..100, default 20); only used in numbered mode
exclude_custom query boolean Exclude custom (org-defined) connectors from the catalog (default false: exclude nothing)
exclude_mcp query boolean Exclude MCP connectors, including managed MCP applications (default false: exclude nothing)
rank query string Optional relevance ordering: omit (or empty) for the default order; "prefix" ranks applications whose display_name starts with query (case-insensitive) first. With a non-empty query, prefix ranking requires numbered mode (page/page_size); on the cursor path, or for any other value, the request is rejected with 400
created_by_me query boolean Only connectors created by the caller or by an agent the caller currently owns (default false: no creator filter). Connectors with no recorded creator never match

回包

POST /api/v1/connect/applications

Create application

权限(scope): connections:application:write · 调用方式: appToken · operationId: create-connect-application

Required app scope: connections:application:write.

请求体

application/json · CreateConnectApplicationRequestBody

字段 类型 必填 说明
api_key_header_name string API key header/param name
api_key_location string API key location: header or query
category string Category
connector_kind string Connector transport kind: http (default) or mcp
default_ttl_seconds integer (int32) Default credential TTL in seconds
description string Description
display_name string 是 Display name
icon_url string Icon URL
oauth_authorize_url string OAuth authorize URL
oauth_client_id string OAuth client ID
oauth_client_secret string OAuth client secret
oauth_pkce boolean Whether OAuth uses PKCE
oauth_scopes_default array of string Default OAuth scopes
oauth_token_auth_method string OAuth token auth method: basic or post
oauth_token_body_format string OAuth token body format: form or json
oauth_token_url string OAuth token URL
provider_type string 是 Provider type
slug string Application slug (optional; generated by OpenMax when omitted)
tags array of string Tags

回包

GET /api/v1/connect/applications/category-counts

Count applications per category

权限(scope): connections:application:read · 调用方式: appToken · operationId: get-connect-application-category-counts

Required app scope: connections:application:read.

Catalog size per category for the caller: the applications list-connect-applications would page over for the same query / exclude_custom / exclude_mcp without a category (enabled public applications plus the caller org's own custom connectors), grouped by category in one query. Only non-empty categories are returned; total_count is their sum. org is derived from the principal.

参数

名字 位置 类型 必填 说明
query query string Optional free-text filter, same as list-connect-applications query
exclude_custom query boolean Exclude custom (org-defined) connectors, same as list-connect-applications
exclude_mcp query boolean Exclude MCP connectors, same as list-connect-applications

回包

POST /api/v1/connect/applications/query

Query applications by id

权限(scope): connections:application:read · 调用方式: appToken · operationId: query-connect-applications

Required app scope: connections:application:read.

Read-only (POST for the request body) batch form of get-connect-application: one entry per requested id after de-duplication, in request order, each carrying exactly one of application (the same item get-connect-application returns, including the caller's connection state) or error APPLICATION_NOT_FOUND (unknown, deleted, or another org's private connector — not distinguished, as the single read's 404). Disabled applications are returned like the single read. Whole-request errors: 400 for an invalid body (empty or missing list, more than 100 ids, malformed UUID; 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 scope-gated (connections:application:read). org and member are derived from the principal, never client-supplied.

请求体

application/json · QueryConnectApplicationsRequestBody

字段 类型 必填 说明
application_ids array of string (uuid) 是 Application UUIDs, 1..100 as sent. Duplicates (case-insensitive) are collapsed, the first occurrence keeping its position. An empty list, more than 100 ids or a malformed UUID rejects the whole request with 400.

回包

DELETE /api/v1/connect/applications/{application_id}

Delete application

权限(scope): connections:application:write · 调用方式: appToken · operationId: delete-connect-application

Required app scope: connections:application:write.

参数

名字 位置 类型 必填 说明
application_id path string (uuid) 是 Application UUID

回包

GET /api/v1/connect/applications/{application_id}

Get application

权限(scope): connections:application:read · 调用方式: appToken · operationId: get-connect-application

Required app scope: connections:application:read.

参数

名字 位置 类型 必填 说明
application_id path string (uuid) 是 Application UUID

回包

PATCH /api/v1/connect/applications/{application_id}

Update application

权限(scope): connections:application:write · 调用方式: appToken · operationId: update-connect-application

Required app scope: connections:application:write.

参数

名字 位置 类型 必填 说明
application_id path string (uuid) 是 Application UUID

请求体

application/json · UpdateConnectApplicationRequestBody

字段 类型 必填 说明
api_key_header_name string API key header/param name
api_key_location string API key location: header or query
category string Category
connector_kind string Connector transport kind (read-only after create; accepted but not applied on update)
description string Description
display_name string Display name
icon_url string Icon URL
is_enabled boolean Whether the application is enabled
oauth_authorize_url string OAuth authorize URL (unset leaves unchanged)
oauth_client_id string OAuth client ID (unset leaves unchanged)
oauth_client_secret string OAuth client secret (empty/absent leaves the stored secret unchanged; non-empty overwrites)
oauth_pkce boolean Whether OAuth uses PKCE
oauth_scopes_default array of string Default OAuth scopes (absent leaves unchanged; present replaces, empty clears)
oauth_token_auth_method string OAuth token auth method: basic or post
oauth_token_body_format string OAuth token body format: form or json
oauth_token_url string OAuth token URL (unset leaves unchanged)

回包

GET /api/v1/connect/applications/{application_id}/action-defs

List application action definitions

权限(scope): connections:application:read · 调用方式: appToken · operationId: list-connect-application-action-defs

Required app scope: connections:application:read.

参数

名字 位置 类型 必填 说明
application_id path string (uuid) 是 Application UUID

回包

POST /api/v1/connect/applications/{application_id}/action-defs

Create application action definition

权限(scope): connections:application:write · 调用方式: appToken · operationId: create-connect-application-action-def

Required app scope: connections:application:write.

参数

名字 位置 类型 必填 说明
application_id path string (uuid) 是 Application UUID

请求体

application/json · CreateConnectApplicationActionDefRequestBody

字段 类型 必填 说明
description string 是 Action description (required, non-empty)
encoding string Request body encoding
headers object Header template
input_schema string JSON schema for action inputs
method string 是 HTTP method
name string 是 Action name
request_spec any Optional request_spec JSON object (direct-mode body template / files / upload / batch). Validated by the platform; encoding must then be empty
url_template string 是 URL template

回包

DELETE /api/v1/connect/applications/{application_id}/action-defs/{action_id}

Delete application action definition

权限(scope): connections:application:write · 调用方式: appToken · operationId: delete-connect-application-action-def

Required app scope: connections:application:write.

参数

名字 位置 类型 必填 说明
application_id path string (uuid) 是 Application UUID
action_id path string (uuid) 是 Action UUID

回包

PATCH /api/v1/connect/applications/{application_id}/action-defs/{action_id}

Update application action definition

权限(scope): connections:application:write · 调用方式: appToken · operationId: update-connect-application-action-def

Required app scope: connections:application:write.

参数

名字 位置 类型 必填 说明
application_id path string (uuid) 是 Application UUID
action_id path string (uuid) 是 Action UUID

请求体

application/json · UpdateConnectApplicationActionDefRequestBody

字段 类型 必填 说明
encoding string Request body encoding
headers object Header template; non-empty replaces stored headers, empty leaves unchanged
input_schema string JSON schema for action inputs
method string HTTP method
request_spec any Optional request_spec JSON object; present replaces the stored one (cannot be cleared via update). Validated by the platform
url_template string URL template

回包

GET /api/v1/connect/applications/{application_id}/actions

List application actions

权限(scope): connections:application:read · 调用方式: appToken · operationId: list-connect-application-actions

Required app scope: connections:application:read.

参数

名字 位置 类型 必填 说明
application_id path string (uuid) 是 Application UUID
cursor query string Pagination cursor (opaque, from a previous response's next_cursor; omit for the first page). Only provider-hosted applications 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.

回包

GET /api/v1/connect/applications/{application_id}/actions/{action}

Describe application action

权限(scope): connections:application:read · 调用方式: appToken · operationId: describe-connect-application-action

Required app scope: connections:application:read.

Stage 2 of two-stage action discovery: the full ActionInfo (input schema, params, direct-mode local-egress template) for a single action of an application.

参数

名字 位置 类型 必填 说明
application_id path string (uuid) 是 Application UUID
action path string 是 Action identifier (e.g. toolkit.action) to describe
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.

回包

GET /api/v1/connect/applications/{application_id}/actions:search

Search application actions

权限(scope): connections:application:read · 调用方式: appToken · operationId: search-connect-application-actions

Required app scope: connections:application:read.

Stage 1 of two-stage action discovery: a paginated, query-filtered search over an application's action catalog. Returns lightweight ActionInfo entries plus a next_cursor for the following page.

参数

名字 位置 类型 必填 说明
application_id path string (uuid) 是 Application UUID
query query string Free-text query over the application's action catalog
cursor query string Pagination cursor (opaque, from a previous response's next_cursor; omit for the first page)
limit query integer (int32) Maximum actions to return (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.

回包

GET /api/v1/connect/applications/{application_id}/toolkits

List application toolkits

权限(scope): connections:application:read · 调用方式: appToken · operationId: list-connect-application-toolkits

Required app scope: connections:application:read.

参数

名字 位置 类型 必填 说明
application_id path string (uuid) 是 Application UUID

回包

GET /api/v1/connect/applications/{application_slug}/connect-fields

Get connect fields

权限(scope): connections:application:read · 调用方式: appToken · operationId: get-connect-fields

Required app scope: connections:application:read.

Returns the connect-form field schema for an api_key application (the fields the caller must supply in the fields map of POST /api/v1/connect/connections/api-key), so a client can render the credential form dynamically instead of hardcoding api_key/username/base_url. Provider-hosted api_key toolkits return the provider's field names; managed api_key connectors that declare connect fields return api_key/username/base_url with an input placeholder and zh/en display_name_i18n/description_i18n/placeholder_i18n maps (the plain display_name/description/placeholder are the English fallback). Every other application returns an empty list.

参数

名字 位置 类型 必填 说明
application_slug path string 是 Application slug

回包

GET /api/v1/connect/oauth-callback-url

Get OAuth callback URL

权限(scope): connections:application:read · 调用方式: appToken · operationId: get-connect-oauth-callback-url

Required app scope: connections:application:read.

Returns the platform's provider-facing OAuth callback URL to register with the OAuth provider. This is the same value the platform injects as oauth_callback_url when a custom connector is created, so a client can display it before creation.

回包