{
  "openapi": "3.1.0",
  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
  "info": {
    "title": "ToolFable Agent Tools API",
    "version": "1.0.0",
    "description": "Stateless utilities for direct agent calls. Requests are limited to 131072 JSON bytes, processed in memory, not intentionally persisted by this API, and returned with Cache-Control: no-store."
  },
  "servers": [
    {
      "url": "https://toolfable.com",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Agent tools",
      "description": "Direct, stateless access to selected ToolFable engines."
    }
  ],
  "paths": {
    "/api/agent-tools": {
      "get": {
        "operationId": "getAgentToolsManifest",
        "summary": "Get the ToolFable agent-tools manifest",
        "tags": [
          "Agent tools"
        ],
        "responses": {
          "200": {
            "description": "Agent-tools manifest",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              },
              "Access-Control-Allow-Origin": {
                "$ref": "#/components/headers/AllowOrigin"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentToolsManifest"
                }
              }
            }
          }
        }
      },
      "options": {
        "operationId": "optionsAgentToolsManifest",
        "summary": "CORS preflight for the manifest",
        "tags": [
          "Agent tools"
        ],
        "responses": {
          "204": {
            "$ref": "#/components/responses/Preflight"
          }
        }
      }
    },
    "/api/agent-tools/agent-tool-schema-builder": {
      "post": {
        "operationId": "buildAgentToolSchema",
        "summary": "Build an agent tool schema",
        "description": "Normalize a JSON tool definition for OpenAI Responses function tools or MCP tools. Supported options are target, strict, and indent.",
        "tags": [
          "Agent tools"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentToolRequest"
              },
              "examples": {
                "toolDescription": {
                  "value": {
                    "input": "{\"name\":\"get_weather\",\"description\":\"Look up weather by city.\",\"parameters\":{\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\"}},\"required\":[\"city\"]}}",
                    "options": {
                      "target": "openai-responses",
                      "strict": true,
                      "indent": "2"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/ToolSuccess"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "415": {
            "$ref": "#/components/responses/UnsupportedMediaType"
          },
          "422": {
            "$ref": "#/components/responses/ToolExecutionError"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      },
      "options": {
        "operationId": "optionsAgentToolSchemaBuilder",
        "summary": "CORS preflight",
        "tags": [
          "Agent tools"
        ],
        "responses": {
          "204": {
            "$ref": "#/components/responses/Preflight"
          }
        }
      }
    },
    "/api/agent-tools/json-schema-generator": {
      "post": {
        "operationId": "generateJsonSchema",
        "summary": "Generate a JSON Schema",
        "description": "Generate a JSON Schema from representative JSON data without storing the supplied data. Supported options are includeRequired, additionalProperties, detectFormats, title, and indent.",
        "tags": [
          "Agent tools"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentToolRequest"
              },
              "examples": {
                "jsonDocument": {
                  "value": {
                    "input": "{\"name\":\"Ada\",\"active\":true}",
                    "options": {
                      "includeRequired": true,
                      "detectFormats": true
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/ToolSuccess"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "415": {
            "$ref": "#/components/responses/UnsupportedMediaType"
          },
          "422": {
            "$ref": "#/components/responses/ToolExecutionError"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      },
      "options": {
        "operationId": "optionsJsonSchemaGenerator",
        "summary": "CORS preflight",
        "tags": [
          "Agent tools"
        ],
        "responses": {
          "204": {
            "$ref": "#/components/responses/Preflight"
          }
        }
      }
    },
    "/api/agent-tools/jsonl-validator": {
      "post": {
        "operationId": "validateJsonl",
        "summary": "Validate JSONL",
        "description": "Validate newline-delimited JSON and return line-oriented validation feedback. Supported options are mode, allowBlankLines, objectOnly, and sortKeys.",
        "tags": [
          "Agent tools"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentToolRequest"
              },
              "examples": {
                "jsonLines": {
                  "value": {
                    "input": "{\"id\":1}\n{\"id\":2}",
                    "options": {
                      "mode": "validate",
                      "objectOnly": true
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/ToolSuccess"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "415": {
            "$ref": "#/components/responses/UnsupportedMediaType"
          },
          "422": {
            "$ref": "#/components/responses/ToolExecutionError"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      },
      "options": {
        "operationId": "optionsJsonlValidator",
        "summary": "CORS preflight",
        "tags": [
          "Agent tools"
        ],
        "responses": {
          "204": {
            "$ref": "#/components/responses/Preflight"
          }
        }
      }
    },
    "/api/agent-tools/prompt-template-renderer": {
      "post": {
        "operationId": "renderPromptTemplate",
        "summary": "Render a prompt template",
        "description": "Render a prompt template. Supply variables as a JSON object encoded in the variables option; missingVariable and prettyValues control rendering behavior.",
        "tags": [
          "Agent tools"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentToolRequest"
              },
              "examples": {
                "template": {
                  "value": {
                    "input": "Summarize {{topic}} for {{audience}}.",
                    "options": {
                      "variables": "{\"topic\":\"JSONL\",\"audience\":\"developers\"}",
                      "missingVariable": "error"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/ToolSuccess"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "415": {
            "$ref": "#/components/responses/UnsupportedMediaType"
          },
          "422": {
            "$ref": "#/components/responses/ToolExecutionError"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      },
      "options": {
        "operationId": "optionsPromptTemplateRenderer",
        "summary": "CORS preflight",
        "tags": [
          "Agent tools"
        ],
        "responses": {
          "204": {
            "$ref": "#/components/responses/Preflight"
          }
        }
      }
    }
  },
  "components": {
    "headers": {
      "CacheControl": {
        "description": "Responses are not cacheable.",
        "schema": {
          "type": "string",
          "const": "no-store"
        }
      },
      "AllowOrigin": {
        "description": "The API supports cross-origin agent calls.",
        "schema": {
          "type": "string",
          "const": "*"
        }
      }
    },
    "schemas": {
      "AgentToolRequest": {
        "type": "object",
        "description": "The complete serialized JSON body must not exceed 131072 bytes.",
        "required": [
          "input"
        ],
        "properties": {
          "input": {
            "type": "string",
            "description": "Tool input. Empty strings are accepted when the selected engine supports them."
          },
          "options": {
            "type": "object",
            "description": "Optional tool-specific settings.",
            "additionalProperties": {
              "type": [
                "string",
                "number",
                "boolean"
              ]
            }
          }
        },
        "additionalProperties": false
      },
      "AgentToolResult": {
        "type": "object",
        "required": [
          "output",
          "outputText"
        ],
        "properties": {
          "output": {
            "description": "Parsed JSON when the engine returns one JSON value; otherwise the same string as outputText."
          },
          "outputText": {
            "type": "string"
          },
          "outputHtml": {
            "type": "string",
            "description": "Optional presentation markup returned by an engine. Treat it as untrusted content."
          }
        },
        "additionalProperties": false
      },
      "AgentToolSuccess": {
        "type": "object",
        "required": [
          "ok",
          "tool",
          "result"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true
          },
          "tool": {
            "type": "string",
            "enum": [
              "agent-tool-schema-builder",
              "json-schema-generator",
              "jsonl-validator",
              "prompt-template-renderer"
            ]
          },
          "result": {
            "$ref": "#/components/schemas/AgentToolResult"
          }
        },
        "additionalProperties": false
      },
      "ApiError": {
        "type": "object",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "details": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "additionalProperties": false
      },
      "ApiErrorResponse": {
        "type": "object",
        "required": [
          "ok",
          "error"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "const": false
          },
          "error": {
            "$ref": "#/components/schemas/ApiError"
          }
        },
        "additionalProperties": false
      },
      "AgentToolsManifest": {
        "type": "object",
        "required": [
          "schemaVersion",
          "name",
          "baseUrl",
          "openapi",
          "privacy",
          "limits",
          "tools"
        ],
        "properties": {
          "schemaVersion": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "baseUrl": {
            "type": "string",
            "format": "uri"
          },
          "openapi": {
            "type": "string",
            "format": "uri"
          },
          "staticManifest": {
            "type": "string",
            "format": "uri"
          },
          "llms": {
            "type": "string",
            "format": "uri"
          },
          "privacy": {
            "type": "object"
          },
          "limits": {
            "type": "object"
          },
          "request": {
            "type": "object"
          },
          "response": {
            "type": "object"
          },
          "tools": {
            "type": "array",
            "minItems": 4,
            "maxItems": 4,
            "items": {
              "type": "object",
              "required": [
                "id",
                "name",
                "description",
                "method",
                "path",
                "input",
                "options"
              ],
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "method": {
                  "type": "string",
                  "const": "POST"
                },
                "path": {
                  "type": "string"
                },
                "input": {
                  "type": "string"
                },
                "options": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "string"
                  }
                }
              },
              "additionalProperties": false
            }
          }
        }
      }
    },
    "responses": {
      "ToolSuccess": {
        "description": "Tool execution completed successfully.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          },
          "Access-Control-Allow-Origin": {
            "$ref": "#/components/headers/AllowOrigin"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/AgentToolSuccess"
            }
          }
        }
      },
      "BadRequest": {
        "description": "Invalid JSON or request shape.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiErrorResponse"
            }
          }
        }
      },
      "BodyTooLarge": {
        "description": "The serialized JSON body exceeds 131072 bytes.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiErrorResponse"
            }
          }
        }
      },
      "UnsupportedMediaType": {
        "description": "Content-Type is not application/json.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiErrorResponse"
            }
          }
        }
      },
      "ToolExecutionError": {
        "description": "The selected engine rejected or could not process the supplied input.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiErrorResponse"
            }
          }
        }
      },
      "InternalError": {
        "description": "Unexpected engine or API failure.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ApiErrorResponse"
            }
          }
        }
      },
      "Preflight": {
        "description": "CORS preflight accepted.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          },
          "Access-Control-Allow-Origin": {
            "$ref": "#/components/headers/AllowOrigin"
          }
        }
      }
    }
  }
}