{
  "openapi": "3.1.0",
  "info": {
    "title": "ParaDaily Agent Tools",
    "version": "1.0.0",
    "description": "Read-only tool-call-ready API for retrieving ParaDaily article metadata, Markdown articles, and RAG-friendly chunks.",
    "contact": {
      "name": "Simmy Chen (陈芯牧 / Xinmu Chen)",
      "url": "https://simmychen.com/about"
    },
    "x-publisher": {
      "name": "ParaDaily",
      "url": "https://paradaily.com",
      "founder": "Simmy Chen (Xinmu Chen / 陈芯牧)",
      "founderProfile": "https://simmychen.com/about"
    }
  },
  "servers": [
    {
      "url": "https://paradaily.com"
    }
  ],
  "paths": {
    "/api/v1/tools/search": {
      "post": {
        "operationId": "search_simmyresearch",
        "summary": "Search ParaDaily articles",
        "description": "Search article metadata by query, tag, or category and return compact article summaries.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ToolResult"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tools/get_article": {
      "post": {
        "operationId": "get_simmyresearch_article",
        "summary": "Get a full ParaDaily article",
        "description": "Fetch one article by slug. Can include RAG chunks when includeChunks is true or include is chunks/full.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GetArticleRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Article payload",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ToolResult"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tools/get_chunks": {
      "post": {
        "operationId": "get_simmyresearch_chunks",
        "summary": "Get RAG-friendly chunks for one article",
        "description": "Fetch structured chunks by article slug, optionally filtered by a query string.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GetChunksRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Chunk list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ToolResult"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/articles": {
      "get": {
        "operationId": "list_simmyresearch_articles",
        "summary": "List articles",
        "parameters": [
          {
            "name": "tag",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Article list"
          }
        }
      }
    },
    "/api/v1/article": {
      "get": {
        "operationId": "get_simmyresearch_article_get",
        "summary": "Get article by slug",
        "parameters": [
          {
            "name": "slug",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["chunks"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Article payload"
          }
        }
      }
    },
    "/api/v1/chunks": {
      "get": {
        "operationId": "get_simmyresearch_chunks_get",
        "summary": "Get chunks by slug",
        "parameters": [
          {
            "name": "slug",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Chunk list"
          }
        }
      }
    },
    "/api/v1/search": {
      "get": {
        "operationId": "search_simmyresearch_get",
        "summary": "Search articles by query",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Search results"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SearchRequest": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "Search query across title, summary, source, tags, and metadata."
          },
          "tag": {
            "type": "string",
            "description": "Optional exact tag filter."
          },
          "category": {
            "type": "string",
            "description": "Optional exact category filter."
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 20,
            "default": 8
          }
        },
        "anyOf": [
          {
            "required": ["query"]
          },
          {
            "required": ["tag"]
          },
          {
            "required": ["category"]
          }
        ],
        "additionalProperties": false
      },
      "GetArticleRequest": {
        "type": "object",
        "required": ["slug"],
        "properties": {
          "slug": {
            "type": "string",
            "description": "Article slug."
          },
          "include": {
            "type": "string",
            "enum": ["metadata", "full", "chunks"],
            "description": "Use chunks or full to include chunk data."
          },
          "includeChunks": {
            "type": "boolean",
            "default": false
          }
        },
        "additionalProperties": false
      },
      "GetChunksRequest": {
        "type": "object",
        "required": ["slug"],
        "properties": {
          "slug": {
            "type": "string",
            "description": "Article slug."
          },
          "query": {
            "type": "string",
            "description": "Optional chunk text filter."
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 80,
            "default": 30
          }
        },
        "additionalProperties": false
      },
      "ToolResult": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "const": "tool_result"
          },
          "tool": {
            "type": "string"
          },
          "input": {
            "type": "object"
          },
          "data": {},
          "generatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": ["object", "tool", "input", "data", "generatedAt"]
      }
    }
  }
}