{
  "openapi": "3.1.0",
  "info": {
    "title": "DrawFiddle — public read API",
    "version": "1.0.0",
    "description": "Read access to the community snippet catalogue and to the C# source of any shared fiddle. No key and no account are needed for anything described here. Writing (sharing code, publishing apps, voting, account management) needs a session and is intentionally not part of this document — see /auth.md.",
    "license": {
      "name": "Snippets are published by their authors for reuse",
      "url": "https://drawfiddle.com/terms/"
    }
  },
  "servers": [
    {
      "url": "https://drawfiddle.com"
    }
  ],
  "paths": {
    "/api/community": {
      "get": {
        "summary": "List community snippets",
        "parameters": [
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "top",
                "new"
              ],
              "default": "top"
            }
          },
          {
            "name": "kind",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "fiddle",
                "app"
              ],
              "default": "all"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 60,
              "default": 24
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "tag",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Single tag, as listed by /api/community/tags."
          }
        ],
        "responses": {
          "200": {
            "description": "The catalogue. `mine` and `owned` stay empty without a session.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Snippet"
                      }
                    },
                    "mine": {
                      "type": "object",
                      "description": "Your own votes, keyed \"id:kind\". Empty when signed out."
                    },
                    "owned": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Items you listed. Empty when signed out."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/community/tags": {
      "get": {
        "summary": "Tag cloud of listed snippets, most used first",
        "responses": {
          "200": {
            "description": "Tags with counts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tags": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "tag": {
                            "type": "string"
                          },
                          "count": {
                            "type": "integer"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/share/{id}": {
      "get": {
        "summary": "C# source of a shared fiddle",
        "description": "Plain text. The description and tags travel in X-Fiddle-Desc (URI-encoded) and X-Fiddle-Tags response headers. For a readable version with the same source in a fenced block, use /show/{id}.md instead.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ],
        "responses": {
          "200": {
            "description": "The source",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "No such snippet, or it expired"
          }
        }
      }
    },
    "/show/{id}.md": {
      "get": {
        "summary": "A snippet as markdown: title, description, links and the C# source",
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ],
        "responses": {
          "200": {
            "description": "Markdown",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/c/{id}.md": {
      "get": {
        "summary": "Just the source of a snippet, as markdown",
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ],
        "responses": {
          "200": {
            "description": "Markdown",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/f/{id}/og.png": {
      "get": {
        "summary": "Rendered preview of a snippet (1200x630)",
        "parameters": [
          {
            "$ref": "#/components/parameters/Id"
          }
        ],
        "responses": {
          "200": {
            "description": "PNG",
            "content": {
              "image/png": {}
            }
          }
        }
      }
    },
    "/index.md": {
      "get": {
        "summary": "The whole catalogue as one markdown page",
        "responses": {
          "200": {
            "description": "Markdown",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "Id": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "pattern": "^[A-Za-z0-9]{6,16}$"
        }
      }
    },
    "schemas": {
      "Snippet": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "fiddle",
              "app"
            ]
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "author": {
            "type": "string",
            "nullable": true
          },
          "tags": {
            "type": "string",
            "description": "Comma separated."
          },
          "created": {
            "type": "integer",
            "description": "Unix milliseconds."
          },
          "votes": {
            "type": "integer"
          },
          "avg": {
            "type": "number",
            "description": "Mean rating, 1-5."
          },
          "official": {
            "type": "integer",
            "enum": [
              0,
              1
            ]
          },
          "wasm": {
            "type": "integer",
            "enum": [
              0,
              1
            ],
            "description": "1 when the snippet has a published standalone app."
          },
          "server": {
            "type": "integer",
            "enum": [
              0,
              1
            ],
            "description": "1 when it is published as a server-rendered app."
          }
        }
      }
    }
  }
}