{
  "openapi": "3.0.0",
  "info": {
    "title": "Talon",
    "description": "API for the Talon static site management system",
    "version": "0.1.0",
    "license": {
      "name": "MIT License"
    }
  },
  "servers": [],
  "tags": [],
  "paths": {
    "/website/{subdomain}": {
      "get": {
        "summary": "Get a website",
        "parameters": [
          {
            "name": "subdomain",
            "schema": {
              "type": "string"
            },
            "in": "path",
            "required": true,
            "deprecated": false,
            "explode": true
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json; charset=utf-8": {
                "schema": {
                  "$ref": "#/components/schemas/Website"
                }
              }
            }
          }
        }
      },
      "put": {
        "summary": "Create a new website",
        "parameters": [
          {
            "name": "subdomain",
            "schema": {
              "type": "string"
            },
            "in": "path",
            "required": true,
            "deprecated": false,
            "explode": true
          }
        ],
        "requestBody": {
          "content": {
            "application/json; charset=utf-8": {
              "schema": {
                "$ref": "#/components/schemas/WebsiteNew"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": ""
          }
        },
        "security": [
          {
            "ApiKeyAuthorization": []
          }
        ]
      },
      "patch": {
        "summary": "Update website",
        "parameters": [
          {
            "name": "subdomain",
            "schema": {
              "type": "string"
            },
            "in": "path",
            "required": true,
            "deprecated": false,
            "explode": true
          }
        ],
        "requestBody": {
          "content": {
            "application/json; charset=utf-8": {
              "schema": {
                "$ref": "#/components/schemas/WebsiteUpdate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": ""
          }
        },
        "security": [
          {
            "ApiKeyAuthorization": []
          }
        ]
      },
      "delete": {
        "summary": "Delete website",
        "parameters": [
          {
            "name": "subdomain",
            "schema": {
              "type": "string"
            },
            "in": "path",
            "required": true,
            "deprecated": false,
            "explode": true
          }
        ],
        "responses": {
          "200": {
            "description": ""
          }
        },
        "security": [
          {
            "ApiKeyAuthorization": []
          }
        ]
      }
    },
    "/website/{subdomain}/icon": {
      "put": {
        "summary": "Upload a website icon",
        "description": "Supported image formats: png, jpeg, gif, bmp, ico, tiff,\nwebp, pnm, dds, tga, openexr, farbfeld\n\nMaximum upload size: 5MB, 4000 pixels\n\nIcons are resized to 32x32 pixels.",
        "parameters": [
          {
            "name": "subdomain",
            "schema": {
              "type": "string"
            },
            "in": "path",
            "required": true,
            "deprecated": false,
            "explode": true
          }
        ],
        "requestBody": {
          "content": {
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": ""
          }
        },
        "security": [
          {
            "ApiKeyAuthorization": []
          }
        ]
      },
      "delete": {
        "summary": "Delete a website icon",
        "parameters": [
          {
            "name": "subdomain",
            "schema": {
              "type": "string"
            },
            "in": "path",
            "required": true,
            "deprecated": false,
            "explode": true
          }
        ],
        "responses": {
          "200": {
            "description": ""
          }
        },
        "security": [
          {
            "ApiKeyAuthorization": []
          }
        ]
      }
    },
    "/websites": {
      "get": {
        "summary": "Get all publicly listed websites",
        "description": "Returns all publicly listed websites (visibility != `hidden`)",
        "parameters": [
          {
            "name": "visibility",
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Visibility"
                },
                {
                  "default": "hidden"
                }
              ]
            },
            "in": "query",
            "description": "Mimimum visibility of the websites",
            "required": false,
            "deprecated": false,
            "explode": true
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json; charset=utf-8": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Website"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/websitesAll": {
      "get": {
        "summary": "Get all websites",
        "description": "Returns all websites from Talon's database (including hidden ones, if the current user\nhas access to them). This endpoint requires authentication (use the `/websites` endpoint\nfor unauthenticated users).",
        "parameters": [
          {
            "name": "visibility",
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Visibility"
                },
                {
                  "default": "hidden"
                }
              ]
            },
            "in": "query",
            "description": "Mimimum visibility of the websites",
            "required": false,
            "deprecated": false,
            "explode": true
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json; charset=utf-8": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Website"
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuthorization": []
          }
        ]
      }
    },
    "/website/{subdomain}/versions": {
      "get": {
        "summary": "Get website versions",
        "parameters": [
          {
            "name": "subdomain",
            "schema": {
              "type": "string"
            },
            "in": "path",
            "required": true,
            "deprecated": false,
            "explode": true
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json; charset=utf-8": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Version"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/website/{subdomain}/version/{version}": {
      "get": {
        "summary": "Get version",
        "parameters": [
          {
            "name": "subdomain",
            "schema": {
              "type": "string"
            },
            "in": "path",
            "required": true,
            "deprecated": false,
            "explode": true
          },
          {
            "name": "version",
            "schema": {
              "type": "integer",
              "format": "uint32"
            },
            "in": "path",
            "required": true,
            "deprecated": false,
            "explode": true
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json; charset=utf-8": {
                "schema": {
                  "$ref": "#/components/schemas/Version"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete version",
        "parameters": [
          {
            "name": "subdomain",
            "schema": {
              "type": "string"
            },
            "in": "path",
            "required": true,
            "deprecated": false,
            "explode": true
          },
          {
            "name": "version",
            "schema": {
              "type": "integer",
              "format": "uint32"
            },
            "in": "path",
            "required": true,
            "deprecated": false,
            "explode": true
          }
        ],
        "responses": {
          "200": {
            "description": ""
          }
        },
        "security": [
          {
            "ApiKeyAuthorization": []
          }
        ]
      }
    },
    "/website/{subdomain}/version/{version}/files": {
      "get": {
        "summary": "Get version files",
        "parameters": [
          {
            "name": "subdomain",
            "schema": {
              "type": "string"
            },
            "in": "path",
            "required": true,
            "deprecated": false,
            "explode": true
          },
          {
            "name": "version",
            "schema": {
              "type": "integer",
              "format": "uint32"
            },
            "in": "path",
            "required": true,
            "deprecated": false,
            "explode": true
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json; charset=utf-8": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/VersionFile"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/website/{subdomain}/upload": {
      "post": {
        "summary": "Upload a new version",
        "parameters": [
          {
            "name": "subdomain",
            "schema": {
              "type": "string"
            },
            "in": "path",
            "required": true,
            "deprecated": false,
            "explode": true
          },
          {
            "name": "fallback",
            "schema": {
              "type": "string"
            },
            "in": "query",
            "description": "Fallback page\n\nThe fallback page gets returned when the requested page does not exist",
            "required": false,
            "deprecated": false,
            "explode": true
          },
          {
            "name": "spa",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "in": "query",
            "description": "SPA mode (return fallback page with OK status)",
            "required": false,
            "deprecated": false,
            "explode": true
          },
          {
            "name": "version_data",
            "schema": {
              "type": "object",
              "additionalProperties": {
                "type": "string"
              }
            },
            "in": "query",
            "description": "Associated version data\n\nThis is an arbitrary string map that can hold build information and other stuff\nand will be displayed in the site info dialog.",
            "required": false,
            "deprecated": false,
            "explode": true
          }
        ],
        "requestBody": {
          "content": {
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": ""
          }
        },
        "security": [
          {
            "ApiKeyAuthorization": []
          }
        ]
      }
    },
    "/file/{hash}": {
      "get": {
        "summary": "Retrieve a file",
        "parameters": [
          {
            "name": "hash",
            "schema": {
              "type": "string"
            },
            "in": "path",
            "required": true,
            "deprecated": false,
            "explode": true
          }
        ],
        "responses": {
          "200": {
            "description": "File content",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            },
            "headers": {
              "etag": {
                "description": "File hash",
                "required": true,
                "deprecated": false,
                "schema": {
                  "type": "string"
                }
              },
              "last-modified": {
                "description": "Date when the file was last modified",
                "required": true,
                "deprecated": false,
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/info": {
      "get": {
        "summary": "Get information about your server",
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json; charset=utf-8": {
                "schema": {
                  "$ref": "#/components/schemas/Info"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Info": {
        "type": "object",
        "description": "Server information",
        "required": [
          "stats",
          "version",
          "start_time"
        ],
        "properties": {
          "stats": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Stats"
              },
              {
                "description": "Stats about your instance"
              }
            ]
          },
          "version": {
            "allOf": [
              {
                "$ref": "#/components/schemas/VersionInfo"
              },
              {
                "description": "Version information"
              }
            ]
          },
          "start_time": {
            "type": "string",
            "format": "date-time",
            "description": "Start time of the server"
          }
        }
      },
      "SourceIcon": {
        "type": "string",
        "enum": [
          "link",
          "git",
          "github",
          "gitlab",
          "gitea",
          "bitbucket"
        ]
      },
      "Stats": {
        "type": "object",
        "description": "Stats about your Talon instance",
        "required": [
          "n_websites",
          "n_files",
          "storage_used"
        ],
        "properties": {
          "n_websites": {
            "type": "integer",
            "format": "uint64",
            "description": "Number of websites"
          },
          "n_files": {
            "type": "integer",
            "format": "uint64",
            "description": "Number of unique files"
          },
          "storage_used": {
            "type": "integer",
            "format": "uint64",
            "description": "Amount of used storage space (in bytes)"
          }
        }
      },
      "Version": {
        "type": "object",
        "description": "Website version",
        "required": [
          "id",
          "created_at",
          "data"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "format": "uint32",
            "description": "Version ID"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Version creation date"
          },
          "data": {
            "type": "object",
            "description": "Associated version data\n\nThis is an arbitrary string map that can hold build information and other stuff\nand will be displayed in the site info dialog.",
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      },
      "VersionFile": {
        "type": "object",
        "description": "Website file",
        "required": [
          "path",
          "hash"
        ],
        "properties": {
          "path": {
            "type": "string",
            "description": "File path"
          },
          "hash": {
            "type": "string",
            "description": "File hash"
          },
          "mime": {
            "type": "string",
            "description": "MIME file type"
          }
        }
      },
      "VersionInfo": {
        "type": "object",
        "description": "Information about a Talon version",
        "required": [
          "version",
          "commit",
          "commit_date",
          "rust_version",
          "build_target",
          "build_mode"
        ],
        "properties": {
          "version": {
            "type": "string",
            "description": "Talon version"
          },
          "commit": {
            "type": "string",
            "description": "Commit hash"
          },
          "commit_date": {
            "type": "string",
            "format": "date-time",
            "description": "Commit date"
          },
          "rust_version": {
            "type": "string",
            "description": "Rust version"
          },
          "build_target": {
            "type": "string",
            "description": "Build target (OS and architecture)"
          },
          "build_mode": {
            "type": "string",
            "description": "Rust build mode (`debug` / `release`)"
          }
        }
      },
      "Visibility": {
        "type": "string",
        "enum": [
          "featured",
          "searchable",
          "hidden"
        ]
      },
      "Website": {
        "type": "object",
        "description": "Website",
        "required": [
          "subdomain",
          "name",
          "created_at",
          "visibility",
          "has_icon"
        ],
        "properties": {
          "subdomain": {
            "type": "string",
            "description": "Website subdomain"
          },
          "name": {
            "type": "string",
            "description": "Website name"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Website creation date"
          },
          "latest_version": {
            "type": "integer",
            "format": "uint32",
            "description": "Latest version ID"
          },
          "color": {
            "type": "string",
            "description": "Color of the page icon\n\nFormat: `#7935df`"
          },
          "visibility": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Visibility"
              },
              {
                "description": "Visibility of the page in the sidebar menu"
              }
            ]
          },
          "source_url": {
            "type": "string",
            "description": "Link to the source of the page"
          },
          "source_icon": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SourceIcon"
              },
              {
                "description": "Icon for the source link"
              }
            ]
          },
          "has_icon": {
            "type": "boolean",
            "description": "Does the website have an icon?"
          }
        }
      },
      "WebsiteNew": {
        "type": "object",
        "description": "Create a new website",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Website name"
          },
          "color": {
            "type": "string",
            "description": "Color of the page icon"
          },
          "visibility": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Visibility"
              },
              {
                "description": "Visibility of the page in the sidebar menu",
                "default": "hidden"
              }
            ]
          },
          "source_url": {
            "type": "string",
            "description": "Link to the source of the page"
          },
          "source_icon": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SourceIcon"
              },
              {
                "description": "Icon for the source link"
              }
            ]
          }
        }
      },
      "WebsiteUpdate": {
        "type": "object",
        "description": "Update a website with the contained values\n\nValues set to `None` remain unchanged.",
        "properties": {
          "name": {
            "type": "string",
            "description": "Website name"
          },
          "color": {
            "type": "string",
            "description": "Color of the page icon"
          },
          "visibility": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Visibility"
              },
              {
                "description": "Visibility of the page in the sidebar menu"
              }
            ]
          },
          "source_url": {
            "type": "string",
            "description": "Link to the source of the page"
          },
          "source_icon": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SourceIcon"
              },
              {
                "description": "Icon for the source link"
              }
            ]
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuthorization": {
        "type": "apiKey",
        "name": "X-API-Key",
        "in": "header"
      }
    }
  }
}