{
  "openapi": "3.1.0",
  "info": {
    "title": "Invisible Cities API",
    "version": "1.0.0",
    "description": "Fifty-five cities from Italo Calvino’s Le città invisibili, each with a deterministic procedural 3D scene graph.\n\nScene briefs are original interpretive notes written for this API, not quotations from the novel.",
    "license": {
      "name": "MIT"
    }
  },
  "servers": [
    {
      "url": "https://55citys.331319.xyz"
    }
  ],
  "tags": [
    {
      "name": "catalogue",
      "description": "Cities and groups"
    },
    {
      "name": "scenes",
      "description": "Procedural 3D scene graphs"
    },
    {
      "name": "meta",
      "description": "Docs, health, OpenAPI"
    }
  ],
  "paths": {
    "/api": {
      "get": {
        "tags": [
          "meta"
        ],
        "summary": "Service index",
        "operationId": "getIndex",
        "responses": {
          "200": {
            "description": "Endpoint index"
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "tags": [
          "meta"
        ],
        "summary": "Health probe",
        "operationId": "getHealth",
        "responses": {
          "200": {
            "description": "Status"
          }
        }
      }
    },
    "/api/groups": {
      "get": {
        "tags": [
          "catalogue"
        ],
        "summary": "Themed groups",
        "operationId": "listGroups",
        "responses": {
          "200": {
            "description": "Eleven groups"
          }
        }
      }
    },
    "/api/cities": {
      "get": {
        "tags": [
          "catalogue"
        ],
        "summary": "List cities",
        "operationId": "listCities",
        "parameters": [
          {
            "name": "group",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "memory",
                "desire",
                "signs",
                "thin",
                "trading",
                "eyes",
                "names",
                "dead",
                "sky",
                "continuous",
                "hidden"
              ]
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "style",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "grid",
                "domes",
                "spiral",
                "radial",
                "signs",
                "canals",
                "wells",
                "stilts",
                "amphitheatre",
                "net",
                "arcades",
                "lattice",
                "rings",
                "mirror",
                "gardens",
                "necro",
                "floating",
                "labyrinth",
                "ruins"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 55,
              "default": 55
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 54,
              "default": 0
            }
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "appearance",
                "name",
                "group",
                "chapter"
              ],
              "default": "appearance"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of cities",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": {
                      "type": "integer"
                    },
                    "total": {
                      "type": "integer"
                    },
                    "cities": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/City"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unknown filter value"
          }
        }
      }
    },
    "/api/cities/{slug}": {
      "get": {
        "tags": [
          "catalogue"
        ],
        "summary": "One city",
        "operationId": "getCity",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "City record",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/City"
                }
              }
            }
          },
          "404": {
            "description": "Unknown city"
          }
        }
      }
    },
    "/api/cities/{slug}/scene": {
      "get": {
        "tags": [
          "scenes"
        ],
        "summary": "3D scene graph",
        "operationId": "getScene",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "detail",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "low",
                "medium",
                "high"
              ],
              "default": "medium"
            }
          },
          {
            "name": "seed",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Scene graph",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Scene"
                }
              }
            }
          },
          "404": {
            "description": "Unknown city"
          }
        }
      }
    },
    "/api/random": {
      "get": {
        "tags": [
          "scenes"
        ],
        "summary": "Random city with scene",
        "operationId": "getRandom",
        "parameters": [
          {
            "name": "group",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "memory",
                "desire",
                "signs",
                "thin",
                "trading",
                "eyes",
                "names",
                "dead",
                "sky",
                "continuous",
                "hidden"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "City and scene"
          }
        }
      }
    },
    "/api/docs": {
      "get": {
        "tags": [
          "meta"
        ],
        "summary": "Machine-readable docs",
        "operationId": "getDocs",
        "responses": {
          "200": {
            "description": "Docs model"
          }
        }
      }
    },
    "/api/openapi.json": {
      "get": {
        "tags": [
          "meta"
        ],
        "summary": "This document",
        "operationId": "getOpenApi",
        "responses": {
          "200": {
            "description": "OpenAPI 3.1"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "City": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "italian": {
            "type": "string"
          },
          "group": {
            "type": "string"
          },
          "groupName": {
            "type": "string"
          },
          "ordinal": {
            "type": "integer",
            "minimum": 1,
            "maximum": 5
          },
          "chapter": {
            "type": "integer",
            "minimum": 1,
            "maximum": 9
          },
          "appearance": {
            "type": "integer",
            "minimum": 1,
            "maximum": 55
          },
          "style": {
            "type": "string"
          },
          "water": {
            "type": "boolean"
          },
          "brief": {
            "type": "string"
          },
          "sceneUrl": {
            "type": "string"
          }
        }
      },
      "Instance": {
        "type": "object",
        "description": "One primitive. The client applies translation, Y rotation and scale.",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "box",
              "cyl",
              "dome",
              "cone",
              "disc"
            ]
          },
          "position": {
            "type": "array",
            "items": {
              "type": "number"
            },
            "minItems": 3,
            "maxItems": 3
          },
          "scale": {
            "type": "array",
            "items": {
              "type": "number"
            },
            "minItems": 3,
            "maxItems": 3
          },
          "rotation": {
            "type": "number",
            "description": "Radians around Y."
          },
          "color": {
            "type": "integer",
            "minimum": 0,
            "maximum": 4,
            "description": "Index into palette.buildings."
          },
          "glow": {
            "type": "integer",
            "enum": [
              0,
              1
            ],
            "description": "Emissive accent (lamps, signs, water lights)."
          }
        }
      },
      "Scene": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string"
          },
          "seed": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          },
          "palette": {
            "type": "object"
          },
          "ground": {
            "type": "object"
          },
          "water": {
            "type": [
              "object",
              "null"
            ]
          },
          "sun": {
            "type": "object"
          },
          "camera": {
            "type": "object"
          },
          "stats": {
            "type": "object"
          },
          "instances": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Instance"
            }
          }
        }
      }
    }
  }
}