{
  "openapi": "3.0.1",
  "info": {
    "title": "Danube API",
    "description": "Tool discovery and execution platform for AI assistants",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.danubeai.com/v1"
    }
  ],
  "paths": {
    "/tools": {
      "get": {
        "summary": "List All Tools",
        "description": "Get a list of all available tools",
        "operationId": "listTools",
        "security": [
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "List of tools",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Tool"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid or missing API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tools/search": {
      "get": {
        "summary": "Search Tools",
        "description": "Search for tools by query. Matches against tool names and descriptions using semantic search.",
        "operationId": "searchTools",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "description": "Search query to match tool names and descriptions (e.g., 'get weather', 'fetch news')",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "service_id",
            "in": "query",
            "description": "Filter results to a specific service",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tags",
            "in": "query",
            "description": "Filter by tags",
            "required": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of matching tools",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Tool"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tools/{tool_id}": {
      "get": {
        "summary": "Get Tool by ID",
        "description": "Retrieve a specific tool by its unique identifier",
        "operationId": "getToolById",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "tool_id",
            "in": "path",
            "description": "The unique identifier of the tool",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tool details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Tool"
                }
              }
            }
          },
          "404": {
            "description": "Tool not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tools/name/{tool_name}": {
      "get": {
        "summary": "Get Tool by Name",
        "description": "Retrieve a specific tool by its name",
        "operationId": "getToolByName",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "tool_name",
            "in": "path",
            "description": "The name of the tool",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tool details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Tool"
                }
              }
            }
          },
          "404": {
            "description": "Tool not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tools/call/{tool_id}": {
      "post": {
        "summary": "Call Tool",
        "description": "Execute a tool with the provided input parameters",
        "operationId": "callTool",
        "security": [
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "tool_id",
            "in": "path",
            "description": "The unique identifier of the tool to execute",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "Tool input parameters",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ToolCallRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tool execution result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ToolCallResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Tool not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded or usage limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UsageLimitError"
                }
              }
            }
          }
        }
      }
    },
    "/services/public": {
      "get": {
        "summary": "List Services",
        "description": "Get all available services. No authentication required.",
        "operationId": "listServices",
        "responses": {
          "200": {
            "description": "List of services",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Service"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/services/public/{service_id}": {
      "get": {
        "summary": "Get Service",
        "description": "Get a specific service by ID. No authentication required.",
        "operationId": "getService",
        "parameters": [
          {
            "name": "service_id",
            "in": "path",
            "description": "The unique identifier of the service",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Service details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Service"
                }
              }
            }
          },
          "404": {
            "description": "Service not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/services/public/{service_id}/tools": {
      "get": {
        "summary": "Get Service Tools",
        "description": "Get all tools for a specific service. No authentication required.",
        "operationId": "getServiceTools",
        "parameters": [
          {
            "name": "service_id",
            "in": "path",
            "description": "The unique identifier of the service",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of tools for the service",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Tool"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Service not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Tool": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the tool"
          },
          "name": {
            "type": "string",
            "description": "Display name of the tool"
          },
          "description": {
            "type": "string",
            "description": "What the tool does"
          },
          "service_id": {
            "type": "string",
            "description": "ID of the service this tool belongs to"
          },
          "parameters": {
            "type": "object",
            "description": "JSON Schema defining the tool's input parameters"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "inactive"
            ],
            "description": "Whether the tool is currently active"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Tags for categorizing the tool"
          }
        }
      },
      "Service": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the service"
          },
          "name": {
            "type": "string",
            "description": "Display name of the service"
          },
          "description": {
            "type": "string",
            "description": "Service description"
          },
          "summary": {
            "type": "string",
            "description": "Short summary of the service"
          },
          "url": {
            "type": "string",
            "description": "Service website URL"
          },
          "logo_url": {
            "type": "string",
            "description": "URL to the service logo"
          },
          "version": {
            "type": "string",
            "description": "Service version"
          }
        }
      },
      "ToolCallRequest": {
        "type": "object",
        "properties": {
          "tool_input": {
            "type": "object",
            "description": "Input parameters for the tool (can also pass parameters directly at root level)"
          }
        },
        "example": {
          "tool_input": {
            "limit": 5
          }
        }
      },
      "ToolCallResponse": {
        "type": "object",
        "description": "Tool execution result - structure varies by tool"
      },
      "Error": {
        "type": "object",
        "properties": {
          "detail": {
            "type": "string",
            "description": "Error message"
          }
        }
      },
      "UsageLimitError": {
        "type": "object",
        "properties": {
          "detail": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string"
              },
              "usage": {
                "type": "object"
              },
              "upgrade_url": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "name": "danube-api-key",
        "in": "header",
        "description": "Your Danube API key"
      }
    }
  }
}