Skip to content
MCP Gateway

Preview an API contract import without persisting a registry record.

POST
/v1/api-sources/preview

Discovery-first endpoint for customer-supplied OpenAPI 3.x, Swagger/OpenAPI 2.0, or Postman Collection v2.1 contracts. Accepts JSON uploaded content, multipart file upload content, safe HTTPS direct URLs, and dev/test fixture paths. Allows zero selected operations and returns metadata-only candidate and mapping preview data.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”
object
schemaVersion
required
Allowed values: gateway.api-source-preview/v1 gateway.api-source-import/v1
apiSourceId
required
string
>= 1 characters
environmentId
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>
selectedOperations
Array<string>
default:
credentialBindingId

Optional opaque credential binding id used only for mapping preview metadata.

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

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Metadata-only import preview. No registry record is persisted.

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

400

Section titled “400 ”

Invalid

403

Section titled “403 ”

Missing api_source.import for the requested environment.

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