Skip to content
MCP Gateway

Import an API contract and create gateway-hosted MCP tool candidates.

POST
/v1/api-sources/import

Accepts OpenAPI 3.x, Swagger/OpenAPI 2.0, or Postman Collection v2.1 contract input and persists selected operations for approval. Imported APIs become gateway-hosted MCP tool facades through the API adapter; no backend MCP server is created.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”
object
schemaVersion
required
apiSourceId
required
string
>= 1 characters
environmentId
required
string
>= 1 characters
name
required
string
>= 1 characters
owner
required
object
team
required
string
>= 1 characters
userId
required
string
>= 1 characters
escalationContact
required
string
>= 1 characters
oncallRotation
required
string
>= 1 characters
source
required
object
inputType
required
Allowed values: direct_url uploaded_file configured_source
url

Direct contract URL or configured source URL. Remote fetches are bounded and host-allowlisted.

string format: uri
uploadedFileName

Dev/test fixture path under fixtures/openapi when content fields are absent.

string
>= 1 characters
fileName

Safe display name for browser-uploaded contract content. File bytes are not echoed in responses.

string
>= 1 characters
contentBase64

Browser-uploaded contract bytes. Accepted on preview/import but never returned.

string
>= 1 characters
contentText

Browser-uploaded UTF-8 contract content. Accepted on preview/import but never returned.

string
>= 1 characters
resolverId

Configured source resolver id. Provider-specific resolver details are backend configuration, not product DTO concepts.

string
>= 1 characters
allowedHosts
required
Array<string>
>= 1 items
selectedOperations
required
Array<string>
>= 1 items
credentialBindingId

Optional top-level default opaque credential binding id. Secret material is never accepted here.

string
>= 1 characters
operationCredentialBindings
Array<object>
default:
object
operationId
required
string
>= 1 characters
credentialBindingId
required

Opaque credential binding id. Secret material is never accepted here.

string
>= 1 characters
credentialMode
Allowed values: service_account user_delegated agent_scoped workload_mapped
reasonCode
string
/^[a-z0-9_]+$/

Responses

Section titled “ Responses ”

202

Section titled “202 ”

Import accepted for validation, operation selection, and approval.

