{"openapi":"3.1.0","info":{"title":"BOP Share Machine Gateway API","version":"1.0.0","description":"Temporary file delivery infrastructure for AI agents and automated systems. Enables agents to create temporary transfer slots, upload artifacts (PDF, image, spreadsheet, archive, document), and obtain temporary receiver links for human users. Built on private S3 storage with automatic expiry (1-7 days). No accounts or permanent storage.","contact":{"name":"BOP Share Support","url":"https://share.bop.ink/lien-he"},"license":{"name":"MIT"}},"servers":[{"url":"https://share.bop.ink","description":"Current BOP Share Environment Gateway"},{"url":"https://share.bop.ink","description":"Production Canonical Host"}],"paths":{"/api/v1/transfers":{"post":{"summary":"Create a temporary transfer slot or upload directly","description":"Initiates a temporary transfer for an artifact. Supports two modes:\n1. Application/JSON: returns a presigned upload URL for direct S3 PUT upload.\n2. Multipart/Form-Data: direct 1-step upload in a single request.\nReturns a temporary receiver URL to deliver to the human user.","operationId":"createTransfer","tags":["Transfers"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTransferJsonRequest"},"examples":{"pdfReport":{"summary":"PDF Report Delivery","value":{"filename":"market_analysis_q3.pdf","contentType":"application/pdf","fileSizeBytes":2457600,"expiryDays":1}},"imageArtifact":{"summary":"Generated PNG Chart","value":{"filename":"architecture_diagram.png","contentType":"image/png","fileSizeBytes":819200,"expiryDays":1}},"archiveZip":{"summary":"Code Archive ZIP","value":{"filename":"project_source.zip","contentType":"application/zip","fileSizeBytes":15728640,"expiryDays":3}}}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/CreateTransferMultipartRequest"}}}},"responses":{"201":{"description":"Transfer slot created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferResponse"}}}},"400":{"description":"Invalid input parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Payload or file exceeds machine ceiling of 50 MiB (52,428,800 bytes)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded (15 creations/min)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Gateway disabled by operator or system under maintenance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/transfers/{fileKey}":{"get":{"summary":"Get transfer metadata and status","description":"Inspects status, expiration time, and preview capability for an active transfer without exposing secret revocation credentials.","operationId":"getTransferStatus","tags":["Transfers"],"parameters":[{"name":"fileKey","in":"path","required":true,"description":"The opaque transfer key or ID (e.g. f_abc123 or d/f_abc123)","schema":{"type":"string","example":"f_4a8b9c0d1e2f"}}],"responses":{"200":{"description":"Transfer status retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferStatusResponse"}}}},"404":{"description":"Transfer not found or already deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"Transfer has expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/transfers/{fileKey}/finalize":{"post":{"summary":"Finalize and activate an uploaded transfer","description":"Validates that the file has been successfully uploaded to the presigned S3 target and verifies the stored size is within the 50 MiB ceiling.","operationId":"finalizeTransfer","tags":["Transfers"],"parameters":[{"name":"fileKey","in":"path","required":true,"description":"The opaque transfer key or ID","schema":{"type":"string","example":"f_4a8b9c0d1e2f"}}],"responses":{"200":{"description":"Transfer verified and activated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinalizeResponse"}}}},"404":{"description":"Upload target not found or PUT not completed yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Uploaded object exceeds 50 MiB (52,428,800 bytes) size limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/transfers/{fileKey}/revoke":{"post":{"summary":"Revoke and destroy an active transfer","description":"Immediately destroys a transfer and permanently deletes the underlying object from storage using its revocation token.","operationId":"revokeTransfer","tags":["Transfers"],"parameters":[{"name":"fileKey","in":"path","required":true,"description":"The opaque transfer key or ID","schema":{"type":"string","example":"f_4a8b9c0d1e2f"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","description":"The secret revocation token returned at transfer creation time","example":"del_sec_a1b2c3d4e5f6"}},"required":["token"]}}}},"responses":{"200":{"description":"Transfer successfully revoked and deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Transfer successfully revoked and deleted."}}}}}},"401":{"description":"Missing revocation token"},"403":{"description":"Invalid or mismatched revocation token"}}}}},"components":{"schemas":{"CreateTransferJsonRequest":{"type":"object","properties":{"filename":{"type":"string","description":"Name of the artifact including file extension","example":"financial_summary.pdf"},"contentType":{"type":"string","description":"MIME content type of the artifact","example":"application/pdf","default":"application/octet-stream"},"fileSizeBytes":{"type":"integer","description":"Expected size in bytes (max: 52428800 bytes / 50 MiB)","example":1048576},"expiryDays":{"type":"integer","description":"Lifetime in days before automatic deletion (min: 1, max: 7, default: 1)","minimum":1,"maximum":7,"example":1}},"required":["filename"]},"CreateTransferMultipartRequest":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"The raw file binary bytes to upload directly (max 50 MiB)"},"filename":{"type":"string","description":"Optional filename override","example":"data.xlsx"},"expiryDays":{"type":"integer","description":"Lifetime in days (1 to 7, default: 1)","example":1}},"required":["file"]},"TransferResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"transfer":{"type":"object","properties":{"id":{"type":"string","example":"f_4a8b9c0d1e2f"},"fileKey":{"type":"string","example":"d/f_4a8b9c0d1e2f"},"url":{"type":"string","format":"uri","description":"The temporary receiver URL to present to the human user","example":"https://share.bop.ink/d/f_4a8b9c0d1e2f"},"filename":{"type":"string","example":"financial_summary.pdf"},"contentType":{"type":"string","example":"application/pdf"},"sizeBytes":{"type":"integer","example":1048576},"expiresAt":{"type":"integer","example":1741234567890},"expiresAtIso":{"type":"string","format":"date-time","example":"2026-09-03T18:00:00.000Z"},"status":{"type":"string","enum":["pending_upload","active"],"example":"pending_upload"}},"required":["id","fileKey","url","filename","expiresAt","expiresAtIso","status"]},"upload":{"type":"object","description":"Presigned upload target for PUTting binary bytes (present when requested via JSON)","properties":{"method":{"type":"string","example":"PUT"},"url":{"type":"string","format":"uri","description":"Temporary presigned S3 PUT URL valid for 15 minutes"},"expiresInSeconds":{"type":"integer","example":900},"headers":{"type":"object","additionalProperties":{"type":"string"},"example":{"Content-Type":"application/pdf"}}}},"revocation":{"type":"object","properties":{"token":{"type":"string","description":"Secret token used to revoke this transfer before expiry (keep confidential)","example":"del_sec_993821038102"},"revokeUrl":{"type":"string","format":"uri","example":"https://share.bop.ink/api/v1/transfers/f_4a8b9c0d1e2f/revoke"}},"required":["token","revokeUrl"]}},"required":["success","transfer","revocation"]},"TransferStatusResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"transfer":{"type":"object","properties":{"id":{"type":"string","example":"f_4a8b9c0d1e2f"},"receiverUrl":{"type":"string","format":"uri"},"filename":{"type":"string","example":"summary.pdf"},"contentType":{"type":"string","example":"application/pdf"},"sizeBytes":{"type":"integer","example":1048576},"expiresAt":{"type":"integer","example":1741234567890},"expiresAtIso":{"type":"string","format":"date-time"},"isExpired":{"type":"boolean","example":false},"previewEligibility":{"type":"boolean","example":false},"previewCategory":{"type":"string","example":"unsupported"}}}}},"FinalizeResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"transfer":{"type":"object","properties":{"id":{"type":"string","example":"f_4a8b9c0d1e2f"},"receiverUrl":{"type":"string","format":"uri"},"sizeBytes":{"type":"integer","example":1048576},"expiresAt":{"type":"integer","example":1741234567890},"expiresAtIso":{"type":"string","format":"date-time"},"status":{"type":"string","example":"active"}}}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"FILE_TOO_LARGE"},"message":{"type":"string","example":"File size exceeds machine limit of 50 MiB (52428800 bytes)."},"retryable":{"type":"boolean","example":false}},"required":["code","message","retryable"]}},"required":["error"]}}}}