{
  "openapi": "3.0.3",
  "info": {
    "title": "Academic Data API",
    "version": "1.0.0",
    "description": "Structured academic data API with API key authentication and usage tracking."
  },
  "servers": [
    {
      "url": "https://link.cljtscd.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "required": [
          "status",
          "message",
          "request_id",
          "data",
          "meta",
          "error_code"
        ],
        "properties": {
          "status": {
            "type": "string",
            "example": "error"
          },
          "message": {
            "type": "string",
            "example": "Invalid parameters"
          },
          "request_id": {
            "type": "string",
            "example": "req_1780990000000_ab12cd34"
          },
          "error_code": {
            "type": "string",
            "example": "invalid_parameters"
          },
          "data": {
            "type": "object"
          },
          "meta": {
            "type": "object"
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "field": {
                  "type": "string",
                  "example": "q"
                },
                "message": {
                  "type": "string",
                  "example": "q is required"
                }
              }
            }
          }
        }
      },
      "StructuredResponse": {
        "type": "object",
        "required": [
          "status",
          "message",
          "request_id",
          "data",
          "meta"
        ],
        "properties": {
          "status": {
            "type": "string",
            "example": "success"
          },
          "message": {
            "type": "string",
            "example": "ok"
          },
          "request_id": {
            "type": "string"
          },
          "data": {
            "type": "object",
            "properties": {
              "schema_version": {
                "type": "string"
              },
              "format": {
                "type": "string",
                "example": "structured"
              },
              "endpoint": {
                "type": "string"
              },
              "item_count": {
                "type": "integer"
              },
              "items": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "rank": {
                      "type": "integer"
                    },
                    "title": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    },
                    "authors": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "abstract": {
                      "type": "string",
                      "nullable": true
                    },
                    "snippet": {
                      "type": "string"
                    },
                    "cited_by_count": {
                      "type": "integer",
                      "nullable": true
                    },
                    "year": {
                      "type": "integer",
                      "nullable": true
                    },
                    "source": {
                      "type": "string"
                    },
                    "publisher": {
                      "type": "string"
                    },
                    "journal": {
                      "type": "string"
                    },
                    "venue": {
                      "type": "string"
                    },
                    "domain": {
                      "type": "string"
                    },
                    "pdf_url": {
                      "type": "string",
                      "nullable": true
                    },
                    "resource_type": {
                      "type": "string",
                      "nullable": true
                    },
                    "cluster_id": {
                      "type": "string",
                      "nullable": true
                    },
                    "single_cluster_id": {
                      "type": "string",
                      "nullable": true
                    },
                    "cluster_ids": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "cited_by_path": {
                      "type": "string"
                    },
                    "related_path": {
                      "type": "string"
                    },
                    "citation_detail_url": {
                      "type": "string"
                    },
                    "author_profiles": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "document_id": {
                      "type": "string"
                    },
                    "field_completeness": {
                      "type": "number"
                    }
                  }
                }
              },
              "parse_status": {
                "type": "string",
                "example": "ok"
              }
            }
          },
          "meta": {
            "type": "object"
          }
        }
      },
      "UsageResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "success"
          },
          "message": {
            "type": "string",
            "example": "ok"
          },
          "request_id": {
            "type": "string"
          },
          "data": {
            "type": "object",
            "properties": {
              "daily_limit": {
                "type": "integer"
              },
              "daily_used": {
                "type": "integer"
              },
              "daily_remaining": {
                "type": "integer"
              },
              "total_limit": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "total_requests": {
                "type": "integer"
              },
              "total_remaining": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "last_used_at": {
                "type": "string",
                "nullable": true
              },
              "created_at": {
                "type": "string"
              },
              "usage_detail": {
                "type": "object",
                "properties": {
                  "timezone": {
                    "type": "string",
                    "example": "Asia/Shanghai"
                  },
                  "today": {
                    "type": "object",
                    "properties": {
                      "date": {
                        "type": "string",
                        "example": "2026-06-10"
                      },
                      "count": {
                        "type": "integer",
                        "example": 12
                      }
                    }
                  },
                  "current_month": {
                    "type": "object",
                    "properties": {
                      "month": {
                        "type": "string",
                        "example": "2026-06"
                      },
                      "total": {
                        "type": "integer",
                        "example": 120
                      },
                      "daily": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "date": {
                              "type": "string",
                              "example": "2026-06-01"
                            },
                            "count": {
                              "type": "integer",
                              "example": 8
                            }
                          }
                        }
                      }
                    }
                  },
                  "previous_month": {
                    "type": "object",
                    "properties": {
                      "month": {
                        "type": "string",
                        "example": "2026-05"
                      },
                      "total": {
                        "type": "integer",
                        "example": 88
                      }
                    }
                  }
                }
              }
            }
          },
          "meta": {
            "type": "object"
          }
        }
      },
      "ResultItem": {
        "type": "object",
        "properties": {
          "rank": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "authors": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "abstract": {
            "type": "string",
            "nullable": true
          },
          "snippet": {
            "type": "string"
          },
          "cited_by_count": {
            "type": "integer",
            "nullable": true
          },
          "year": {
            "type": "integer",
            "nullable": true
          },
          "source": {
            "type": "string"
          },
          "publisher": {
            "type": "string"
          },
          "journal": {
            "type": "string"
          },
          "venue": {
            "type": "string"
          },
          "domain": {
            "type": "string"
          },
          "pdf_url": {
            "type": "string",
            "nullable": true
          },
          "resource_type": {
            "type": "string",
            "nullable": true
          },
          "cluster_id": {
            "type": "string",
            "nullable": true
          },
          "single_cluster_id": {
            "type": "string",
            "nullable": true
          },
          "cluster_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "cited_by_path": {
            "type": "string"
          },
          "related_path": {
            "type": "string"
          },
          "citation_detail_url": {
            "type": "string"
          },
          "author_profiles": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "document_id": {
            "type": "string"
          },
          "field_completeness": {
            "type": "number"
          }
        }
      }
    }
  },
  "paths": {
    "/health": {
      "get": {
        "summary": "Health check",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/search": {
      "get": {
        "summary": "Search records",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "hl",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "zh-CN"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Structured search results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "message",
                    "request_id",
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "success"
                    },
                    "message": {
                      "type": "string",
                      "example": "ok"
                    },
                    "request_id": {
                      "type": "string"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "schema_version": {
                          "type": "string"
                        },
                        "format": {
                          "type": "string",
                          "example": "structured"
                        },
                        "endpoint": {
                          "type": "string"
                        },
                        "item_count": {
                          "type": "integer"
                        },
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "rank": {
                                "type": "integer"
                              },
                              "title": {
                                "type": "string"
                              },
                              "url": {
                                "type": "string"
                              },
                              "authors": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "abstract": {
                                "type": "string",
                                "nullable": true
                              },
                              "snippet": {
                                "type": "string"
                              },
                              "cited_by_count": {
                                "type": "integer",
                                "nullable": true
                              },
                              "year": {
                                "type": "integer",
                                "nullable": true
                              },
                              "source": {
                                "type": "string"
                              },
                              "publisher": {
                                "type": "string"
                              },
                              "journal": {
                                "type": "string"
                              },
                              "venue": {
                                "type": "string"
                              },
                              "domain": {
                                "type": "string"
                              },
                              "pdf_url": {
                                "type": "string",
                                "nullable": true
                              },
                              "resource_type": {
                                "type": "string",
                                "nullable": true
                              },
                              "cluster_id": {
                                "type": "string",
                                "nullable": true
                              },
                              "single_cluster_id": {
                                "type": "string",
                                "nullable": true
                              },
                              "cluster_ids": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "cited_by_path": {
                                "type": "string"
                              },
                              "related_path": {
                                "type": "string"
                              },
                              "citation_detail_url": {
                                "type": "string"
                              },
                              "author_profiles": {
                                "type": "array",
                                "items": {
                                  "type": "object"
                                }
                              },
                              "document_id": {
                                "type": "string"
                              },
                              "field_completeness": {
                                "type": "number"
                              }
                            }
                          }
                        },
                        "parse_status": {
                          "type": "string",
                          "example": "ok"
                        }
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "message",
                    "request_id",
                    "data",
                    "meta",
                    "error_code"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "error"
                    },
                    "message": {
                      "type": "string",
                      "example": "Invalid parameters"
                    },
                    "request_id": {
                      "type": "string",
                      "example": "req_1780990000000_ab12cd34"
                    },
                    "error_code": {
                      "type": "string",
                      "example": "invalid_parameters"
                    },
                    "data": {
                      "type": "object"
                    },
                    "meta": {
                      "type": "object"
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "field": {
                            "type": "string",
                            "example": "q"
                          },
                          "message": {
                            "type": "string",
                            "example": "q is required"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "message",
                    "request_id",
                    "data",
                    "meta",
                    "error_code"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "error"
                    },
                    "message": {
                      "type": "string",
                      "example": "Invalid parameters"
                    },
                    "request_id": {
                      "type": "string",
                      "example": "req_1780990000000_ab12cd34"
                    },
                    "error_code": {
                      "type": "string",
                      "example": "invalid_parameters"
                    },
                    "data": {
                      "type": "object"
                    },
                    "meta": {
                      "type": "object"
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "field": {
                            "type": "string",
                            "example": "q"
                          },
                          "message": {
                            "type": "string",
                            "example": "q is required"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "message",
                    "request_id",
                    "data",
                    "meta",
                    "error_code"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "error"
                    },
                    "message": {
                      "type": "string",
                      "example": "Invalid parameters"
                    },
                    "request_id": {
                      "type": "string",
                      "example": "req_1780990000000_ab12cd34"
                    },
                    "error_code": {
                      "type": "string",
                      "example": "invalid_parameters"
                    },
                    "data": {
                      "type": "object"
                    },
                    "meta": {
                      "type": "object"
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "field": {
                            "type": "string",
                            "example": "q"
                          },
                          "message": {
                            "type": "string",
                            "example": "q is required"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "Data fetch failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "message",
                    "request_id",
                    "data",
                    "meta",
                    "error_code"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "error"
                    },
                    "message": {
                      "type": "string",
                      "example": "Invalid parameters"
                    },
                    "request_id": {
                      "type": "string",
                      "example": "req_1780990000000_ab12cd34"
                    },
                    "error_code": {
                      "type": "string",
                      "example": "invalid_parameters"
                    },
                    "data": {
                      "type": "object"
                    },
                    "meta": {
                      "type": "object"
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "field": {
                            "type": "string",
                            "example": "q"
                          },
                          "message": {
                            "type": "string",
                            "example": "q is required"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/author": {
      "get": {
        "summary": "Get author profile",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "author_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "hl",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Structured author profile",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "message",
                    "request_id",
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "success"
                    },
                    "message": {
                      "type": "string",
                      "example": "ok"
                    },
                    "request_id": {
                      "type": "string"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "schema_version": {
                          "type": "string"
                        },
                        "format": {
                          "type": "string",
                          "example": "structured"
                        },
                        "endpoint": {
                          "type": "string"
                        },
                        "item_count": {
                          "type": "integer"
                        },
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "rank": {
                                "type": "integer"
                              },
                              "title": {
                                "type": "string"
                              },
                              "url": {
                                "type": "string"
                              },
                              "authors": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "abstract": {
                                "type": "string",
                                "nullable": true
                              },
                              "snippet": {
                                "type": "string"
                              },
                              "cited_by_count": {
                                "type": "integer",
                                "nullable": true
                              },
                              "year": {
                                "type": "integer",
                                "nullable": true
                              },
                              "source": {
                                "type": "string"
                              },
                              "publisher": {
                                "type": "string"
                              },
                              "journal": {
                                "type": "string"
                              },
                              "venue": {
                                "type": "string"
                              },
                              "domain": {
                                "type": "string"
                              },
                              "pdf_url": {
                                "type": "string",
                                "nullable": true
                              },
                              "resource_type": {
                                "type": "string",
                                "nullable": true
                              },
                              "cluster_id": {
                                "type": "string",
                                "nullable": true
                              },
                              "single_cluster_id": {
                                "type": "string",
                                "nullable": true
                              },
                              "cluster_ids": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "cited_by_path": {
                                "type": "string"
                              },
                              "related_path": {
                                "type": "string"
                              },
                              "citation_detail_url": {
                                "type": "string"
                              },
                              "author_profiles": {
                                "type": "array",
                                "items": {
                                  "type": "object"
                                }
                              },
                              "document_id": {
                                "type": "string"
                              },
                              "field_completeness": {
                                "type": "number"
                              }
                            }
                          }
                        },
                        "parse_status": {
                          "type": "string",
                          "example": "ok"
                        }
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "message",
                    "request_id",
                    "data",
                    "meta",
                    "error_code"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "error"
                    },
                    "message": {
                      "type": "string",
                      "example": "Invalid parameters"
                    },
                    "request_id": {
                      "type": "string",
                      "example": "req_1780990000000_ab12cd34"
                    },
                    "error_code": {
                      "type": "string",
                      "example": "invalid_parameters"
                    },
                    "data": {
                      "type": "object"
                    },
                    "meta": {
                      "type": "object"
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "field": {
                            "type": "string",
                            "example": "q"
                          },
                          "message": {
                            "type": "string",
                            "example": "q is required"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "message",
                    "request_id",
                    "data",
                    "meta",
                    "error_code"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "error"
                    },
                    "message": {
                      "type": "string",
                      "example": "Invalid parameters"
                    },
                    "request_id": {
                      "type": "string",
                      "example": "req_1780990000000_ab12cd34"
                    },
                    "error_code": {
                      "type": "string",
                      "example": "invalid_parameters"
                    },
                    "data": {
                      "type": "object"
                    },
                    "meta": {
                      "type": "object"
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "field": {
                            "type": "string",
                            "example": "q"
                          },
                          "message": {
                            "type": "string",
                            "example": "q is required"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "message",
                    "request_id",
                    "data",
                    "meta",
                    "error_code"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "error"
                    },
                    "message": {
                      "type": "string",
                      "example": "Invalid parameters"
                    },
                    "request_id": {
                      "type": "string",
                      "example": "req_1780990000000_ab12cd34"
                    },
                    "error_code": {
                      "type": "string",
                      "example": "invalid_parameters"
                    },
                    "data": {
                      "type": "object"
                    },
                    "meta": {
                      "type": "object"
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "field": {
                            "type": "string",
                            "example": "q"
                          },
                          "message": {
                            "type": "string",
                            "example": "q is required"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "Data fetch failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "message",
                    "request_id",
                    "data",
                    "meta",
                    "error_code"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "error"
                    },
                    "message": {
                      "type": "string",
                      "example": "Invalid parameters"
                    },
                    "request_id": {
                      "type": "string",
                      "example": "req_1780990000000_ab12cd34"
                    },
                    "error_code": {
                      "type": "string",
                      "example": "invalid_parameters"
                    },
                    "data": {
                      "type": "object"
                    },
                    "meta": {
                      "type": "object"
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "field": {
                            "type": "string",
                            "example": "q"
                          },
                          "message": {
                            "type": "string",
                            "example": "q is required"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/citations": {
      "get": {
        "summary": "Get citation records",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "cluster_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "hl",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Structured citation records",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "message",
                    "request_id",
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "success"
                    },
                    "message": {
                      "type": "string",
                      "example": "ok"
                    },
                    "request_id": {
                      "type": "string"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "schema_version": {
                          "type": "string"
                        },
                        "format": {
                          "type": "string",
                          "example": "structured"
                        },
                        "endpoint": {
                          "type": "string"
                        },
                        "item_count": {
                          "type": "integer"
                        },
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "rank": {
                                "type": "integer"
                              },
                              "title": {
                                "type": "string"
                              },
                              "url": {
                                "type": "string"
                              },
                              "authors": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "abstract": {
                                "type": "string",
                                "nullable": true
                              },
                              "snippet": {
                                "type": "string"
                              },
                              "cited_by_count": {
                                "type": "integer",
                                "nullable": true
                              },
                              "year": {
                                "type": "integer",
                                "nullable": true
                              },
                              "source": {
                                "type": "string"
                              },
                              "publisher": {
                                "type": "string"
                              },
                              "journal": {
                                "type": "string"
                              },
                              "venue": {
                                "type": "string"
                              },
                              "domain": {
                                "type": "string"
                              },
                              "pdf_url": {
                                "type": "string",
                                "nullable": true
                              },
                              "resource_type": {
                                "type": "string",
                                "nullable": true
                              },
                              "cluster_id": {
                                "type": "string",
                                "nullable": true
                              },
                              "single_cluster_id": {
                                "type": "string",
                                "nullable": true
                              },
                              "cluster_ids": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "cited_by_path": {
                                "type": "string"
                              },
                              "related_path": {
                                "type": "string"
                              },
                              "citation_detail_url": {
                                "type": "string"
                              },
                              "author_profiles": {
                                "type": "array",
                                "items": {
                                  "type": "object"
                                }
                              },
                              "document_id": {
                                "type": "string"
                              },
                              "field_completeness": {
                                "type": "number"
                              }
                            }
                          }
                        },
                        "parse_status": {
                          "type": "string",
                          "example": "ok"
                        }
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "message",
                    "request_id",
                    "data",
                    "meta",
                    "error_code"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "error"
                    },
                    "message": {
                      "type": "string",
                      "example": "Invalid parameters"
                    },
                    "request_id": {
                      "type": "string",
                      "example": "req_1780990000000_ab12cd34"
                    },
                    "error_code": {
                      "type": "string",
                      "example": "invalid_parameters"
                    },
                    "data": {
                      "type": "object"
                    },
                    "meta": {
                      "type": "object"
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "field": {
                            "type": "string",
                            "example": "q"
                          },
                          "message": {
                            "type": "string",
                            "example": "q is required"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "message",
                    "request_id",
                    "data",
                    "meta",
                    "error_code"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "error"
                    },
                    "message": {
                      "type": "string",
                      "example": "Invalid parameters"
                    },
                    "request_id": {
                      "type": "string",
                      "example": "req_1780990000000_ab12cd34"
                    },
                    "error_code": {
                      "type": "string",
                      "example": "invalid_parameters"
                    },
                    "data": {
                      "type": "object"
                    },
                    "meta": {
                      "type": "object"
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "field": {
                            "type": "string",
                            "example": "q"
                          },
                          "message": {
                            "type": "string",
                            "example": "q is required"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "message",
                    "request_id",
                    "data",
                    "meta",
                    "error_code"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "error"
                    },
                    "message": {
                      "type": "string",
                      "example": "Invalid parameters"
                    },
                    "request_id": {
                      "type": "string",
                      "example": "req_1780990000000_ab12cd34"
                    },
                    "error_code": {
                      "type": "string",
                      "example": "invalid_parameters"
                    },
                    "data": {
                      "type": "object"
                    },
                    "meta": {
                      "type": "object"
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "field": {
                            "type": "string",
                            "example": "q"
                          },
                          "message": {
                            "type": "string",
                            "example": "q is required"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "Data fetch failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "message",
                    "request_id",
                    "data",
                    "meta",
                    "error_code"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "error"
                    },
                    "message": {
                      "type": "string",
                      "example": "Invalid parameters"
                    },
                    "request_id": {
                      "type": "string",
                      "example": "req_1780990000000_ab12cd34"
                    },
                    "error_code": {
                      "type": "string",
                      "example": "invalid_parameters"
                    },
                    "data": {
                      "type": "object"
                    },
                    "meta": {
                      "type": "object"
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "field": {
                            "type": "string",
                            "example": "q"
                          },
                          "message": {
                            "type": "string",
                            "example": "q is required"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/related": {
      "get": {
        "summary": "Get related records",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "cluster_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "hl",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Structured related records",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "message",
                    "request_id",
                    "data",
                    "meta"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "success"
                    },
                    "message": {
                      "type": "string",
                      "example": "ok"
                    },
                    "request_id": {
                      "type": "string"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "schema_version": {
                          "type": "string"
                        },
                        "format": {
                          "type": "string",
                          "example": "structured"
                        },
                        "endpoint": {
                          "type": "string"
                        },
                        "item_count": {
                          "type": "integer"
                        },
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "rank": {
                                "type": "integer"
                              },
                              "title": {
                                "type": "string"
                              },
                              "url": {
                                "type": "string"
                              },
                              "authors": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "abstract": {
                                "type": "string",
                                "nullable": true
                              },
                              "snippet": {
                                "type": "string"
                              },
                              "cited_by_count": {
                                "type": "integer",
                                "nullable": true
                              },
                              "year": {
                                "type": "integer",
                                "nullable": true
                              },
                              "source": {
                                "type": "string"
                              },
                              "publisher": {
                                "type": "string"
                              },
                              "journal": {
                                "type": "string"
                              },
                              "venue": {
                                "type": "string"
                              },
                              "domain": {
                                "type": "string"
                              },
                              "pdf_url": {
                                "type": "string",
                                "nullable": true
                              },
                              "resource_type": {
                                "type": "string",
                                "nullable": true
                              },
                              "cluster_id": {
                                "type": "string",
                                "nullable": true
                              },
                              "single_cluster_id": {
                                "type": "string",
                                "nullable": true
                              },
                              "cluster_ids": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "cited_by_path": {
                                "type": "string"
                              },
                              "related_path": {
                                "type": "string"
                              },
                              "citation_detail_url": {
                                "type": "string"
                              },
                              "author_profiles": {
                                "type": "array",
                                "items": {
                                  "type": "object"
                                }
                              },
                              "document_id": {
                                "type": "string"
                              },
                              "field_completeness": {
                                "type": "number"
                              }
                            }
                          }
                        },
                        "parse_status": {
                          "type": "string",
                          "example": "ok"
                        }
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "message",
                    "request_id",
                    "data",
                    "meta",
                    "error_code"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "error"
                    },
                    "message": {
                      "type": "string",
                      "example": "Invalid parameters"
                    },
                    "request_id": {
                      "type": "string",
                      "example": "req_1780990000000_ab12cd34"
                    },
                    "error_code": {
                      "type": "string",
                      "example": "invalid_parameters"
                    },
                    "data": {
                      "type": "object"
                    },
                    "meta": {
                      "type": "object"
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "field": {
                            "type": "string",
                            "example": "q"
                          },
                          "message": {
                            "type": "string",
                            "example": "q is required"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "message",
                    "request_id",
                    "data",
                    "meta",
                    "error_code"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "error"
                    },
                    "message": {
                      "type": "string",
                      "example": "Invalid parameters"
                    },
                    "request_id": {
                      "type": "string",
                      "example": "req_1780990000000_ab12cd34"
                    },
                    "error_code": {
                      "type": "string",
                      "example": "invalid_parameters"
                    },
                    "data": {
                      "type": "object"
                    },
                    "meta": {
                      "type": "object"
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "field": {
                            "type": "string",
                            "example": "q"
                          },
                          "message": {
                            "type": "string",
                            "example": "q is required"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "message",
                    "request_id",
                    "data",
                    "meta",
                    "error_code"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "error"
                    },
                    "message": {
                      "type": "string",
                      "example": "Invalid parameters"
                    },
                    "request_id": {
                      "type": "string",
                      "example": "req_1780990000000_ab12cd34"
                    },
                    "error_code": {
                      "type": "string",
                      "example": "invalid_parameters"
                    },
                    "data": {
                      "type": "object"
                    },
                    "meta": {
                      "type": "object"
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "field": {
                            "type": "string",
                            "example": "q"
                          },
                          "message": {
                            "type": "string",
                            "example": "q is required"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "Data fetch failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "message",
                    "request_id",
                    "data",
                    "meta",
                    "error_code"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "error"
                    },
                    "message": {
                      "type": "string",
                      "example": "Invalid parameters"
                    },
                    "request_id": {
                      "type": "string",
                      "example": "req_1780990000000_ab12cd34"
                    },
                    "error_code": {
                      "type": "string",
                      "example": "invalid_parameters"
                    },
                    "data": {
                      "type": "object"
                    },
                    "meta": {
                      "type": "object"
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "field": {
                            "type": "string",
                            "example": "q"
                          },
                          "message": {
                            "type": "string",
                            "example": "q is required"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/usage": {
      "get": {
        "summary": "Get current key usage",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Usage summary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "success"
                    },
                    "message": {
                      "type": "string",
                      "example": "ok"
                    },
                    "request_id": {
                      "type": "string"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "daily_limit": {
                          "type": "integer"
                        },
                        "daily_used": {
                          "type": "integer"
                        },
                        "daily_remaining": {
                          "type": "integer"
                        },
                        "total_limit": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "total_requests": {
                          "type": "integer"
                        },
                        "total_remaining": {
                          "type": [
                            "integer",
                            "null"
                          ]
                        },
                        "last_used_at": {
                          "type": "string",
                          "nullable": true
                        },
                        "created_at": {
                          "type": "string"
                        },
                        "usage_detail": {
                          "type": "object",
                          "properties": {
                            "timezone": {
                              "type": "string",
                              "example": "Asia/Shanghai"
                            },
                            "today": {
                              "type": "object",
                              "properties": {
                                "date": {
                                  "type": "string",
                                  "example": "2026-06-10"
                                },
                                "count": {
                                  "type": "integer",
                                  "example": 12
                                }
                              }
                            },
                            "current_month": {
                              "type": "object",
                              "properties": {
                                "month": {
                                  "type": "string",
                                  "example": "2026-06"
                                },
                                "total": {
                                  "type": "integer",
                                  "example": 120
                                },
                                "daily": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "date": {
                                        "type": "string",
                                        "example": "2026-06-01"
                                      },
                                      "count": {
                                        "type": "integer",
                                        "example": 8
                                      }
                                    }
                                  }
                                }
                              }
                            },
                            "previous_month": {
                              "type": "object",
                              "properties": {
                                "month": {
                                  "type": "string",
                                  "example": "2026-05"
                                },
                                "total": {
                                  "type": "integer",
                                  "example": 88
                                }
                              }
                            }
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "message",
                    "request_id",
                    "data",
                    "meta",
                    "error_code"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "error"
                    },
                    "message": {
                      "type": "string",
                      "example": "Invalid parameters"
                    },
                    "request_id": {
                      "type": "string",
                      "example": "req_1780990000000_ab12cd34"
                    },
                    "error_code": {
                      "type": "string",
                      "example": "invalid_parameters"
                    },
                    "data": {
                      "type": "object"
                    },
                    "meta": {
                      "type": "object"
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "field": {
                            "type": "string",
                            "example": "q"
                          },
                          "message": {
                            "type": "string",
                            "example": "q is required"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}