{
    "openapi": "3.0.3",
    "info": {
        "title": "Conference Partner API",
        "description": "Read-only REST API over the Conference Partner dataset: academic conferences and journals with CFPs, deadlines, locations, CCF / ICORE / QUALIS rankings, curated ranking lists and site statistics. Authentication: either a free-account JWT (POST /api/login; subject to a shared daily quota across this API and the MCP server at POST /mcp) or per-request x402 payment (HTTP 402 flow at the edge). Free responses link each venue to its canonical Conference Partner detail_page and never expose the external website; paid detail requests additionally include the official website URL. See https://www.myhuiban.com/methodology for ranking definitions and update cadence.",
        "version": "1.2.0",
        "contact": {
            "name": "Conference Partner",
            "url": "https://www.myhuiban.com/",
            "email": "admin@myhuiban.com"
        }
    },
    "servers": [
        {
            "url": "https://www.myhuiban.com",
            "description": "Current environment"
        },
        {
            "url": "https://www.myhuiban.com",
            "description": "Production"
        }
    ],
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "bearerFormat": "JWT",
                "description": "JWT issued by POST /api/login (free account). Send as `Authorization: Bearer <token>`. Subject to a daily quota shared with the MCP server; quota exhaustion returns HTTP 402."
            },
            "paidAccess": {
                "type": "apiKey",
                "in": "header",
                "name": "X-Paid-Access",
                "description": "Per-request x402 payment channel: after the edge verifies an x402 payment it injects this header. Not obtainable by clients directly — pay via the HTTP 402 flow instead. Paid detail requests include the venue's official website URL."
            }
        },
        "schemas": {
            "ApiResponse": {
                "type": "object",
                "description": "Uniform envelope: business code mirrors HTTP semantics (200 success; validation errors return HTTP 200 with code 400 in the body; missing entities return HTTP 404).",
                "properties": {
                    "code": {
                        "type": "integer",
                        "example": 200
                    },
                    "message": {
                        "type": "string",
                        "example": "Success"
                    },
                    "data": {
                        "nullable": true
                    },
                    "request_id": {
                        "type": "string"
                    }
                },
                "required": [
                    "code",
                    "message",
                    "request_id"
                ]
            },
            "LoginRequest": {
                "type": "object",
                "required": [
                    "email",
                    "password"
                ],
                "properties": {
                    "email": {
                        "type": "string",
                        "format": "email"
                    },
                    "password": {
                        "type": "string",
                        "format": "password"
                    }
                }
            },
            "Pagination": {
                "type": "object",
                "properties": {
                    "total": {
                        "type": "integer",
                        "description": "Search endpoints only"
                    },
                    "total_pages": {
                        "type": "integer",
                        "description": "Search endpoints only"
                    },
                    "count": {
                        "type": "integer",
                        "description": "Ranking endpoints only: rows in this page"
                    },
                    "has_more": {
                        "type": "boolean",
                        "description": "Ranking endpoints only"
                    },
                    "page": {
                        "type": "integer"
                    },
                    "per_page": {
                        "type": "integer"
                    }
                }
            },
            "Conference": {
                "type": "object",
                "description": "Conference row. Free responses never include the external website; use detail_page (the canonical Conference Partner page).",
                "properties": {
                    "id": {
                        "type": "string",
                        "example": "1234"
                    },
                    "short_name": {
                        "type": "string",
                        "example": "ICML"
                    },
                    "full_name": {
                        "type": "string",
                        "example": "International Conference on Machine Learning"
                    },
                    "submission_date": {
                        "type": "string",
                        "format": "date",
                        "nullable": true
                    },
                    "notification_date": {
                        "type": "string",
                        "format": "date",
                        "nullable": true
                    },
                    "conference_date": {
                        "type": "string",
                        "format": "date",
                        "nullable": true
                    },
                    "location": {
                        "type": "string",
                        "nullable": true
                    },
                    "ccf_rank": {
                        "type": "string",
                        "description": "A / B / C, empty when unranked"
                    },
                    "core_rank": {
                        "type": "string",
                        "description": "A* / A / B / C, empty when unranked"
                    },
                    "qualis_rank": {
                        "type": "string",
                        "description": "A1..C, empty when unranked"
                    },
                    "is_extended": {
                        "type": "boolean",
                        "nullable": true
                    },
                    "detail_page": {
                        "type": "string",
                        "format": "uri",
                        "example": "https://www.myhuiban.com/conference/1234"
                    }
                }
            },
            "Journal": {
                "type": "object",
                "description": "Journal row. Free responses never include the external website; use detail_page.",
                "properties": {
                    "id": {
                        "type": "string"
                    },
                    "short_name": {
                        "type": "string",
                        "nullable": true
                    },
                    "full_name": {
                        "type": "string"
                    },
                    "impact_factor": {
                        "type": "string",
                        "nullable": true
                    },
                    "publisher": {
                        "type": "string",
                        "nullable": true
                    },
                    "issn": {
                        "type": "string",
                        "nullable": true
                    },
                    "ccf_rank": {
                        "type": "string",
                        "description": "A / B / C, empty when unranked"
                    },
                    "detail_page": {
                        "type": "string",
                        "format": "uri"
                    }
                }
            }
        },
        "responses": {
            "Unauthorized": {
                "description": "No valid credentials: send a JWT or pay per request via x402",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ApiResponse"
                        }
                    }
                }
            },
            "QuotaExhausted": {
                "description": "Daily free quota exhausted (shared across REST API and MCP); retry after the daily reset or pay per request via x402",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ApiResponse"
                        }
                    }
                }
            },
            "RateLimited": {
                "description": "Rate limit exceeded",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ApiResponse"
                        }
                    }
                }
            }
        }
    },
    "security": [
        {
            "bearerAuth": []
        },
        {
            "paidAccess": []
        }
    ],
    "paths": {
        "/api/login": {
            "post": {
                "operationId": "login",
                "summary": "Exchange email/password for a JWT bearer token",
                "tags": [
                    "Auth"
                ],
                "security": [],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/LoginRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Token issued (data.token / data.token_type / data.expires_in / data.user_id); invalid credentials return body code 401",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ApiResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/conferences": {
            "get": {
                "operationId": "searchConferences",
                "summary": "Search academic conferences by keyword",
                "description": "Filter by name, ranking, and date ranges.",
                "tags": [
                    "Conferences"
                ],
                "parameters": [
                    {
                        "name": "query",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Keyword matched against short name and full name (case-insensitive)."
                    },
                    {
                        "name": "ccf_rank",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "a",
                                "b",
                                "c"
                            ]
                        }
                    },
                    {
                        "name": "core_rank",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        },
                        "description": "ICORE rank: A* / A / B / C (use raw value)."
                    },
                    {
                        "name": "qualis_rank",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "field",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "ai",
                                "vision",
                                "nlp",
                                "data",
                                "network",
                                "security",
                                "se",
                                "systems",
                                "theory",
                                "hci",
                                "graphics",
                                "bio",
                                "robotics",
                                "web"
                            ]
                        },
                        "description": "Research field (14 computer-science areas, auto-tagged from venue full names)."
                    },
                    {
                        "name": "submission_date_start",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "submission_date_end",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "conference_date_start",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "conference_date_end",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "default": 1
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100,
                            "default": 10
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paged list: data.conferences[] (Conference) + data.pagination; validation errors return body code 400",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ApiResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "402": {
                        "$ref": "#/components/responses/QuotaExhausted"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/conferences/rankings/{ranking}": {
            "get": {
                "operationId": "listConferences",
                "summary": "Browse conference lists and rankings (no keyword needed)",
                "description": "Same data as the public list pages and the MCP list_conferences tool. Use this to enumerate the data set page by page.",
                "tags": [
                    "Conferences"
                ],
                "parameters": [
                    {
                        "name": "ranking",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "cfp",
                                "past_cfp",
                                "ccf",
                                "core",
                                "qualis",
                                "most_viewed",
                                "most_tracked",
                                "most_attended",
                                "most_competitive",
                                "upcoming",
                                "past",
                                "trending"
                            ]
                        },
                        "description": "cfp=open calls for papers; past_cfp=expired calls; ccf/core/qualis=tier lists; most_viewed/most_tracked/most_attended=popularity; most_competitive=lowest acceptance rate; upcoming/past=by conference date; trending=most viewed in the last 30 days"
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "default": 1
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100,
                            "default": 20
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "data.ranking + data.conferences[] (Conference, some rankings add trackers_count / attendees_count / acceptance_rate / views_30d) + data.pagination (count / has_more); unknown ranking returns body code 400",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ApiResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "402": {
                        "$ref": "#/components/responses/QuotaExhausted"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/conferences/{id}": {
            "get": {
                "operationId": "getConference",
                "summary": "Get full conference detail by id",
                "description": "Basics, CFP text, acceptance-rate history, edition history, structured ratings and comments, related conferences/journals — same as the MCP get_conference tool. Free responses link to detail_page only; paid (x402) requests additionally include the official website URL.",
                "tags": [
                    "Conferences"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "data = Conference plus cfp_text / rating_summary / acceptance[] / history[] / trackers_count / attendees_count / related_conferences[] / related_journals[] / comments[]; missing id returns HTTP 404",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ApiResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "402": {
                        "$ref": "#/components/responses/QuotaExhausted"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/journals": {
            "get": {
                "operationId": "searchJournals",
                "summary": "Search academic journals by keyword, CCF rank or ISSN",
                "tags": [
                    "Journals"
                ],
                "parameters": [
                    {
                        "name": "query",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Keyword matched against journal full/short name."
                    },
                    {
                        "name": "ccf_rank",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "a",
                                "b",
                                "c"
                            ]
                        }
                    },
                    {
                        "name": "issn",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "field",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "ai",
                                "vision",
                                "nlp",
                                "data",
                                "network",
                                "security",
                                "se",
                                "systems",
                                "theory",
                                "hci",
                                "graphics",
                                "bio",
                                "robotics",
                                "web"
                            ]
                        },
                        "description": "Research field (14 computer-science areas, auto-tagged from venue full names)."
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "default": 1
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100,
                            "default": 10
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paged list: data.journals[] (Journal) + data.pagination; validation errors return body code 400",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ApiResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "402": {
                        "$ref": "#/components/responses/QuotaExhausted"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/journals/rankings/{ranking}": {
            "get": {
                "operationId": "listJournals",
                "summary": "Browse journal lists and rankings (no keyword needed)",
                "description": "Same data as the public list pages and the MCP list_journals tool. Use this to enumerate the data set page by page.",
                "tags": [
                    "Journals"
                ],
                "parameters": [
                    {
                        "name": "ranking",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "cfp",
                                "ccf",
                                "highest_if",
                                "most_viewed",
                                "most_tracked",
                                "all"
                            ]
                        },
                        "description": "cfp=special-issue calls for papers; ccf=CCF list; highest_if=highest impact factor; most_viewed/most_tracked=popularity; all=all journals"
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "default": 1
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100,
                            "default": 20
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "data.ranking + data.journals[] (Journal, ranking=cfp adds special_issue) + data.pagination (count / has_more); unknown ranking returns body code 400",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ApiResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "402": {
                        "$ref": "#/components/responses/QuotaExhausted"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/journals/{id}": {
            "get": {
                "operationId": "getJournal",
                "summary": "Get full journal detail by id",
                "description": "Basics, CFP text, special issues, structured ratings and comments, related journals/conferences — same as the MCP get_journal tool. Free responses link to detail_page only; paid (x402) requests additionally include the official website URL.",
                "tags": [
                    "Journals"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "data = Journal plus cfp_text / rating_summary / special_issues[] / trackers_count / related_journals[] / related_conferences[] / comments[]; missing id returns HTTP 404",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ApiResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "402": {
                        "$ref": "#/components/responses/QuotaExhausted"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        },
        "/api/statistics": {
            "get": {
                "operationId": "getStatistics",
                "summary": "Site-level public statistics",
                "description": "Conference/journal totals, upcoming deadlines by month, conference country distribution, journal impact-factor and publisher distributions — same as the MCP get_statistics tool.",
                "tags": [
                    "Statistics"
                ],
                "responses": {
                    "200": {
                        "description": "data.conferences_total / journals_total / conference_deadline_by_month / conference_country_distribution / journal_impact_factor_distribution / journal_publisher_distribution",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ApiResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "402": {
                        "$ref": "#/components/responses/QuotaExhausted"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimited"
                    }
                }
            }
        }
    },
    "externalDocs": {
        "description": "LLM-oriented site description",
        "url": "https://www.myhuiban.com/llms.txt"
    }
}