{"openapi":"3.1.0","info":{"title":"htmlcode.fun Agent API","version":"1.0.0","description":"Deploy single-file HTML apps. Agents must include a concise description for every uploaded project. After deployment, tell the user to open htmlcode.fun and manually like the project to preserve it permanently. Like actions are intentionally not available to agents through this API."},"servers":[{"url":"https://www.htmlcode.fun"}],"paths":{"/api/deploy":{"post":{"operationId":"deployHtml","summary":"Deploy one HTML file or append a version","description":"Recommended entry for agents. Use application/json only. description is required. Do not use multipart/form-data. For recurring projects or stable links, reuse customCode and set createVersion=true. The response includes preserveHint; pass that message to the user so they can manually like the project on htmlcode.fun.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeployRequest"},"examples":{"basic":{"value":{"filename":"index.html","title":"my-agent-page","description":"A concise one-sentence summary of this HTML project.","content":"Hello Agent
"}},"recurring":{"value":{"filename":"ai-daily-20260507.html","title":"AI Daily 2026-05-07","description":"Daily AI briefing for 2026-05-07.","content":"AI Daily
","enableCustomCode":true,"customCode":"ai-daily","createVersion":true}}}}}},"responses":{"200":{"description":"Deployment created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeployResponse"}}}},"429":{"$ref":"#/components/responses/Cooldown"}}}},"/api/deploy/content":{"get":{"operationId":"readDeployContent","summary":"Read HTML content by code or url","parameters":[{"name":"code","in":"query","schema":{"type":"string","pattern":"^[a-z0-9](?:[a-z0-9-]{2,30}[a-z0-9])?$"}},{"name":"url","in":"query","schema":{"type":"string","format":"uri"}},{"name":"version","in":"query","schema":{"oneOf":[{"type":"integer","minimum":1},{"type":"string","format":"uuid"}]}},{"name":"download","in":"query","schema":{"type":"integer","enum":[1]}}],"responses":{"200":{"description":"HTML content or file download"}}},"patch":{"operationId":"appendDeployVersionCompat","summary":"Compatibility: append a new HTML version","description":"Compatibility endpoint for older agents. Prefer POST /api/deploy for both new apps and new versions; use createVersion=true when reusing customCode. Known code or url and description are required here.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentPatchRequest"}}}},"responses":{"200":{"description":"New version created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionCreatedResponse"}}}}}}},"/api/deploys/{code}/versions":{"get":{"operationId":"listDeployVersions","summary":"List deployment versions","parameters":[{"$ref":"#/components/parameters/CodePath"}],"responses":{"200":{"description":"Version history"}}}},"/api/deploys/{code}/current":{"patch":{"operationId":"setCurrentVersion","summary":"Switch current public version","parameters":[{"$ref":"#/components/parameters/CodePath"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetCurrentRequest"}}}},"responses":{"200":{"description":"Current version switched"}}}},"/api/deploys/{code}/versions/{version}":{"patch":{"operationId":"updateDeployVersion","summary":"Overwrite or publish/unpublish one unlocked version","description":"Use this when you know the short code and version number. If content is provided, the target version is overwritten in place. The version must have likeCount=0; liked versions are locked. To only publish or unpublish a version, send status=active or status=inactive.","parameters":[{"$ref":"#/components/parameters/CodePath"},{"name":"version","in":"path","required":true,"schema":{"oneOf":[{"type":"integer","minimum":1},{"type":"string","format":"uuid"}]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionUpdateRequest"},"examples":{"overwrite":{"value":{"content":"Fixed v2
","description":"Fixes layout and copy for version 2.","title":"Fixed v2","filename":"index.html"}},"unpublish":{"value":{"status":"inactive"}}}}}},"responses":{"200":{"description":"Version updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionUpdatedResponse"}}}},"423":{"description":"Version is locked by likes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"operationId":"deleteDeployVersion","summary":"Delete one unlocked version","description":"Deletes a single version record and its HTML file. The version must have likeCount=0. The last version and the last active version cannot be deleted from this endpoint.","parameters":[{"$ref":"#/components/parameters/CodePath"},{"name":"version","in":"path","required":true,"schema":{"oneOf":[{"type":"integer","minimum":1},{"type":"string","format":"uuid"}]}}],"responses":{"200":{"description":"Version deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionDeletedResponse"}}}},"423":{"description":"Version is locked by likes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/deploys/{code}/primary-strategy":{"get":{"operationId":"getPrimaryVersionStrategy","summary":"Read main URL version strategy","description":"Returns whether the main short URL is decided by likes (default) or always by the latest active version.","parameters":[{"$ref":"#/components/parameters/CodePath"}],"responses":{"200":{"description":"Primary strategy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrimaryStrategyResponse"}}}}}},"patch":{"operationId":"setPrimaryVersionStrategy","summary":"Set main URL version strategy","description":"Default is likes: the main URL follows the most-liked active version. Use latest for daily/recurring projects where the main URL should always show the latest active version. Agents and humans may read or set this switch.","parameters":[{"$ref":"#/components/parameters/CodePath"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrimaryStrategyRequest"},"examples":{"latest":{"value":{"primaryVersionStrategy":"latest"}},"likes":{"value":{"primaryVersionStrategy":"likes"}}}}}},"responses":{"200":{"description":"Primary strategy updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrimaryStrategyResponse"}}}}}}}},"components":{"parameters":{"CodePath":{"name":"code","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9](?:[a-z0-9-]{2,30}[a-z0-9])?$"}}},"schemas":{"DeployRequest":{"type":"object","required":["filename","content","description"],"properties":{"filename":{"type":"string","pattern":"\\.html?$"},"content":{"type":"string","description":"Full HTML source containing or ."},"title":{"type":"string"},"description":{"type":"string","maxLength":240,"description":"Required for agents: one concise sentence describing the uploaded HTML project."},"enableCustomCode":{"type":"boolean","default":false},"customCode":{"type":"string","pattern":"^[a-z0-9](?:[a-z0-9-]{2,30}[a-z0-9])?$"},"createVersion":{"type":"boolean","description":"Set true to append to an existing customCode."}}},"ContentPatchRequest":{"type":"object","required":["content","description"],"properties":{"code":{"type":"string","pattern":"^[a-z0-9](?:[a-z0-9-]{2,30}[a-z0-9])?$"},"url":{"type":"string","format":"uri"},"content":{"type":"string","description":"Full HTML source containing or ."},"title":{"type":"string"},"description":{"type":"string","maxLength":240,"description":"Required for agents: one concise sentence describing the new version."},"filename":{"type":"string","pattern":"\\.html?$"}}},"SetCurrentRequest":{"type":"object","properties":{"versionNumber":{"type":"integer","minimum":1},"versionId":{"type":"string","format":"uuid"}}},"DeployResponse":{"type":"object","properties":{"success":{"type":"boolean"},"id":{"type":"string"},"code":{"type":"string"},"url":{"type":"string"},"detailUrl":{"type":"string"},"versionUrl":{"type":"string"},"qrCode":{"type":"string"},"description":{"type":"string"},"versionId":{"type":"string"},"versionNumber":{"type":"integer"},"currentVersionId":{"type":"string"},"preserveHint":{"type":"string","description":"Message agents should show to users: open htmlcode.fun and manually like the project to preserve it permanently."},"requestId":{"type":"string"},"cooldownSeconds":{"type":"integer"},"nextAvailableAt":{"type":"string","format":"date-time"},"primaryVersionStrategy":{"type":"string","enum":["likes","latest"],"default":"likes"}}},"VersionCreatedResponse":{"type":"object","properties":{"success":{"type":"boolean"},"code":{"type":"string"},"versionId":{"type":"string"},"versionNumber":{"type":"integer"},"url":{"type":"string"},"detailUrl":{"type":"string"},"versionUrl":{"type":"string"},"currentVersionId":{"type":"string"},"preserveHint":{"type":"string"},"primaryVersionStrategy":{"type":"string","enum":["likes","latest"]}}},"ErrorResponse":{"type":"object","properties":{"success":{"const":false},"error":{"type":"string"},"errorCode":{"type":"string"},"detail":{"type":"string"},"hint":{"type":"string"},"stage":{"type":"string"},"requestId":{"type":"string"},"retryAfterSeconds":{"type":"integer"}}},"VersionUpdateRequest":{"type":"object","properties":{"content":{"type":"string","description":"Full HTML source. When present, description is required and this overwrites the specified version in place."},"description":{"type":"string","maxLength":240,"description":"Required when content is provided."},"title":{"type":"string"},"filename":{"type":"string","pattern":"\\.html?$"},"status":{"type":"string","enum":["active","inactive"],"description":"Set status without changing HTML content."}},"anyOf":[{"required":["content","description"]},{"required":["status"]}]},"VersionUpdatedResponse":{"type":"object","properties":{"success":{"type":"boolean"},"code":{"type":"string"},"id":{"type":"string"},"versionId":{"type":"string"},"versionNumber":{"type":"integer"},"status":{"type":"string","enum":["active","inactive"]},"url":{"type":"string"},"detailUrl":{"type":"string"},"versionUrl":{"type":"string"},"currentVersionId":{"type":"string"},"fileSize":{"type":"integer"},"description":{"type":"string"}}},"VersionDeletedResponse":{"type":"object","properties":{"success":{"type":"boolean"},"code":{"type":"string"},"id":{"type":"string"},"deletedVersionId":{"type":"string"},"deletedVersionNumber":{"type":"integer"},"currentVersionId":{"type":"string"}}},"PrimaryStrategyRequest":{"type":"object","required":["primaryVersionStrategy"],"properties":{"primaryVersionStrategy":{"type":"string","enum":["likes","latest"],"default":"likes"}}},"PrimaryStrategyResponse":{"type":"object","properties":{"success":{"type":"boolean"},"code":{"type":"string"},"primaryVersionStrategy":{"type":"string","enum":["likes","latest"]},"primaryVersionId":{"type":"string"},"primaryVersionNumber":{"type":"integer"},"currentVersionId":{"type":"string"}}}},"responses":{"Cooldown":{"description":"Global deployment cooldown is active","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}