{
  "openapi": "3.0.0",
  "info": {
    "title": "Apidree System API",
    "version": "1.0.0",
    "description": "High-performance article delivery API",
    "contact": {
      "name": "Apidree Support",
      "url": "https://apidree.com"
    }
  },
  "servers": [
    {
      "url": "https://api.apidree.com",
      "description": "Production server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Server-to-server API key authentication"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "JWT token for mobile/web apps"
      }
    },
    "schemas": {
      "Article": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "article-001"
          },
          "slug": {
            "type": "string",
            "example": "getting-started-javascript"
          },
          "title": {
            "type": "string",
            "example": "Getting Started with JavaScript"
          },
          "author": {
            "type": "string",
            "example": "John Doe"
          },
          "authorAvatar": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "description": "Avatar image URL"
              },
              "alt": {
                "type": "string",
                "description": "Alt text for author avatar"
              },
              "caption": {
                "type": "string",
                "description": "Author name or description"
              },
              "width": {
                "type": "number",
                "description": "Avatar width in pixels"
              },
              "height": {
                "type": "number",
                "description": "Avatar height in pixels"
              }
            },
            "required": [
              "url",
              "alt",
              "caption",
              "width",
              "height"
            ],
            "example": {
              "url": "https://assets.apidree.com/avatars/john-doe.jpg",
              "alt": "John Doe profile picture",
              "caption": "John Doe",
              "width": 200,
              "height": 200
            }
          },
          "content": {
            "type": "string",
            "example": "Article content here..."
          },
          "coverImage": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "description": "Cover image URL"
              },
              "alt": {
                "type": "string",
                "description": "Alt text for cover image"
              },
              "caption": {
                "type": "string",
                "description": "Cover image caption"
              },
              "width": {
                "type": "number",
                "description": "Cover width in pixels"
              },
              "height": {
                "type": "number",
                "description": "Cover height in pixels"
              }
            },
            "required": [
              "url",
              "alt",
              "caption",
              "width",
              "height"
            ],
            "example": {
              "url": "https://assets.apidree.com/articles/article-001/cover.jpg",
              "alt": "Getting Started with JavaScript tutorial cover",
              "caption": "JavaScript fundamentals guide",
              "width": 1920,
              "height": 1080
            }
          },
          "thumbnail": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "description": "Thumbnail image URL"
              },
              "alt": {
                "type": "string",
                "description": "Alt text for thumbnail"
              },
              "caption": {
                "type": "string",
                "description": "Thumbnail caption"
              },
              "width": {
                "type": "number",
                "description": "Thumbnail width in pixels"
              },
              "height": {
                "type": "number",
                "description": "Thumbnail height in pixels"
              }
            },
            "required": [
              "url",
              "alt",
              "caption",
              "width",
              "height"
            ],
            "example": {
              "url": "https://assets.apidree.com/articles/article-001/thumb.jpg",
              "alt": "JavaScript tutorial thumbnail",
              "caption": "Quick preview",
              "width": 300,
              "height": 200
            }
          },
          "images": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "url": {
                  "type": "string",
                  "description": "Image URL"
                },
                "alt": {
                  "type": "string",
                  "description": "Alt text for accessibility (required)"
                },
                "caption": {
                  "type": "string",
                  "description": "Image caption (required)"
                },
                "width": {
                  "type": "number",
                  "description": "Image width in pixels (required)"
                },
                "height": {
                  "type": "number",
                  "description": "Image height in pixels (required)"
                }
              },
              "required": [
                "url",
                "alt",
                "caption",
                "width",
                "height"
              ]
            },
            "example": [
              {
                "url": "https://assets.apidree.com/articles/article-001/image-1.jpg",
                "alt": "JavaScript code example",
                "caption": "Basic JavaScript syntax",
                "width": 1200,
                "height": 800
              }
            ]
          },
          "video": {
            "type": "string",
            "example": "https://assets.apidree.com/videos/tutorial-001.mp4"
          },
          "excerpt": {
            "type": "string",
            "example": "Learn JavaScript basics in this comprehensive tutorial"
          },
          "metaDescription": {
            "type": "string",
            "example": "Complete guide to JavaScript for beginners"
          },
          "keywords": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "javascript",
              "programming",
              "web development"
            ]
          },
          "publishedDate": {
            "type": "string",
            "format": "date-time",
            "example": "2025-01-15T10:00:00Z"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "example": "2025-01-20T15:30:00Z"
          },
          "category": {
            "type": "string",
            "example": "Programming"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "javascript",
              "tutorial",
              "beginner"
            ]
          },
          "language": {
            "type": "string",
            "example": "en"
          },
          "readingTime": {
            "type": "number",
            "example": 8,
            "description": "Estimated reading time in minutes"
          },
          "wordCount": {
            "type": "number",
            "example": 1500
          }
        },
        "required": [
          "id",
          "slug",
          "title",
          "author",
          "content",
          "publishedDate"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "Error message"
          },
          "requestId": {
            "type": "string",
            "example": "123e4567-e89b-12d3-a456-426614174000"
          }
        }
      }
    }
  },
  "paths": {
    "/health": {
      "get": {
        "summary": "Health Check",
        "description": "Check API health and service status",
        "security": [],
        "responses": {
          "200": {
            "description": "Service is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "healthy"
                    },
                    "timestamp": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "version": {
                      "type": "string",
                      "example": "1.0.0"
                    },
                    "requestId": {
                      "type": "string"
                    },
                    "checks": {
                      "type": "object",
                      "properties": {
                        "worker": {
                          "type": "string",
                          "example": "healthy"
                        },
                        "kv": {
                          "type": "string",
                          "example": "healthy"
                        },
                        "r2": {
                          "type": "string",
                          "example": "healthy"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/articles/{articleId}": {
      "get": {
        "summary": "Get Article by ID",
        "description": "Fetch article content with intelligent caching. Quota will be deducted.",
        "parameters": [
          {
            "name": "articleId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_-]{1,100}$"
            },
            "description": "Article ID (alphanumeric, hyphens, underscores only)",
            "example": "article-001"
          }
        ],
        "responses": {
          "200": {
            "description": "Article found",
            "headers": {
              "X-Cache-Status": {
                "description": "HIT or MISS",
                "schema": {
                  "type": "string"
                }
              },
              "X-User-Quota": {
                "description": "Remaining quota",
                "schema": {
                  "type": "integer"
                }
              },
              "X-Request-ID": {
                "description": "Request correlation ID",
                "schema": {
                  "type": "string"
                }
              },
              "X-Latency-Ms": {
                "description": "Request latency in ms",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Article"
                }
              }
            }
          },
          "400": {
            "description": "Invalid article ID format",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Article not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Quota exceeded",
            "headers": {
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer",
                  "example": 0
                }
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "example": 3600
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": false
                    },
                    "error": {
                      "type": "string",
                      "example": "Quota exceeded"
                    },
                    "remainingQuota": {
                      "type": "integer",
                      "example": 0
                    },
                    "upgradeUrl": {
                      "type": "string",
                      "example": "https://apidree.com/upgrade"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Articles",
      "description": "Article delivery endpoints"
    },
    {
      "name": "System",
      "description": "Health and monitoring endpoints"
    }
  ]
}