{
  "openapi": "3.1.0",
  "info": {
    "title": "ColorOS 16 World Clock API",
    "version": "1.0.0",
    "description": "IANA-accurate world time for 46 cities, served by a single Cloudflare Worker. No authentication required.",
    "license": {
      "name": "MIT"
    }
  },
  "servers": [
    {
      "url": "https://time.cogpu.com",
      "description": "This Worker"
    }
  ],
  "tags": [
    {
      "name": "time"
    },
    {
      "name": "meta"
    }
  ],
  "paths": {
    "/api/time": {
      "get": {
        "tags": [
          "time"
        ],
        "summary": "Time for every city",
        "operationId": "getTime",
        "parameters": [
          {
            "name": "tz",
            "in": "query",
            "required": false,
            "description": "Reference timezone used to compute dayDelta (\"+1 day\" / \"Same day\"). Any valid IANA name. Default UTC.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "city",
            "in": "query",
            "required": false,
            "description": "Filter by city name. Repeat the parameter or comma-separate: ?city=Tokyo&city=Paris / ?city=Tokyo,Paris.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Free-text search across city, country and timezone (e.g. ?q=asia/).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "offset (UTC offset, default) · name (A–Z) · hour (local wall clock).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Cap the number of returned cities.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TimeResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/now": {
      "get": {
        "tags": [
          "time"
        ],
        "summary": "Now in one timezone",
        "operationId": "getNow",
        "parameters": [
          {
            "name": "tz",
            "in": "query",
            "required": false,
            "description": "Any IANA timezone name, e.g. Asia/Kathmandu, America/New_York. Default UTC.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "description": "json (default) or text — text returns a one-line 2026-09-09 16:55:35 UTC+5:45.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NowResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/cities": {
      "get": {
        "tags": [
          "meta"
        ],
        "summary": "City index",
        "operationId": "getCities",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Search across city, country and timezone.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Cap the number of results.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "offsets",
            "in": "query",
            "required": false,
            "description": "Set to 1 to include the live UTC offset of each city.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CitiesResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/convert": {
      "get": {
        "tags": [
          "time"
        ],
        "summary": "Convert an instant across timezones",
        "operationId": "convert",
        "parameters": [
          {
            "name": "time",
            "in": "query",
            "required": false,
            "description": "ISO 8601 or Unix epoch (s / ms). Default: now.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Timezone of the time value when it has no offset. Default UTC.",
            "schema": {
              "type": "string",
              "default": "UTC"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": true,
            "description": "Target timezone(s), comma-separated.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConvertResponse"
                }
              }
            }
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "tags": [
          "meta"
        ],
        "summary": "This document",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/docs": {
      "get": {
        "tags": [
          "meta"
        ],
        "summary": "Documentation as Markdown",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CityTime": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "tz": {
            "type": "string"
          },
          "hour": {
            "type": "integer"
          },
          "minute": {
            "type": "integer"
          },
          "second": {
            "type": "integer"
          },
          "weekday": {
            "type": "string"
          },
          "date": {
            "type": "string"
          },
          "offsetMinutes": {
            "type": "integer"
          },
          "offset": {
            "type": "string"
          },
          "dayDelta": {
            "type": "integer"
          },
          "dayProgress": {
            "type": "number"
          },
          "phase": {
            "type": "string"
          },
          "phaseIcon": {
            "type": "string"
          }
        }
      },
      "TimeResponse": {
        "type": "object",
        "properties": {
          "now": {
            "type": "string",
            "format": "date-time"
          },
          "baseTimeZone": {
            "type": "string"
          },
          "count": {
            "type": "integer"
          },
          "cities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CityTime"
            }
          }
        }
      },
      "NowResponse": {
        "type": "object",
        "properties": {
          "timezone": {
            "type": "string"
          },
          "epoch": {
            "type": "integer"
          },
          "epochMs": {
            "type": "integer"
          },
          "iso": {
            "type": "string"
          },
          "date": {
            "type": "string"
          },
          "time": {
            "type": "string"
          },
          "hour": {
            "type": "integer"
          },
          "minute": {
            "type": "integer"
          },
          "second": {
            "type": "integer"
          },
          "offset": {
            "type": "string"
          },
          "offsetMinutes": {
            "type": "integer"
          },
          "phase": {
            "type": "string"
          },
          "phaseIcon": {
            "type": "string"
          }
        }
      },
      "CitiesResponse": {
        "type": "object",
        "properties": {
          "count": {
            "type": "integer"
          },
          "cities": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "city": {
                  "type": "string"
                },
                "country": {
                  "type": "string"
                },
                "tz": {
                  "type": "string"
                },
                "offset": {
                  "type": "string"
                },
                "offsetMinutes": {
                  "type": "integer"
                }
              }
            }
          }
        }
      },
      "ConvertResponse": {
        "type": "object",
        "properties": {
          "input": {
            "type": "object"
          },
          "count": {
            "type": "integer"
          },
          "results": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      }
    }
  }
}