{
  "openapi": "3.1.0",
  "info": {
    "title": "Rakugaki API",
    "version": "1.0.0",
    "description": "Read-only API for hand-drawn doodle characters and their expression images. No authentication. CORS: *. Images: commercial use, modification and redistribution allowed; no credit required."
  },
  "servers": [
    {
      "url": "https://rakugaki.mori22.com"
    }
  ],
  "paths": {
    "/api/characters": {
      "get": {
        "operationId": "listCharacters",
        "summary": "List all characters and expressions",
        "responses": {
          "200": {
            "description": "All characters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "expressions": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "enum": [
                              "normal",
                              "happy",
                              "angry",
                              "sad",
                              "surprised",
                              "confused"
                            ]
                          },
                          "label": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "groups": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "enum": [
                              "shape",
                              "job",
                              "sports",
                              "fantasy",
                              "japanese",
                              "family"
                            ]
                          },
                          "label": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "characters": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "no",
                          "group",
                          "name",
                          "setting",
                          "kana",
                          "images"
                        ],
                        "properties": {
                          "id": {
                            "type": "string",
                            "enum": [
                              "maru",
                              "kaku",
                              "sankaku",
                              "heart",
                              "rokkaku",
                              "gokaku",
                              "shizuku",
                              "kamaboko",
                              "hishigata",
                              "tamago",
                              "kumo",
                              "hana",
                              "chef",
                              "detective",
                              "astronaut",
                              "doctor",
                              "nurse",
                              "police",
                              "firefighter",
                              "postman",
                              "carpenter",
                              "farmer",
                              "fisher",
                              "baker",
                              "painter",
                              "scientist",
                              "teacher",
                              "pilot",
                              "captain",
                              "conductor",
                              "librarian",
                              "reporter",
                              "maid",
                              "magician",
                              "gardener",
                              "barista",
                              "photographer",
                              "mechanic",
                              "guard",
                              "lifeguard",
                              "hairdresser",
                              "florist",
                              "sailor",
                              "judge",
                              "dj",
                              "shopclerk",
                              "engineer",
                              "banker",
                              "cashier",
                              "officeworker",
                              "director",
                              "electrician",
                              "designer",
                              "cityhall",
                              "taxidriver",
                              "mover",
                              "baseball",
                              "soccer",
                              "judoka",
                              "sumo",
                              "boxer",
                              "runner",
                              "cyclist",
                              "skier",
                              "referee",
                              "jockey",
                              "trainer",
                              "king",
                              "wizard",
                              "pirate",
                              "ninja",
                              "ojiichan",
                              "obaachan"
                            ]
                          },
                          "no": {
                            "type": "integer",
                            "minimum": 1,
                            "description": "Character number (shown as No.001)"
                          },
                          "group": {
                            "type": "string",
                            "enum": [
                              "shape",
                              "job",
                              "sports",
                              "fantasy",
                              "japanese",
                              "family"
                            ],
                            "description": "Section id (shape, job, ...)"
                          },
                          "name": {
                            "type": "string",
                            "description": "Display name (Japanese)"
                          },
                          "setting": {
                            "type": "string",
                            "description": "One-line setting (Japanese)"
                          },
                          "kana": {
                            "type": "string",
                            "description": "Hiragana reading and related words, for search"
                          },
                          "images": {
                            "type": "object",
                            "description": "Expression id -> absolute URL of the transparent PNG (720x880)",
                            "properties": {
                              "normal": {
                                "type": "string",
                                "format": "uri"
                              },
                              "happy": {
                                "type": "string",
                                "format": "uri"
                              },
                              "angry": {
                                "type": "string",
                                "format": "uri"
                              },
                              "sad": {
                                "type": "string",
                                "format": "uri"
                              },
                              "surprised": {
                                "type": "string",
                                "format": "uri"
                              },
                              "confused": {
                                "type": "string",
                                "format": "uri"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/random": {
      "get": {
        "operationId": "getRandomCharacter",
        "summary": "Get one random character",
        "responses": {
          "200": {
            "description": "A random character",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "id",
                    "no",
                    "group",
                    "name",
                    "setting",
                    "kana",
                    "images"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "enum": [
                        "maru",
                        "kaku",
                        "sankaku",
                        "heart",
                        "rokkaku",
                        "gokaku",
                        "shizuku",
                        "kamaboko",
                        "hishigata",
                        "tamago",
                        "kumo",
                        "hana",
                        "chef",
                        "detective",
                        "astronaut",
                        "doctor",
                        "nurse",
                        "police",
                        "firefighter",
                        "postman",
                        "carpenter",
                        "farmer",
                        "fisher",
                        "baker",
                        "painter",
                        "scientist",
                        "teacher",
                        "pilot",
                        "captain",
                        "conductor",
                        "librarian",
                        "reporter",
                        "maid",
                        "magician",
                        "gardener",
                        "barista",
                        "photographer",
                        "mechanic",
                        "guard",
                        "lifeguard",
                        "hairdresser",
                        "florist",
                        "sailor",
                        "judge",
                        "dj",
                        "shopclerk",
                        "engineer",
                        "banker",
                        "cashier",
                        "officeworker",
                        "director",
                        "electrician",
                        "designer",
                        "cityhall",
                        "taxidriver",
                        "mover",
                        "baseball",
                        "soccer",
                        "judoka",
                        "sumo",
                        "boxer",
                        "runner",
                        "cyclist",
                        "skier",
                        "referee",
                        "jockey",
                        "trainer",
                        "king",
                        "wizard",
                        "pirate",
                        "ninja",
                        "ojiichan",
                        "obaachan"
                      ]
                    },
                    "no": {
                      "type": "integer",
                      "minimum": 1,
                      "description": "Character number (shown as No.001)"
                    },
                    "group": {
                      "type": "string",
                      "enum": [
                        "shape",
                        "job",
                        "sports",
                        "fantasy",
                        "japanese",
                        "family"
                      ],
                      "description": "Section id (shape, job, ...)"
                    },
                    "name": {
                      "type": "string",
                      "description": "Display name (Japanese)"
                    },
                    "setting": {
                      "type": "string",
                      "description": "One-line setting (Japanese)"
                    },
                    "kana": {
                      "type": "string",
                      "description": "Hiragana reading and related words, for search"
                    },
                    "images": {
                      "type": "object",
                      "description": "Expression id -> absolute URL of the transparent PNG (720x880)",
                      "properties": {
                        "normal": {
                          "type": "string",
                          "format": "uri"
                        },
                        "happy": {
                          "type": "string",
                          "format": "uri"
                        },
                        "angry": {
                          "type": "string",
                          "format": "uri"
                        },
                        "sad": {
                          "type": "string",
                          "format": "uri"
                        },
                        "surprised": {
                          "type": "string",
                          "format": "uri"
                        },
                        "confused": {
                          "type": "string",
                          "format": "uri"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/random/image": {
      "get": {
        "operationId": "getRandomImage",
        "summary": "Get the PNG of a random character (random expression unless specified)",
        "parameters": [
          {
            "name": "expression",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "normal",
                "happy",
                "angry",
                "sad",
                "surprised",
                "confused"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Transparent PNG, 720x880. The chosen character and expression are in X-Rakugaki-Character / X-Rakugaki-Expression.",
            "headers": {
              "X-Rakugaki-Character": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "maru",
                    "kaku",
                    "sankaku",
                    "heart",
                    "rokkaku",
                    "gokaku",
                    "shizuku",
                    "kamaboko",
                    "hishigata",
                    "tamago",
                    "kumo",
                    "hana",
                    "chef",
                    "detective",
                    "astronaut",
                    "doctor",
                    "nurse",
                    "police",
                    "firefighter",
                    "postman",
                    "carpenter",
                    "farmer",
                    "fisher",
                    "baker",
                    "painter",
                    "scientist",
                    "teacher",
                    "pilot",
                    "captain",
                    "conductor",
                    "librarian",
                    "reporter",
                    "maid",
                    "magician",
                    "gardener",
                    "barista",
                    "photographer",
                    "mechanic",
                    "guard",
                    "lifeguard",
                    "hairdresser",
                    "florist",
                    "sailor",
                    "judge",
                    "dj",
                    "shopclerk",
                    "engineer",
                    "banker",
                    "cashier",
                    "officeworker",
                    "director",
                    "electrician",
                    "designer",
                    "cityhall",
                    "taxidriver",
                    "mover",
                    "baseball",
                    "soccer",
                    "judoka",
                    "sumo",
                    "boxer",
                    "runner",
                    "cyclist",
                    "skier",
                    "referee",
                    "jockey",
                    "trainer",
                    "king",
                    "wizard",
                    "pirate",
                    "ninja",
                    "ojiichan",
                    "obaachan"
                  ]
                }
              },
              "X-Rakugaki-Expression": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "normal",
                    "happy",
                    "angry",
                    "sad",
                    "surprised",
                    "confused"
                  ]
                }
              }
            },
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/characters/{id}": {
      "get": {
        "operationId": "getCharacter",
        "summary": "Get one character",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "maru",
                "kaku",
                "sankaku",
                "heart",
                "rokkaku",
                "gokaku",
                "shizuku",
                "kamaboko",
                "hishigata",
                "tamago",
                "kumo",
                "hana",
                "chef",
                "detective",
                "astronaut",
                "doctor",
                "nurse",
                "police",
                "firefighter",
                "postman",
                "carpenter",
                "farmer",
                "fisher",
                "baker",
                "painter",
                "scientist",
                "teacher",
                "pilot",
                "captain",
                "conductor",
                "librarian",
                "reporter",
                "maid",
                "magician",
                "gardener",
                "barista",
                "photographer",
                "mechanic",
                "guard",
                "lifeguard",
                "hairdresser",
                "florist",
                "sailor",
                "judge",
                "dj",
                "shopclerk",
                "engineer",
                "banker",
                "cashier",
                "officeworker",
                "director",
                "electrician",
                "designer",
                "cityhall",
                "taxidriver",
                "mover",
                "baseball",
                "soccer",
                "judoka",
                "sumo",
                "boxer",
                "runner",
                "cyclist",
                "skier",
                "referee",
                "jockey",
                "trainer",
                "king",
                "wizard",
                "pirate",
                "ninja",
                "ojiichan",
                "obaachan"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The character",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "id",
                    "no",
                    "group",
                    "name",
                    "setting",
                    "kana",
                    "images"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "enum": [
                        "maru",
                        "kaku",
                        "sankaku",
                        "heart",
                        "rokkaku",
                        "gokaku",
                        "shizuku",
                        "kamaboko",
                        "hishigata",
                        "tamago",
                        "kumo",
                        "hana",
                        "chef",
                        "detective",
                        "astronaut",
                        "doctor",
                        "nurse",
                        "police",
                        "firefighter",
                        "postman",
                        "carpenter",
                        "farmer",
                        "fisher",
                        "baker",
                        "painter",
                        "scientist",
                        "teacher",
                        "pilot",
                        "captain",
                        "conductor",
                        "librarian",
                        "reporter",
                        "maid",
                        "magician",
                        "gardener",
                        "barista",
                        "photographer",
                        "mechanic",
                        "guard",
                        "lifeguard",
                        "hairdresser",
                        "florist",
                        "sailor",
                        "judge",
                        "dj",
                        "shopclerk",
                        "engineer",
                        "banker",
                        "cashier",
                        "officeworker",
                        "director",
                        "electrician",
                        "designer",
                        "cityhall",
                        "taxidriver",
                        "mover",
                        "baseball",
                        "soccer",
                        "judoka",
                        "sumo",
                        "boxer",
                        "runner",
                        "cyclist",
                        "skier",
                        "referee",
                        "jockey",
                        "trainer",
                        "king",
                        "wizard",
                        "pirate",
                        "ninja",
                        "ojiichan",
                        "obaachan"
                      ]
                    },
                    "no": {
                      "type": "integer",
                      "minimum": 1,
                      "description": "Character number (shown as No.001)"
                    },
                    "group": {
                      "type": "string",
                      "enum": [
                        "shape",
                        "job",
                        "sports",
                        "fantasy",
                        "japanese",
                        "family"
                      ],
                      "description": "Section id (shape, job, ...)"
                    },
                    "name": {
                      "type": "string",
                      "description": "Display name (Japanese)"
                    },
                    "setting": {
                      "type": "string",
                      "description": "One-line setting (Japanese)"
                    },
                    "kana": {
                      "type": "string",
                      "description": "Hiragana reading and related words, for search"
                    },
                    "images": {
                      "type": "object",
                      "description": "Expression id -> absolute URL of the transparent PNG (720x880)",
                      "properties": {
                        "normal": {
                          "type": "string",
                          "format": "uri"
                        },
                        "happy": {
                          "type": "string",
                          "format": "uri"
                        },
                        "angry": {
                          "type": "string",
                          "format": "uri"
                        },
                        "sad": {
                          "type": "string",
                          "format": "uri"
                        },
                        "surprised": {
                          "type": "string",
                          "format": "uri"
                        },
                        "confused": {
                          "type": "string",
                          "format": "uri"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/characters/{id}/{expression}": {
      "get": {
        "operationId": "getCharacterImage",
        "summary": "Get the PNG image of a character with an expression",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "maru",
                "kaku",
                "sankaku",
                "heart",
                "rokkaku",
                "gokaku",
                "shizuku",
                "kamaboko",
                "hishigata",
                "tamago",
                "kumo",
                "hana",
                "chef",
                "detective",
                "astronaut",
                "doctor",
                "nurse",
                "police",
                "firefighter",
                "postman",
                "carpenter",
                "farmer",
                "fisher",
                "baker",
                "painter",
                "scientist",
                "teacher",
                "pilot",
                "captain",
                "conductor",
                "librarian",
                "reporter",
                "maid",
                "magician",
                "gardener",
                "barista",
                "photographer",
                "mechanic",
                "guard",
                "lifeguard",
                "hairdresser",
                "florist",
                "sailor",
                "judge",
                "dj",
                "shopclerk",
                "engineer",
                "banker",
                "cashier",
                "officeworker",
                "director",
                "electrician",
                "designer",
                "cityhall",
                "taxidriver",
                "mover",
                "baseball",
                "soccer",
                "judoka",
                "sumo",
                "boxer",
                "runner",
                "cyclist",
                "skier",
                "referee",
                "jockey",
                "trainer",
                "king",
                "wizard",
                "pirate",
                "ninja",
                "ojiichan",
                "obaachan"
              ]
            }
          },
          {
            "name": "expression",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "normal",
                "happy",
                "angry",
                "sad",
                "surprised",
                "confused"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Transparent PNG, 720x880",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}