{"openapi":"3.1.0","info":{"title":"HTMLinks API","version":"0.1.0","description":"Publish self-contained HTML. Anonymous uploads. Each document has its own secret management key."},"servers":[{"url":"https://www.htmlinks.com/api/v1"}],"paths":{"/documents":{"post":{"summary":"Upload HTML without an account","security":[],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":32,"maxLength":128}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"},"metadata":{"type":"string","description":"JSON-encoded metadata; only read on creation."}}}}}},"responses":{"201":{"description":"Success","headers":{"ETag":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document","description":"Includes a secret manageKey on creation."}}}},"default":{"description":"Error; 401 unauthorized, 403 forbidden, 404 unavailable, 409 quota/idempotency, 412 stale ETag, 413 body limit, 415 file type, 422 validation, 428 missing ETag, 429 rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}":{"get":{"summary":"Read metadata","security":[{"managementKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","headers":{"ETag":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"default":{"description":"Error; 401 unauthorized, 403 forbidden, 404 unavailable, 409 quota/idempotency, 412 stale ETag, 413 body limit, 415 file type, 422 validation, 428 missing ETag, 429 rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Change metadata or access","security":[{"managementKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"},"example":"\"1\""}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"title":{"type":"string","minLength":1,"maxLength":160},"category":{"enum":["design","presentation","technical","report","other"]},"access":{"enum":["private","link","password"]},"password":{"type":"string","minLength":8,"maxLength":256,"writeOnly":true},"expiresAt":{"type":["string","null"],"format":"date-time"}}}}}},"responses":{"200":{"description":"Success","headers":{"ETag":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"default":{"description":"Error; 401 unauthorized, 403 forbidden, 404 unavailable, 409 quota/idempotency, 412 stale ETag, 413 body limit, 415 file type, 422 validation, 428 missing ETag, 429 rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Soft delete and revoke access","security":[{"managementKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"},"example":"\"1\""}],"responses":{"200":{"description":"Success","headers":{"ETag":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"default":{"description":"Error; 401 unauthorized, 403 forbidden, 404 unavailable, 409 quota/idempotency, 412 stale ETag, 413 body limit, 415 file type, 422 validation, 428 missing ETag, 429 rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}/content":{"put":{"summary":"Publish a replacement revision","security":[{"managementKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"},"example":"\"1\""},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":32,"maxLength":128}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"},"metadata":{"type":"string","description":"JSON-encoded metadata; only read on creation."}}}}}},"responses":{"200":{"description":"Success","headers":{"ETag":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"default":{"description":"Error; 401 unauthorized, 403 forbidden, 404 unavailable, 409 quota/idempotency, 412 stale ETag, 413 body limit, 415 file type, 422 validation, 428 missing ETag, 429 rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}/source":{"get":{"summary":"Download current HTML source","security":[{"managementKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"HTML attachment","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/documents/{id}/revisions":{"get":{"summary":"List revisions","security":[{"managementKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","headers":{"ETag":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"revisions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"number":{"type":"integer"},"size":{"type":"integer"},"filename":{"type":"string"},"checksum":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}}}}}}},"default":{"description":"Error; 401 unauthorized, 403 forbidden, 404 unavailable, 409 quota/idempotency, 412 stale ETag, 413 body limit, 415 file type, 422 validation, 428 missing ETag, 429 rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}/revisions/{revisionId}/source":{"get":{"summary":"Download revision HTML","security":[{"managementKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"revisionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"HTML attachment","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/documents/{id}/rollback":{"post":{"summary":"Republish an earlier revision","security":[{"managementKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"},"example":"\"1\""}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["revisionId"],"properties":{"revisionId":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Success","headers":{"ETag":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"default":{"description":"Error; 401 unauthorized, 403 forbidden, 404 unavailable, 409 quota/idempotency, 412 stale ETag, 413 body limit, 415 file type, 422 validation, 428 missing ETag, 429 rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}/restore":{"post":{"summary":"Restore a recoverable document","security":[{"managementKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"If-Match","in":"header","required":true,"schema":{"type":"string"},"example":"\"1\""}],"responses":{"200":{"description":"Success","headers":{"ETag":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"default":{"description":"Error; 401 unauthorized, 403 forbidden, 404 unavailable, 409 quota/idempotency, 412 stale ETag, 413 body limit, 415 file type, 422 validation, 428 missing ETag, 429 rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}/preview":{"post":{"summary":"Create a single-use viewer handoff","security":[{"managementKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","headers":{"ETag":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","format":"uri"},"grant":{"type":"string"}}}}}},"default":{"description":"Error; 401 unauthorized, 403 forbidden, 404 unavailable, 409 quota/idempotency, 412 stale ETag, 413 body limit, 415 file type, 422 validation, 428 missing ETag, 429 rate limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"managementKey":{"type":"http","scheme":"bearer"}},"schemas":{"Document":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"publicId":{"type":"string"},"manageKey":{"type":"string","description":"Returned only when creating a document; keep private."},"title":{"type":"string"},"category":{"type":"string"},"access":{"enum":["private","link","password"]},"revision":{"type":"integer"},"version":{"type":"integer"},"etag":{"type":"string"},"size":{"type":"integer"},"url":{"type":"string","format":"uri"},"expiresAt":{"type":["string","null"],"format":"date-time"},"deletedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}}}}}}}}