object
schemaVersion
required
apiSourceId
required
string
>= 1 characters
detectedFormat
required
Allowed values: openapi_3 swagger_2 postman_collection unknown
normalizedFrom
required
Any of:
Allowed values: openapi_3 swagger_2 postman_collection unknown
upstreamHosts
required
Array<string>
runtimePlacement
required
object
mode
required
mcpServerCreated
required
boolean
managedMcpHostingAvailable
required
boolean
reasonCode
required
validation
required
object
valid
required
boolean
reasonCodes
required
Array<string>
candidateOperations
required
Array<object>
object
operationId
required
string
>= 1 characters
method
required
Allowed values: GET POST PUT PATCH DELETE
host
required
string
>= 1 characters
path
required
string
>= 1 characters /^//
summary
required
string
requestContentTypes
required
Array<string>
requestBodyFields
required
Array<object>
object
name
required
string
>= 1 characters
location
required
Allowed values: path query header body
required
required
boolean
type
required
Allowed values: string integer number boolean object array
contentType
string | null
authRequirements
required
Array<object>
object
authGroup
required
integer
scheme
required
Allowed values: none api_key bearer basic oauth2 hmac sigv4 mtls workload_identity unsupported
placement
required
Allowed values: none header query authorization_header transport signature
schemeName
string
>= 1 characters
parameterName
string
>= 1 characters
requiredScopes
required
Array<string>
oauthFlow
Allowed values: client_credentials authorization_code jwt_bearer unknown
bearerFormat
string
>= 1 characters
credentialBindingRequired
required
boolean
callerVisible
required
boolean
supported
required
boolean
unsupportedReason
string
/^[a-z0-9_]+$/
injectionPlan
required
Allowed values: none header_api_key query_api_key authorization_bearer authorization_basic oauth2_client_credentials oauth2_user_delegated workload_identity mtls hmac_signature aws_sigv4 unsupported
selected
required
boolean
approvalStatus
required
string
Allowed values: submitted under_review approved rejected disabled archived
generatedToolId
required
string
>= 1 characters
generatedToolName
required
string
>= 1 characters
riskTier
required
Allowed values: low medium high critical
validationWarnings
required
Array<object>
object
reasonCode
required
string
/^[a-z0-9_]+$/
field
required
string
>= 1 characters
host
string
>= 1 characters
severity
required
Allowed values: info warning error
mappingPreviews
required
Array<object>
object
schemaVersion
required
apiSourceId
required
string
>= 1 characters
operationId
required
string
>= 1 characters
generatedToolId
required
string
>= 1 characters
generatedToolName
required
string
>= 1 characters
selected
required
boolean
approvalStatus
required
string
Allowed values: submitted under_review approved rejected disabled archived
requestContentType
required
Allowed values: application/json application/x-www-form-urlencoded multipart/form-data
method
required
Allowed values: GET POST PUT PATCH DELETE
upstreamHost
required
string
>= 1 characters
pathTemplate
required
string
>= 1 characters /^//
runtimePlacement
required
object
mode
required
mcpServerCreated
required
boolean
managedMcpHostingAvailable
required
boolean
reasonCode
required
inputSchema
required
object
type
required
additionalProperties
required
boolean
required
required
Array<string>
properties
required
object
key
additional properties
object
type
required
Allowed values: string integer number boolean object array
location
required
Allowed values: path query header body
required
required
boolean
minLength
integer
maxLength
integer
>= 1
maxItems
integer
>= 1
maxBytes
integer
>= 1
validationBoundaries
required
object
pathParamsRequired
required
boolean
querySchemaValidated
required
boolean
headerSchemaValidated
required
boolean
bodySchemaValidated
required
boolean
credentialBindingId
required
Any of:
string
>= 1 characters
credentialMode
required
Allowed values: none service_account user_delegated agent_scoped workload_mapped
authRequirements
required
Array<object>
object
authGroup
required
integer
scheme
required
Allowed values: none api_key bearer basic oauth2 hmac sigv4 mtls workload_identity unsupported
placement
required
Allowed values: none header query authorization_header transport signature
schemeName
string
>= 1 characters
parameterName
string
>= 1 characters
requiredScopes
required
Array<string>
oauthFlow
Allowed values: client_credentials authorization_code jwt_bearer unknown
bearerFormat
string
>= 1 characters
credentialBindingRequired
required
boolean
callerVisible
required
boolean
supported
required
boolean
unsupportedReason
string
/^[a-z0-9_]+$/
injectionPlan
required
Allowed values: none header_api_key query_api_key authorization_bearer authorization_basic oauth2_client_credentials oauth2_user_delegated workload_identity mtls hmac_signature aws_sigv4 unsupported
injectionPlan
required
Allowed values: none header_api_key query_api_key authorization_bearer authorization_basic oauth2_client_credentials oauth2_user_delegated workload_identity mtls hmac_signature aws_sigv4 unsupported
requiredScopes
required
Array<string>
credentialCompatibility
required
Allowed values: not_required compatible unsupported
unsupportedReason
required
Any of:
string
/^[a-z0-9_]+$/
limits
required
object
timeoutMs
required
integer
>= 1 <= 30000
maxRequestBytes
required
integer
>= 1
maxResponseBytes
required
integer
>= 1
oversizeBehavior
required
audit
required
object
eventType
required
policyVersionRequired
required
boolean
credentialModeRequired
required
boolean
credentialBindingIdRequired
required
boolean
payloadLogged
required
boolean
secretMaterialLogged
required
boolean
redactionStatus
required
approvalStatus
required
string
Allowed values: submitted under_review approved rejected disabled archived
mcpClient
Any of:
object
gatewayEndpointUrl
required
string format: uri
generatedTools
required
Array<object>
object
toolId
required
string
>= 1 characters
name
required
string
>= 1 characters
authMode
required
Allowed values: gateway_client_auth
transport
required
Allowed values: streamable_http sse
smokeTestCommand
required

Secret-free local command descriptor for MCP client list/call smoke.

string
>= 1 characters

Type set in Geist, Source Serif 4, and Departure Mono.