lda-wf/docs/openapi_capability_source.md

OpenAPI Capability Sources

OpenAPI sources expose raw API operations as workflow capabilities.

The OpenAPI document is the source of truth for operation inventory, public input names, JSON Schema contracts, request paths, request bodies, response schemas, and declared status codes. Runtime execution uses a generic httpx request builder plus openapi-core validation/unmarshalling. It does not parse generated Python clients and does not rename public OpenAPI fields.

Payload Shape

Workflow inputs stay OpenAPI-shaped:

{
  "path": {"petId": "pet-1"},
  "query": {"includeOwner": true},
  "header": {"X-Trace-ID": "trace-1"},
  "cookie": {},
  "body": {"name": "Fluffy"}
}

The workflow-facing field is petId, not a generated Python name like pet_id.

Outcomes

Raw OpenAPI nodes expose transport-level outcomes:

• ok: declared 2xx response and response validation passed.
• http_error: declared non-2xx response and response validation passed.
• unexpected_status: response status was not declared and no default response covered it.
• validation_error: request or response failed OpenAPI validation.
• transport_error: HTTP failed before a response existed.

Business outcomes such as not_found, rate_limited, or needs_input belong in saved wrappers, not raw OpenAPI operation nodes.

Current Limits

• Auth integration is future work. For now, source configuration owns the base URL only.
• Multipart, form, and binary request/response handling are future work.
• Rich business outcome mapping is wrapper territory.
• OpenAPI operation nodes are workflow capabilities, not top-level MCP tools.