{"openapi":"3.1.0","info":{"title":"brln.tv — artifact hosting","description":"Upload an HTML page, PDF or image and get a shareable URL back. Built for AI agents: one unauthenticated POST is the whole integration.\n\n**Anonymous** — 2 MB per file, 5 files/month per IP, 30-day retention.\n\n**Registered** — 95 MB per file, no expiry, listable library.\n\n```\ncurl -X POST https://brln.tv/api/artifacts -F 'file=@report.html'\n```\n\nProse documentation: https://brln.tv/docs · MCP server: https://brln.tv/mcp","contact":{"name":"brln.tv","url":"https://brln.tv/"},"license":{"name":"Proprietary"},"version":"0.1.0"},"servers":[{"url":"https://brln.tv","description":"production"}],"paths":{"/health":{"get":{"tags":["health"],"summary":"Health","description":"Liveness plus dependency checks. 503 when Postgres or S3 is unreachable.","operationId":"health","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/auth/register":{"post":{"tags":["authentication"],"summary":"Create an account","description":"Create an account. Registered uploads are larger and never expire.","operationId":"register","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserRegister"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/auth/login":{"post":{"tags":["authentication"],"summary":"Exchange credentials for a bearer token","description":"Exchange email + password for a bearer token.","operationId":"login","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserLogin"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/users/me":{"get":{"tags":["users"],"summary":"Your own profile","description":"The authenticated caller's own profile.","operationId":"getCurrentUser","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/artifacts":{"post":{"tags":["artifacts"],"summary":"Upload an artifact and get a shareable URL","description":"Upload an artifact and get a shareable URL back.\n\nNo account is required. Send `Authorization: Bearer <token>` to upload as a\nregistered user instead, which raises the size limit, removes the expiry and\nmakes the artifact appear in your library.\n\nAnonymous: 2 MB per file, 5 files per month per IP, deleted after 30 days.\nRegistered: 95 MB per file, no expiry.\n\nThe response `delete_token` is returned once, for anonymous uploads only —\nkeep it if you may need to retract the upload.","operationId":"uploadArtifact","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_uploadArtifact"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArtifactUploadResponse"}}}},"413":{"description":"File is larger than the caller's size limit"},"415":{"description":"File extension is not on the accepted list"},"429":{"description":"Anonymous monthly quota for this IP is spent"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/artifacts/my":{"get":{"tags":["artifacts"],"summary":"List your own artifacts","description":"List the authenticated caller's artifacts, newest first.","operationId":"listMyArtifacts","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ArtifactResponse"},"title":"Response Listmyartifacts"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/artifacts/{artifact_id}":{"get":{"tags":["artifacts"],"summary":"Get metadata for one artifact","description":"Public metadata for a single artifact. No authentication required.","operationId":"getArtifact","parameters":[{"name":"artifact_id","in":"path","required":true,"schema":{"type":"string","title":"Artifact Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArtifactResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["artifacts"],"summary":"Delete an artifact","description":"Delete an artifact.\n\nAuthorised either by the owner's bearer token, or — for an anonymous\nupload — by the one-time `X-Delete-Token` returned when it was created.","operationId":"deleteArtifact","parameters":[{"name":"artifact_id","in":"path","required":true,"schema":{"type":"string","title":"Artifact Id"}},{"name":"x-delete-token","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Delete-Token"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/admin/stats":{"get":{"tags":["admin"],"summary":"Platform statistics","operationId":"adminStats","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminStats"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/admin/users":{"get":{"tags":["admin"],"summary":"List users","operationId":"adminListUsers","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AdminUserRow"},"title":"Response Adminlistusers"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/admin/users/{user_id}/ban":{"post":{"tags":["admin"],"summary":"Ban a user and withdraw their artifacts","description":"Ban a user and take their artifacts out of circulation.","operationId":"adminBanUser","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","title":"User Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BanUserRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/admin/users/{user_id}/unban":{"post":{"tags":["admin"],"summary":"Unban a user and restore their artifacts","operationId":"adminUnbanUser","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","title":"User Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/admin/artifacts":{"get":{"tags":["admin"],"summary":"List all artifacts","operationId":"adminListArtifacts","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true},"title":"Response Adminlistartifacts"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/admin/artifacts/{artifact_id}/delete":{"post":{"tags":["admin"],"summary":"Take an artifact down","operationId":"adminDeleteArtifact","parameters":[{"name":"artifact_id","in":"path","required":true,"schema":{"type":"string","title":"Artifact Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteArtifactRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/admin/audit-logs":{"get":{"tags":["admin"],"summary":"Recent moderation actions","operationId":"adminAuditLogs","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Limit"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AdminAuditLogResponse"},"title":"Response Adminauditlogs"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AdminActionType":{"type":"string","enum":["ban_user","unban_user","delete_artifact","restore_artifact","flag_artifact"],"title":"AdminActionType"},"AdminAuditLogResponse":{"properties":{"id":{"type":"string","title":"Id"},"admin_username":{"type":"string","title":"Admin Username"},"action_type":{"$ref":"#/components/schemas/AdminActionType"},"target_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target User Id"},"target_artifact_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Artifact Id"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","admin_username","action_type","created_at"],"title":"AdminAuditLogResponse"},"AdminStats":{"properties":{"total_users":{"type":"integer","title":"Total Users"},"active_users":{"type":"integer","title":"Active Users"},"banned_users":{"type":"integer","title":"Banned Users"},"total_artifacts":{"type":"integer","title":"Total Artifacts"},"active_artifacts":{"type":"integer","title":"Active Artifacts"},"deleted_artifacts":{"type":"integer","title":"Deleted Artifacts"},"total_storage_bytes":{"type":"integer","title":"Total Storage Bytes"}},"type":"object","required":["total_users","active_users","banned_users","total_artifacts","active_artifacts","deleted_artifacts","total_storage_bytes"],"title":"AdminStats"},"AdminUserRow":{"properties":{"id":{"type":"string","title":"Id"},"username":{"type":"string","title":"Username"},"email":{"type":"string","title":"Email"},"role":{"type":"string","title":"Role"},"is_active":{"type":"boolean","title":"Is Active"},"is_banned":{"type":"boolean","title":"Is Banned"},"ban_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ban Reason"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"storage_used_bytes":{"type":"integer","title":"Storage Used Bytes"},"artifacts_count":{"type":"integer","title":"Artifacts Count"}},"type":"object","required":["id","username","email","role","is_active","is_banned","created_at","storage_used_bytes","artifacts_count"],"title":"AdminUserRow"},"ArtifactResponse":{"properties":{"id":{"type":"string","title":"Id"},"filename":{"type":"string","title":"Filename"},"url":{"type":"string","title":"Url"},"file_size_bytes":{"type":"integer","title":"File Size Bytes"},"mime_type":{"type":"string","title":"Mime Type"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At"},"status":{"type":"string","title":"Status"},"download_count":{"type":"integer","title":"Download Count"}},"type":"object","required":["id","filename","url","file_size_bytes","mime_type","created_at","status","download_count"],"title":"ArtifactResponse"},"ArtifactUploadResponse":{"properties":{"id":{"type":"string","title":"Id"},"url":{"type":"string","title":"Url"},"filename":{"type":"string","title":"Filename"},"file_size_bytes":{"type":"integer","title":"File Size Bytes"},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At"},"delete_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Delete Token"}},"type":"object","required":["id","url","filename","file_size_bytes"],"title":"ArtifactUploadResponse","example":{"delete_token":"s3cr3t-one-time-token","expires_at":"2026-09-30T10:30:00Z","file_size_bytes":512000,"filename":"report.html","id":"550e8400-e29b-41d4-a716-446655440000","url":"https://pages.brln.tv/a1b2c3d4/report.html"}},"BanUserRequest":{"properties":{"reason":{"type":"string","maxLength":500,"minLength":5,"title":"Reason"}},"type":"object","required":["reason"],"title":"BanUserRequest"},"Body_uploadArtifact":{"properties":{"file":{"type":"string","format":"binary","title":"File"}},"type":"object","required":["file"],"title":"Body_uploadArtifact"},"DeleteArtifactRequest":{"properties":{"reason":{"type":"string","maxLength":500,"minLength":5,"title":"Reason"}},"type":"object","required":["reason"],"title":"DeleteArtifactRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"TokenResponse":{"properties":{"access_token":{"type":"string","title":"Access Token"},"token_type":{"type":"string","title":"Token Type","default":"bearer"},"user":{"$ref":"#/components/schemas/UserResponse"}},"type":"object","required":["access_token","user"],"title":"TokenResponse"},"UserLogin":{"properties":{"email":{"type":"string","format":"email","title":"Email"},"password":{"type":"string","title":"Password"}},"type":"object","required":["email","password"],"title":"UserLogin"},"UserRegister":{"properties":{"username":{"type":"string","maxLength":50,"minLength":3,"pattern":"^[a-zA-Z0-9][a-zA-Z0-9_-]{1,49}$","title":"Username"},"email":{"type":"string","format":"email","title":"Email"},"password":{"type":"string","maxLength":72,"minLength":8,"title":"Password"}},"type":"object","required":["username","email","password"],"title":"UserRegister","example":{"email":"agent@example.com","password":"correct-horse-battery","username":"agent-smith"}},"UserResponse":{"properties":{"id":{"type":"string","title":"Id"},"username":{"type":"string","title":"Username"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"storage_used_bytes":{"type":"integer","title":"Storage Used Bytes"},"is_banned":{"type":"boolean","title":"Is Banned","default":false}},"type":"object","required":["id","username","created_at","storage_used_bytes"],"title":"UserResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"tags":[{"name":"artifacts","description":"Upload, inspect and delete artifacts."},{"name":"authentication","description":"Register and exchange credentials for a bearer token."},{"name":"users","description":"The authenticated caller's own profile."},{"name":"admin","description":"Moderation. Requires an admin account."},{"name":"health","description":"Service and dependency status."}]}