{"openapi":"3.1.0","info":{"title":"homu API","version":"1.0.0","description":"Read and edit homu link-in-bio pages. Create a key in Dashboard → Account → API & AI. Full guide: https://homu.to/llms-full.txt. MCP server: https://homu.to/api/mcp."},"servers":[{"url":"https://homu.to/api/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"homu_sk_… API key"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"BlockStyle":{"type":"object","description":"Optional on every block: per-block design. Omit fields to follow the page theme. Set content._style = null/omit to reset.","properties":{"align":{"type":"string","description":"\"left\" | \"center\" | \"right\""},"background":{"type":"string","description":"\"none\" | \"surface\" | \"accent\" | \"#rrggbb\""},"textColor":{"type":"string","description":"\"#rrggbb\""},"padding":{"type":"string","description":"BlockSpacing — inner padding"},"spaceAbove":{"type":"string","description":"BlockSpacing"},"spaceBelow":{"type":"string","description":"BlockSpacing"},"radius":{"type":"string","description":"\"none\" | \"sm\" | \"md\" | \"lg\""},"shadow":{"type":"string","description":"\"none\" | \"soft\" | \"strong\""},"hideOn":{"type":"string","description":"\"mobile\" | \"desktop\""}}},"Block":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["PROFILE","HEADER","MENU_LIST","LINKS","FEEDBACK","GALLERY","TIP_BOARD","FUNDING","BOARD","BOOKING","YOUTUBE","TWITCH","GOOGLE_MAPS","TEXT","IMAGE","DIVIDER"]},"order":{"type":"integer"},"visible":{"type":"boolean"},"content":{"type":"object","description":"Type-specific content; may include _style (BlockStyle). See GET /block-types."}}},"BlockInput":{"type":"object","required":["type","content"],"properties":{"id":{"type":"string","description":"Existing id to keep a block (PUT only)"},"type":{"type":"string","enum":["PROFILE","HEADER","MENU_LIST","LINKS","FEEDBACK","GALLERY","TIP_BOARD","FUNDING","BOARD","BOOKING","YOUTUBE","TWITCH","GOOGLE_MAPS","TEXT","IMAGE","DIVIDER"]},"content":{"type":"object"},"style":{"oneOf":[{"$ref":"#/components/schemas/BlockStyle"},{"type":"null"}]},"visible":{"type":"boolean"}}},"Appearance":{"type":"object","properties":{"backgroundColor":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"primaryColor":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"buttonStyle":{"type":"string","enum":["SQUARE","ROUNDED_XS","ROUNDED_SM","ROUNDED_MD","ROUNDED_FULL"]},"font":{"type":"string","description":"Font id from GET /fonts"},"dynamicBackground":{"type":["object","null"]},"customCss":{"type":["string","null"],"maxLength":20000}}},"Page":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"description":{"type":["string","null"]},"publicUrl":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"},"appearance":{"$ref":"#/components/schemas/Appearance"},"blocks":{"type":"array","items":{"$ref":"#/components/schemas/Block"}}}}}},"paths":{"/me":{"get":{"summary":"Account of the API key","responses":{"200":{"description":"OK"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (120/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/pages":{"get":{"summary":"List your pages","responses":{"200":{"description":"OK"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (120/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/pages/{pageId}":{"parameters":[{"name":"pageId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a page with appearance and blocks","responses":{"200":{"description":"Updated page","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"$ref":"#/components/schemas/Page"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (120/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update title, description and appearance","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":["string","null"]},"appearance":{"$ref":"#/components/schemas/Appearance"}}}}}},"responses":{"200":{"description":"Updated page","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"$ref":"#/components/schemas/Page"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (120/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/pages/{pageId}/blocks":{"parameters":[{"name":"pageId","in":"path","required":true,"schema":{"type":"string"}}],"put":{"summary":"Replace all blocks","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["blocks"],"properties":{"blocks":{"type":"array","items":{"$ref":"#/components/schemas/BlockInput"}}}}}}},"responses":{"200":{"description":"Updated page","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"$ref":"#/components/schemas/Page"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (120/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Add a block","requestBody":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BlockInput"},{"type":"object","properties":{"position":{"type":"integer","minimum":1}}}]}}}},"responses":{"200":{"description":"Updated page","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"$ref":"#/components/schemas/Page"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (120/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/pages/{pageId}/blocks/{blockId}":{"parameters":[{"name":"pageId","in":"path","required":true,"schema":{"type":"string"}},{"name":"blockId","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a block","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"object"},"style":{"oneOf":[{"$ref":"#/components/schemas/BlockStyle"},{"type":"null"}]},"visible":{"type":"boolean"},"position":{"type":"integer"}}}}}},"responses":{"200":{"description":"Updated page","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"$ref":"#/components/schemas/Page"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (120/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a block","responses":{"200":{"description":"Updated page","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"$ref":"#/components/schemas/Page"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (120/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/pages/{pageId}/images":{"parameters":[{"name":"pageId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Upload an image","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}},"required":["file"]}}}},"responses":{"200":{"description":"{ url }"},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (120/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/block-types":{"get":{"summary":"Block reference with examples","security":[],"responses":{"200":{"description":"OK"}}}},"/fonts":{"get":{"summary":"Font ids and button styles","security":[],"responses":{"200":{"description":"OK"}}}}}}