{
  "openapi": "3.0.3",
  "info": {
    "title": "Newspectives Public API",
    "description": "Multi-perspective news analysis API. Compare how different regions report the same news event through AI-driven analysis of global news sources.",
    "version": "1.0.0",
    "contact": {
      "email": "info@newspectives.com"
    }
  },
  "servers": [
    {
      "url": "https://newspectives.com",
      "description": "Production server"
    }
  ],
  "paths": {
    "/api/topics/recent": {
      "get": {
        "summary": "Get recent analyzed topics",
        "description": "Retrieve recently analyzed news topics with multi-perspective analysis from different geographic regions.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Number of recent topics to return",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 10,
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "id",
            "in": "query",
            "description": "Fetch a specific topic by ID",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Array of topic objects with multi-perspective analysis",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "Unique topic identifier"
                      },
                      "query": {
                        "type": "string",
                        "description": "The news topic or headline"
                      },
                      "timestamp": {
                        "type": "number",
                        "description": "Unix timestamp in milliseconds when topic was analyzed"
                      },
                      "imageUrl": {
                        "type": "string",
                        "description": "URL to topic preview image"
                      },
                      "tags": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Topic tags for categorization"
                      },
                      "perspectives": {
                        "type": "object",
                        "description": "Analysis by geographic region (US, CN, RU, ARAB, IL, GLOBAL_SOUTH, EU)",
                        "additionalProperties": {
                          "type": "object",
                          "properties": {
                            "status": {
                              "type": "string",
                              "enum": ["completed", "pending", "error"],
                              "description": "Status of analysis for this region"
                            },
                            "data": {
                              "type": "object",
                              "properties": {
                                "headline": {
                                  "type": "string",
                                  "description": "Region-specific headline"
                                },
                                "tone": {
                                  "type": "string",
                                  "description": "Tone analysis (e.g., positive, negative, neutral)"
                                },
                                "summary": {
                                  "type": "string",
                                  "description": "Perspective-specific summary"
                                },
                                "keyPoints": {
                                  "type": "array",
                                  "items": {
                                    "type": "string"
                                  },
                                  "description": "Key points from this perspective"
                                },
                                "sources": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "title": {
                                        "type": "string",
                                        "description": "Source article title"
                                      },
                                      "url": {
                                        "type": "string",
                                        "description": "URL to source article"
                                      }
                                    }
                                  },
                                  "description": "Source articles for this perspective"
                                }
                              }
                            }
                          }
                        }
                      }
                    },
                    "required": ["id", "query", "timestamp", "perspectives"]
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters"
          },
          "404": {
            "description": "Topic not found"
          }
        }
      }
    },
    "/api/topics/radio": {
      "get": {
        "summary": "List all radio broadcasts",
        "description": "Returns all public topics that have an AI-generated radio broadcast, newest first. Supports pagination.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Number of items to return",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20,
              "minimum": 1,
              "maximum": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Number of items to skip for pagination",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of radio broadcasts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total": {
                      "type": "integer",
                      "description": "Total number of radio broadcasts available"
                    },
                    "offset": {
                      "type": "integer",
                      "description": "Current offset"
                    },
                    "limit": {
                      "type": "integer",
                      "description": "Items per page"
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Topic identifier"
                          },
                          "title": {
                            "type": "string",
                            "description": "The news topic"
                          },
                          "url": {
                            "type": "string",
                            "description": "Link to the topic on Newspectives"
                          },
                          "radioUrl": {
                            "type": "string",
                            "description": "Direct URL to the radio audio file (WAV)"
                          },
                          "imageUrl": {
                            "type": "string",
                            "nullable": true,
                            "description": "Topic illustration image"
                          },
                          "timestamp": {
                            "type": "number",
                            "description": "Unix timestamp in milliseconds"
                          },
                          "tags": {
                            "type": "array",
                            "items": { "type": "string" }
                          }
                        },
                        "required": ["id", "title", "url", "radioUrl", "timestamp"]
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "summary": "Health check",
        "description": "Check if the API is operational",
        "responses": {
          "200": {
            "description": "API is operational",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": ["ok"],
                      "description": "Service status"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}