{"openapi":"3.1.0","info":{"title":"htmlbin API","version":"1.0.0","summary":"Agent-first HTML hosting. Drop self-contained HTML, get a public URL.","description":"All endpoints under /api/. Auth uses a Bearer token minted via the /api/auth/start device-code flow.","contact":{"url":"https://htmlbin.dev"},"license":{"name":"MIT"}},"servers":[{"url":"https://htmlbin.dev"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"hb_<base62>"}},"schemas":{"Drop":{"type":"object","required":["slug","title","url","raw_url","created_at"],"properties":{"slug":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"url":{"type":"string","format":"uri"},"raw_url":{"type":"string","format":"uri"},"locked":{"type":"boolean"},"latest_version":{"type":"integer"},"view_count":{"type":"integer"},"created_at":{"type":"integer","description":"unix ms"},"updated_at":{"type":"integer","description":"unix ms"}}},"VersionListItem":{"type":"object","required":["version","size_bytes","created_at"],"properties":{"version":{"type":"integer"},"size_bytes":{"type":"integer"},"has_context":{"type":"boolean"},"created_at":{"type":"integer"}}},"Version":{"type":"object","required":["slug","version","size_bytes","created_at"],"properties":{"slug":{"type":"string"},"version":{"type":"integer"},"size_bytes":{"type":"integer"},"context":{"type":"string","nullable":true,"description":"Optional reasoning trace recorded at this version"},"created_at":{"type":"integer"},"is_latest":{"type":"boolean"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}},"paths":{"/api/onboard":{"get":{"summary":"Agent onboarding instructions","description":"Returns the full agent protocol. Markdown by default; pass Accept: application/json for JSON wrapper.","responses":{"200":{"description":"Onboarding text","content":{"text/markdown":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object","properties":{"instructions":{"type":"string"},"public_url":{"type":"string"}}}}}}}}},"/api/auth/start":{"post":{"summary":"Begin device-code flow","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"}}}}}},"responses":{"200":{"description":"Code + poll token","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"verification_url":{"type":"string","format":"uri"},"poll_token":{"type":"string"},"expires_in":{"type":"integer"},"poll_interval":{"type":"integer"}}}}}}}}},"/api/auth/poll":{"get":{"summary":"Poll for verified token","parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Status (and api_token if verified, exactly once)","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["pending","verified","claimed","expired"]},"api_token":{"type":"string"},"user_id":{"type":"string"}}}}}}}}},"/api/prototypes":{"get":{"summary":"List your drops","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Array of drops","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Drop"}}}}}}},"post":{"summary":"Upload a new drop","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","html"],"properties":{"title":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":500},"html":{"type":"string"},"password":{"type":"string","minLength":4}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Drop"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/prototypes/{slug}":{"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get metadata for one of your drops","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Drop metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Drop"}}}}}},"put":{"summary":"Update drop (slug stays the same)","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"html":{"type":"string"}}}}}},"responses":{"200":{"description":"Updated"}}},"delete":{"summary":"Delete drop","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Deleted"}}}},"/api/prototypes/{slug}/password":{"post":{"summary":"Set, change, or remove the password on a drop","security":[{"bearerAuth":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["password"],"properties":{"password":{"type":"string","description":"Empty string to remove"}}}}}},"responses":{"200":{"description":"Updated"}}}},"/p/{slug}":{"get":{"summary":"Public viewer (HTML)","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Viewer page"},"404":{"description":"Not found"}}}},"/p/{slug}/raw":{"get":{"summary":"Raw HTML, edge-cached","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The drop, served as text/html","content":{"text/html":{"schema":{"type":"string"}}}}}}}}}