OpenMax
Free Trial

Apps API · Connect Applications

Connect Applications: 17 endpoints

← All groups

GET /api/v1/connect/applications

List applications

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

Required app scope: connections:application:read.

Parameters

Name In Type Required Description
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

Responses

POST /api/v1/connect/applications

Create application

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

Required app scope: connections:application:write.

Request body

application/json · CreateConnectApplicationRequestBody

Field Type Required Description
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 yes 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 yes Provider type
slug string Application slug (optional; generated by OpenMax when omitted)
tags array of string Tags

Responses

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

Count applications per category

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

Parameters

Name In Type Required Description
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

Responses

POST /api/v1/connect/applications/query

Query applications by id

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

Request body

application/json · QueryConnectApplicationsRequestBody

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

Responses

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

Delete application

Scope: connections:application:write · Called with: appToken · operationId: delete-connect-application

Required app scope: connections:application:write.

Parameters

Name In Type Required Description
application_id path string (uuid) yes Application UUID

Responses

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

Get application

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

Required app scope: connections:application:read.

Parameters

Name In Type Required Description
application_id path string (uuid) yes Application UUID

Responses

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

Update application

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

Required app scope: connections:application:write.

Parameters

Name In Type Required Description
application_id path string (uuid) yes Application UUID

Request body

application/json · UpdateConnectApplicationRequestBody

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

Responses

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

List application action definitions

Scope: connections:application:read · Called with: appToken · operationId: list-connect-application-action-defs

Required app scope: connections:application:read.

Parameters

Name In Type Required Description
application_id path string (uuid) yes Application UUID

Responses

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

Create application action definition

Scope: connections:application:write · Called with: appToken · operationId: create-connect-application-action-def

Required app scope: connections:application:write.

Parameters

Name In Type Required Description
application_id path string (uuid) yes Application UUID

Request body

application/json · CreateConnectApplicationActionDefRequestBody

Field Type Required Description
description string yes Action description (required, non-empty)
encoding string Request body encoding
headers object Header template
input_schema string JSON schema for action inputs
method string yes HTTP method
name string yes 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 yes URL template

Responses

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

Delete application action definition

Scope: connections:application:write · Called with: appToken · operationId: delete-connect-application-action-def

Required app scope: connections:application:write.

Parameters

Name In Type Required Description
application_id path string (uuid) yes Application UUID
action_id path string (uuid) yes Action UUID

Responses

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

Update application action definition

Scope: connections:application:write · Called with: appToken · operationId: update-connect-application-action-def

Required app scope: connections:application:write.

Parameters

Name In Type Required Description
application_id path string (uuid) yes Application UUID
action_id path string (uuid) yes Action UUID

Request body

application/json · UpdateConnectApplicationActionDefRequestBody

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

Responses

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

List application actions

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

Required app scope: connections:application:read.

Parameters

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

Responses

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

Describe application action

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

Parameters

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

Responses

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

Search application actions

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

Parameters

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

Responses

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

List application toolkits

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

Required app scope: connections:application:read.

Parameters

Name In Type Required Description
application_id path string (uuid) yes Application UUID

Responses

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

Get connect fields

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

Parameters

Name In Type Required Description
application_slug path string yes Application slug

Responses

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

Get OAuth callback URL

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

Responses