{"openapi":"3.1.0","info":{"title":"BinHTML API","version":"1.0.0","description":"Publish AI-generated HTML artifacts and receive secure shareable BinHTML links.","contact":{"name":"BinHTML","url":"https://binhtml.com","email":"hello@binhtml.com"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://binhtml.com","description":"Production"}],"externalDocs":{"description":"BinHTML API documentation","url":"https://binhtml.com/docs/api"},"tags":[{"name":"Artifacts","description":"Publish and version sandboxed HTML artifacts with secure share links.","externalDocs":{"url":"https://binhtml.com/docs/api"}},{"name":"Project Shares","description":"Create, inspect, and revoke Pro project share links for grouped artifacts.","externalDocs":{"url":"https://binhtml.com/docs/api"}}],"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer","description":"Use your BinHTML API key as a bearer token."},"headerApiKey":{"type":"apiKey","in":"header","name":"x-binhtml-api-key","description":"Alternative API key header."}},"schemas":{"ArtifactProject":{"type":["object","null"],"required":["id","name","slug"],"properties":{"id":{"type":"string","example":"project_123"},"name":{"type":"string","example":"Launch workspace"},"slug":{"type":"string","example":"launch-workspace"}}},"ProjectShare":{"type":"object","required":["enabled","slug","expiresAt","createdAt","updatedAt"],"properties":{"enabled":{"type":"boolean","example":true},"slug":{"type":["string","null"],"example":"proj_test123"},"expiresAt":{"type":["string","null"],"format":"date-time","example":null},"createdAt":{"type":["string","null"],"format":"date-time","example":"2026-05-15T10:00:00.000Z"},"updatedAt":{"type":["string","null"],"format":"date-time","example":"2026-05-15T10:00:00.000Z"}}},"ProjectShareResponse":{"type":"object","required":["project","share","urls"],"properties":{"project":{"$ref":"#/components/schemas/ArtifactProject"},"share":{"$ref":"#/components/schemas/ProjectShare"},"urls":{"type":"object","required":["projectShare"],"properties":{"projectShare":{"type":["string","null"],"format":"uri","example":"https://binhtml.com/p/proj_test123"}}}}},"Artifact":{"type":"object","required":["id","slug","title","visibility","expiresAt","createdAt","project"],"properties":{"id":{"type":"string","example":"artifact_123"},"slug":{"type":"string","example":"pr-review-dashboard-abcd1234"},"title":{"type":"string","example":"PR review dashboard"},"visibility":{"type":"string","enum":["private","unlisted"],"example":"unlisted"},"expiresAt":{"type":["string","null"],"format":"date-time","example":null},"createdAt":{"type":"string","format":"date-time","example":"2026-05-15T10:00:00.000Z"},"project":{"$ref":"#/components/schemas/ArtifactProject"}}},"Version":{"type":"object","required":["number","sizeBytes","renderMode"],"properties":{"number":{"type":"integer","example":1},"sizeBytes":{"type":"integer","example":7824},"renderMode":{"type":"string","example":"sandboxed-html"}}},"Urls":{"type":"object","required":["share","management","sourceDownload"],"properties":{"share":{"type":"string","format":"uri","example":"https://binhtml.com/a/pr-review-dashboard-abcd1234"},"management":{"type":"string","format":"uri","example":"https://binhtml.com/dashboard/artifacts/artifact_123"},"sourceDownload":{"type":"string","format":"uri","example":"https://binhtml.com/dashboard/artifacts/artifact_123/source"}}},"PublishResponse":{"type":"object","required":["artifact","version","urls"],"properties":{"artifact":{"$ref":"#/components/schemas/Artifact"},"version":{"$ref":"#/components/schemas/Version"},"urls":{"$ref":"#/components/schemas/Urls"}}},"VersionUpdateResponse":{"type":"object","required":["operation","artifact","version","urls"],"properties":{"operation":{"type":"string","enum":["updated"]},"artifact":{"$ref":"#/components/schemas/Artifact"},"version":{"$ref":"#/components/schemas/Version"},"urls":{"$ref":"#/components/schemas/Urls"}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"invalid_request"},"message":{"type":"string","example":"sourceHtml must include a complete HTML document."}}}}},"RateLimitErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","retryAfterSeconds"],"properties":{"code":{"type":"string","enum":["rate_limited"]},"message":{"type":"string"},"retryAfterSeconds":{"type":"integer","example":60}}}}}},"responses":{"UnauthorizedError":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidApiKey":{"value":{"error":{"code":"unauthorized","message":"Missing or invalid API key."}}}}}}},"NotFoundError":{"description":"The requested resource was not found for this API key owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"PayloadTooLargeError":{"description":"HTML source exceeds the current size limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServiceUnavailableError":{"description":"Artifact storage or project sharing is unavailable right now.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RateLimitError":{"description":"Publishing rate limit reached.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Maximum publishes allowed in the current window."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Publishes remaining in the current window."},"X-RateLimit-Reset":{"schema":{"type":"string"},"description":"ISO timestamp when the rate-limit window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}}}},"paths":{"/api/v1/artifacts":{"post":{"operationId":"publishArtifact","tags":["Artifacts"],"summary":"Publish an HTML artifact","description":"Creates a new hosted HTML artifact. The HTML source is validated, stored, and rendered through BinHTML's sandboxed share page.","externalDocs":{"description":"Publishing API guide","url":"https://binhtml.com/docs/api"},"security":[{"bearerApiKey":[]},{"headerApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","sourceHtml"],"properties":{"title":{"type":"string","maxLength":120,"example":"PR review dashboard"},"description":{"type":"string","nullable":true,"example":"Generated review summary for the payments PR."},"projectName":{"type":"string","maxLength":80,"nullable":true,"description":"Optional project name for grouping related artifacts.","example":"Checkout redesign"},"sourceHtml":{"type":"string","description":"A complete HTML document including <!doctype html> or an <html> tag."},"visibility":{"type":"string","enum":["private","unlisted"],"default":"unlisted"},"expiresAt":{"type":"string","format":"date-time","nullable":true,"description":"Optional future expiry timestamp."}}},"examples":{"artifactWithProject":{"summary":"Publish into a project","value":{"title":"PR review dashboard","description":"Generated review summary for the payments PR.","projectName":"Checkout redesign","sourceHtml":"<!doctype html><html><body><h1>Review</h1></body></html>","visibility":"unlisted"}}}}}},"responses":{"201":{"description":"Artifact created. Includes project metadata when projectName is provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishResponse"}}}},"400":{"description":"Invalid title, HTML source, visibility, or expiry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"413":{"$ref":"#/components/responses/PayloadTooLargeError"},"429":{"$ref":"#/components/responses/RateLimitError"},"503":{"$ref":"#/components/responses/ServiceUnavailableError"}}}},"/api/v1/projects/{projectId}/share":{"get":{"operationId":"getProjectShare","tags":["Project Shares"],"summary":"Get a project share link","description":"Returns the current share state for an owned project. Project share pages are unlisted and noindex.","externalDocs":{"description":"Project share links","url":"https://binhtml.com/docs/api"},"security":[{"bearerApiKey":[]},{"headerApiKey":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Project share state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectShareResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"$ref":"#/components/responses/NotFoundError"},"503":{"$ref":"#/components/responses/ServiceUnavailableError"}}},"post":{"operationId":"createProjectShare","tags":["Project Shares"],"summary":"Create or refresh a project share link","description":"Creates one Pro project share URL. Builder users receive plan_limit.","externalDocs":{"description":"Project share links","url":"https://binhtml.com/docs/api"},"security":[{"bearerApiKey":[]},{"headerApiKey":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expiresAt":{"type":["string","null"],"format":"date-time"}}},"examples":{"noExpiry":{"value":{"expiresAt":null}},"expiringShare":{"value":{"expiresAt":"2026-06-15T10:00:00.000Z"}}}}}},"responses":{"201":{"description":"Project share link ready.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectShareResponse"}}}},"400":{"description":"Invalid expiry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"description":"Project share links require Pro.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"planLimit":{"value":{"error":{"code":"plan_limit","message":"Project share links are available on Pro."}}}}}}},"404":{"$ref":"#/components/responses/NotFoundError"},"503":{"$ref":"#/components/responses/ServiceUnavailableError"}}},"delete":{"operationId":"deleteProjectShare","tags":["Project Shares"],"summary":"Disable a project share link","description":"Revokes the current project share URL for an owned project.","externalDocs":{"description":"Project share links","url":"https://binhtml.com/docs/api"},"security":[{"bearerApiKey":[]},{"headerApiKey":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Project share link disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectShareResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"$ref":"#/components/responses/NotFoundError"},"503":{"$ref":"#/components/responses/ServiceUnavailableError"}}}},"/api/v1/projects/share":{"post":{"operationId":"createProjectShareByName","tags":["Project Shares"],"summary":"Create a project share link by project name","description":"Creates or refreshes a Pro project share URL using a project name, useful for agent workflows after publishing with projectName.","externalDocs":{"description":"Project share links","url":"https://binhtml.com/docs/api"},"security":[{"bearerApiKey":[]},{"headerApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["projectName"],"properties":{"projectName":{"type":"string","maxLength":80,"example":"Launch workspace"},"expiresAt":{"type":["string","null"],"format":"date-time"}}},"examples":{"projectName":{"value":{"projectName":"Launch workspace","expiresAt":null}}}}}},"responses":{"201":{"description":"Project share link ready.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectShareResponse"}}}},"400":{"description":"Invalid project name, expiry, or JSON body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"description":"Project share links require Pro.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"$ref":"#/components/responses/NotFoundError"},"503":{"$ref":"#/components/responses/ServiceUnavailableError"}}}},"/api/v1/artifacts/{artifactId}/versions":{"post":{"operationId":"createArtifactVersion","tags":["Artifacts"],"summary":"Upload a new artifact version","description":"Creates a new version for an existing artifact owned by the API key user. The artifact share URL stays the same and the new version becomes current.","externalDocs":{"description":"Version update guide","url":"https://binhtml.com/docs/api"},"security":[{"bearerApiKey":[]},{"headerApiKey":[]}],"parameters":[{"name":"artifactId","in":"path","required":true,"schema":{"type":"string"},"description":"The artifact ID returned by a previous publish."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sourceHtml"],"properties":{"sourceHtml":{"type":"string","description":"A complete replacement HTML document including <!doctype html> or an <html> tag."},"label":{"type":"string","nullable":true,"description":"Optional version label shown in version history."}}},"examples":{"replacementVersion":{"value":{"sourceHtml":"<!doctype html><html><body><h1>Updated review</h1></body></html>","label":"Second draft"}}}}}},"responses":{"201":{"description":"Version created and set as current.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionUpdateResponse"}}}},"400":{"description":"Invalid HTML source or request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"$ref":"#/components/responses/NotFoundError"},"413":{"$ref":"#/components/responses/PayloadTooLargeError"},"429":{"$ref":"#/components/responses/RateLimitError"},"503":{"$ref":"#/components/responses/ServiceUnavailableError"}}}}}}