openapi: 3.1.0
info:
title: Warmplane HTTP Facade API
version: "v1"
description: |
Warmplane exposes a compact, deterministic HTTP facade over multiple upstream MCP servers.
This API is index-first: list compact capability/resource/prompt entries, then request detail
or execute operations on-demand.
servers:
- url: http://127.0.0.1:9090
description: local default
paths:
/v1/capabilities:
get:
summary: List capabilities
operationId: listCapabilities
responses:
"200":
description: Capability index
content:
application/json:
schema:
$ref: "#/components/schemas/CapabilitiesListResponse"
/v1/capabilities/{id}:
get:
summary: Describe capability
operationId: describeCapability
parameters:
- in: path
name: id
required: true
schema:
type: string
responses:
"200":
description: Capability detail
content:
application/json:
schema:
$ref: "#/components/schemas/CapabilityDescribeResponse"
"404":
description: Capability not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
/v1/tools/call:
post:
summary: Execute capability
operationId: callCapability
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CallCapabilityRequest"
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/SuccessEnvelope"
"400":
description: Invalid request
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
"403":
description: Policy blocked
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
"404":
description: Capability not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
"502":
description: Upstream error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
"504":
description: Upstream timeout
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
/v1/resources:
get:
summary: List resources
operationId: listResources
responses:
"200":
description: Resource index
content:
application/json:
schema:
$ref: "#/components/schemas/ResourcesListResponse"
/v1/resources/read:
post:
summary: Read resource
operationId: readResource
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ReadResourceRequest"
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/SuccessEnvelope"
"400":
description: Invalid request
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
"403":
description: Policy blocked
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
"404":
description: Resource not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
"502":
description: Upstream error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
"504":
description: Upstream timeout
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
/v1/prompts:
get:
summary: List prompts
operationId: listPrompts
responses:
"200":
description: Prompt index
content:
application/json:
schema:
$ref: "#/components/schemas/PromptsListResponse"
/v1/prompts/get:
post:
summary: Get prompt output
operationId: getPrompt
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/GetPromptRequest"
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/SuccessEnvelope"
"400":
description: Invalid request
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
"403":
description: Policy blocked
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
"404":
description: Prompt not found
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
"502":
description: Upstream error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
"504":
description: Upstream timeout
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorEnvelope"
components:
schemas:
CapabilityListItem:
type: object
required: [id, summary, server, tool, tags]
properties:
id:
type: string
summary:
type: string
server:
type: string
tool:
type: string
tags:
type: array
items:
type: string
ResourceListItem:
type: object
required: [id, server, uri, name, tags]
properties:
id:
type: string
server:
type: string
uri:
type: string
name:
type: string
description:
type: [string, "null"]
mime_type:
type: [string, "null"]
tags:
type: array
items:
type: string
PromptListItem:
type: object
required: [id, server, name, arguments, tags]
properties:
id:
type: string
server:
type: string
name:
type: string
title:
type: [string, "null"]
description:
type: [string, "null"]
arguments:
type: array
items:
type: object
tags:
type: array
items:
type: string
CapabilitiesListResponse:
type: object
required: [version, capabilities]
properties:
version:
type: string
const: v1
capabilities:
type: array
items:
$ref: "#/components/schemas/CapabilityListItem"
CapabilityDescribeResponse:
type: object
required: [version, capability]
properties:
version:
type: string
const: v1
capability:
type: object
required: [id, server, tool, description, input_schema, examples]
properties:
id:
type: string
server:
type: string
tool:
type: string
description:
type: string
input_schema:
type: object
examples:
type: array
items: {}
ResourcesListResponse:
type: object
required: [version, resources]
properties:
version:
type: string
const: v1
resources:
type: array
items:
$ref: "#/components/schemas/ResourceListItem"
PromptsListResponse:
type: object
required: [version, prompts]
properties:
version:
type: string
const: v1
prompts:
type: array
items:
$ref: "#/components/schemas/PromptListItem"
CallCapabilityRequest:
type: object
required: [capability_id, args]
properties:
capability_id:
type: string
args:
type: object
request_id:
type: [string, "null"]
ReadResourceRequest:
type: object
required: [resource_id]
properties:
resource_id:
type: string
request_id:
type: [string, "null"]
GetPromptRequest:
type: object
required: [prompt_id]
properties:
prompt_id:
type: string
arguments:
type: [object, "null"]
request_id:
type: [string, "null"]
SuccessEnvelope:
type: object
required: [ok, request_id, trace_id, data, error]
properties:
ok:
type: boolean
const: true
request_id:
type: [string, "null"]
trace_id:
type: string
data: {}
error:
type: "null"
ErrorEnvelope:
type: object
required: [ok, request_id, trace_id, data, error]
properties:
ok:
type: boolean
const: false
request_id:
type: [string, "null"]
trace_id:
type: string
data:
type: "null"
error:
type: object
required: [code, message, retryable]
properties:
code:
type: string
enum:
- TOOL_NOT_FOUND
- RESOURCE_NOT_FOUND
- PROMPT_NOT_FOUND
- SERVER_UNREACHABLE
- INVALID_ARGS
- UPSTREAM_TIMEOUT
- UPSTREAM_ERROR
- INTERNAL_ERROR
message:
type: string
retryable:
type: boolean