From e0b56c53354e9b05c3bb171558a8a60b076f7218 Mon Sep 17 00:00:00 2001
From: Nate Barbettini <nate@arcade-ai.com>
Date: Mon, 17 Mar 2025 10:21:29 -0700
Subject: [PATCH 1/2] Move version to header and flatten responses

---
 spec/http/1.0/openapi.json | 112 ++++++++++++++++++++++---------------
 1 file changed, 68 insertions(+), 44 deletions(-)

diff --git a/spec/http/1.0/openapi.json b/spec/http/1.0/openapi.json
index 6388641..a2747ab 100644
--- a/spec/http/1.0/openapi.json
+++ b/spec/http/1.0/openapi.json
@@ -18,10 +18,20 @@
         "operationId": "health-check",
         "summary": "Check health",
         "description": "Checks the health status of the server.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/OXPVersionSelectorHeader"
+          }
+        ],
         "security": [{}],
         "responses": {
           "200": {
-            "description": "Server is healthy."
+            "description": "Server is healthy.",
+            "headers": {
+              "OXP-Version": {
+                "$ref": "#/components/headers/OXPServerHeader"
+              }
+            }
           },
           "503": {
             "description": "Server is unhealthy and cannot accept requests."
@@ -34,38 +44,29 @@
         "operationId": "list-tools",
         "summary": "List tools",
         "description": "Returns a list of tool definitions.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/OXPVersionSelectorHeader"
+          }
+        ],
         "security": [
           {
             "bearerAuth": []
           },
           {}
         ],
-        "requestBody": {
-          "required": false,
-          "content": {
-            "application/json": {
-              "schema": {
-                "properties": {
-                  "$schema": {
-                    "type": "string",
-                    "format": "uri"
-                  }
-                }
-              }
-            }
-          }
-        },
         "responses": {
           "200": {
             "description": "A list of available tools.",
+            "headers": {
+              "OXP-Version": {
+                "$ref": "#/components/headers/OXPServerHeader"
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
                   "properties": {
-                    "$schema": {
-                      "type": "string",
-                      "format": "uri"
-                    },
                     "items": {
                       "type": "array",
                       "items": {
@@ -79,7 +80,12 @@
             }
           },
           "401": {
-            "description": "Unauthorized. The request requires authentication, but the provided credentials are invalid or missing."
+            "description": "Unauthorized. The request requires authentication, but the provided credentials are invalid or missing.",
+            "headers": {
+              "OXP-Version": {
+                "$ref": "#/components/headers/OXPServerHeader"
+              }
+            }
           }
         }
       }
@@ -89,6 +95,11 @@
         "operationId": "call-tool",
         "summary": "Call tool",
         "description": "Calls a tool with the given parameters.",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/OXPVersionSelectorHeader"
+          }
+        ],
         "security": [
           {
             "bearerAuth": []
@@ -100,16 +111,7 @@
           "content": {
             "application/json": {
               "schema": {
-                "properties": {
-                  "$schema": {
-                    "type": "string",
-                    "format": "uri"
-                  },
-                  "request": {
-                    "$ref": "#/components/schemas/CallToolRequest"
-                  }
-                },
-                "required": ["request"]
+                "$ref": "#/components/schemas/CallToolRequest"
               }
             }
           }
@@ -117,25 +119,26 @@
         "responses": {
           "200": {
             "description": "Response from tool.",
+            "headers": {
+              "OXP-Version": {
+                "$ref": "#/components/headers/OXPServerHeader"
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
-                  "properties": {
-                    "$schema": {
-                      "type": "string",
-                      "format": "uri"
-                    },
-                    "result": {
-                      "$ref": "#/components/schemas/CallToolResponse"
-                    }
-                  },
-                  "required": ["result"]
+                  "$ref": "#/components/schemas/CallToolResponse"
                 }
               }
             }
           },
           "400": {
             "description": "The request is invalid or could not be processed.",
+            "headers": {
+              "OXP-Version": {
+                "$ref": "#/components/headers/OXPServerHeader"
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -144,11 +147,13 @@
               }
             }
           },
-          "401": {
-            "description": "Unauthorized. The request requires authentication, but the provided credentials are invalid or missing."
-          },
           "422": {
             "description": "The tool call is valid, but the parameters are invalid (missing, incorrect type, etc).",
+            "headers": {
+              "OXP-Version": {
+                "$ref": "#/components/headers/OXPServerHeader"
+              }
+            },
             "content": {
               "application/json": {
                 "schema": {
@@ -169,6 +174,25 @@
         "bearerFormat": "JWT"
       }
     },
+    "parameters": {
+      "OXPVersionSelectorHeader": {
+        "name": "OXP-Version",
+        "in": "header",
+        "description": "Optional header to specify the version of the OXP protocol to use.",
+        "required": false,
+        "schema": {
+          "type": "string"
+        }
+      }
+    },
+    "headers": {
+      "OXPServerHeader": {
+        "description": "The OXP version used by the server",
+        "schema": {
+          "type": "string"
+        }
+      }
+    },
     "schemas": {
       "ToolId": {
         "type": "string",

From bba345fec39ba02be131897d0c2a9fea53b544cd Mon Sep 17 00:00:00 2001
From: Nate Barbettini <nate@arcade-ai.com>
Date: Mon, 17 Mar 2025 10:25:35 -0700
Subject: [PATCH 2/2] Add to 503

---
 spec/http/1.0/openapi.json | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/spec/http/1.0/openapi.json b/spec/http/1.0/openapi.json
index a2747ab..74d16e3 100644
--- a/spec/http/1.0/openapi.json
+++ b/spec/http/1.0/openapi.json
@@ -34,7 +34,12 @@
             }
           },
           "503": {
-            "description": "Server is unhealthy and cannot accept requests."
+            "description": "Server is unhealthy and cannot accept requests.",
+            "headers": {
+              "OXP-Version": {
+                "$ref": "#/components/headers/OXPServerHeader"
+              }
+            }
           }
         }
       }