Academic Data API Docs
{
"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"
}
}
}
}
}
}
}
}
}
}
}
}
}
}