diff --git a/docs/openapi-ingestion.md b/docs/openapi-ingestion.md index 779fc12..81adcd7 100644 --- a/docs/openapi-ingestion.md +++ b/docs/openapi-ingestion.md @@ -1,6 +1,6 @@ # OpenAPI Ingestion Methods in python-utcp -UTCP automatically converts OpenAPI 2.0/3.0 specifications into UTCP tools, enabling AI agents to interact with REST APIs without requiring server modifications or additional infrastructure. +UTCP automatically converts OpenAPI 2.0/3.0 specifications, plus compatible OpenAPI 3.1 specifications, into UTCP tools, enabling AI agents to interact with REST APIs without requiring server modifications or additional infrastructure. ## Method 1: Direct OpenAPI Converter @@ -53,6 +53,40 @@ async def load_remote_spec(url): manual = await load_remote_spec("https://api.example.com/openapi.json") ``` +### Xquik API Example + +Xquik publishes an OpenAPI 3.1 specification for its X data API at +`https://xquik.com/openapi.json`. It can be loaded the same way as any other +remote OpenAPI document: + +```python +manual = await load_remote_spec("https://xquik.com/openapi.json") + +print(f"Generated {len(manual.tools)} Xquik tools") +``` + +When calling authenticated endpoints, provide the API key through the +`x-api-key` header and keep the value in an injected variable: + +```python +config = { + "manual_call_templates": [ + { + "name": "xquik", + "call_template_type": "http", + "url": "https://xquik.com/openapi.json", + "http_method": "GET", + "auth": { + "auth_type": "api_key", + "api_key": "${XQUIK_API_KEY}", + "var_name": "x-api-key", + "location": "header" + } + } + ] +} +``` + ## Method 3: UTCP Client Configuration Include OpenAPI specs directly in your UTCP client configuration. @@ -137,6 +171,7 @@ OpenAPI security schemes automatically convert to UTCP auth objects: ### Multi-format Support - **OpenAPI 2.0 & 3.0**: Full compatibility +- **OpenAPI 3.1**: Compatible specifications can be loaded, but verify 3.1-specific schema features against the converter - **JSON & YAML**: Automatic format detection - **Local & Remote**: Files or URLs