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 |
回包
200OK —application/json·ConnectCursorListResponseConnectApplicationItemBodydefaultError —application/problem+json·D8Error
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 |
回包
200OK —application/json·DataResponseConnectApplicationItemBodydefaultError —application/problem+json·D8Error
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 |
回包
200OK —application/json·DataResponseConnectApplicationCategoryCountsBodydefaultError —application/problem+json·D8Error
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. |
回包
200OK —application/json·DataResponseListConnectApplicationsQueryEntryBodydefaultError —application/problem+json·D8Error
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 |
回包
200OK —application/json·DataResponseMapStringBoolBodydefaultError —application/problem+json·D8Error
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 |
回包
200OK —application/json·DataResponseConnectApplicationItemBodydefaultError —application/problem+json·D8Error
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) |
回包
200OK —application/json·DataResponseConnectApplicationItemBodydefaultError —application/problem+json·D8Error
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 |
回包
200OK —application/json·DataResponseListConnectApplicationActionDefItemBodydefaultError —application/problem+json·D8Error
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 |
回包
200OK —application/json·DataResponseConnectApplicationActionDefItemBodydefaultError —application/problem+json·D8Error
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 |
回包
200OK —application/json·DataResponseMapStringBoolBodydefaultError —application/problem+json·D8Error
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 |
回包
200OK —application/json·DataResponseConnectApplicationActionDefItemBodydefaultError —application/problem+json·D8Error
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. |
回包
200OK —application/json·ConnectCursorListResponseConnectActionItemBodydefaultError —application/problem+json·D8Error
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. |
回包
200OK —application/json·DataResponseConnectActionItemBodydefaultError —application/problem+json·D8Error
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. |
回包
200OK —application/json·ConnectCursorListResponseConnectActionItemBodydefaultError —application/problem+json·D8Error
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 |
回包
200OK —application/json·DataResponseListConnectToolkitItemBodydefaultError —application/problem+json·D8Error
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 |
回包
200OK —application/json·DataResponseConnectConnectFieldsDataBodydefaultError —application/problem+json·D8Error
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.
回包
200OK —application/json·DataResponseConnectOAuthCallbackURLDataBodydefaultError —application/problem+json·D8Error
