{"openapi":"3.1.0","info":{"title":"Astral Developer API","version":"1.0.0","description":"Create exact-byte one-time upload sessions and manage active Astral transfers."},"servers":[{"url":"https://astrls.com/api/v1"}],"tags":[{"name":"Files","description":"Owned active file management."},{"name":"Public","description":"Unauthenticated privacy-safe data."}],"paths":{"/uploads":{"post":{"operationId":"createUploadSession","summary":"Reserve quota and create a one-time resumable upload session","tags":["Files"],"security":[{"bearerApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["clientRequestId","name","mimeType","size","checksum","expiry"],"properties":{"clientRequestId":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._~-]{15,127}$","description":"Owner-scoped idempotency key. Reuse only to retry the exact same upload."},"name":{"type":"string","minLength":1,"maxLength":180},"mimeType":{"type":"string"},"size":{"type":"integer","minimum":1,"maximum":524288000},"checksum":{"type":"string","pattern":"^[0-9a-f]{64}$"},"expiry":{"$ref":"#/components/schemas/Expiry"},"burnAfterDownload":{"type":"boolean","default":false,"description":"Fixes the link to one opening. May be combined with accessPin, but not with another maxOpens value."},"socialPreviewDisabled":{"type":"boolean","default":false,"description":"Prevents social and messaging services from fetching the uploaded image for a link preview."},"accessPin":{"type":"string","pattern":"^[0-9]{6,12}$","writeOnly":true,"description":"Optional numeric PIN; may be combined with maxOpens or burn mode."},"maxOpens":{"type":"integer","minimum":2,"maximum":100,"description":"Optional verified-open limit for Aether and Aether Pro; may be combined with accessPin. Burn mode supplies its own fixed value of one on every plan."}}}}}},"responses":{"201":{"description":"One-time upload session","content":{"application/json":{"schema":{"type":"object","required":["fileId","uploadRequired","uploadUrl","finalizeUrl","expiresAt"],"properties":{"fileId":{"type":"string"},"uploadRequired":{"type":"boolean"},"uploadUrl":{"oneOf":[{"type":"string","format":"uri"},{"type":"null"}]},"finalizeUrl":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Account or scope unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found for this caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Client request ID conflicts with an earlier reservation or was already consumed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Shared account cost-point budget exceeded","headers":{"Retry-After":{"description":"Whole seconds until this account's current fixed window resets.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporary service failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/files":{"get":{"operationId":"listFiles","summary":"List active owned files","tags":["Files"],"security":[{"bearerApiKey":[]}],"responses":{"200":{"description":"Active files","content":{"application/json":{"schema":{"type":"object","required":["files"],"properties":{"files":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/File"}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Account or scope unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found for this caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Shared account cost-point budget exceeded","headers":{"Retry-After":{"description":"Whole seconds until this account's current fixed window resets.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporary service failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/files/{fileId}":{"parameters":[{"$ref":"#/components/parameters/FileId"}],"get":{"operationId":"getFile","summary":"Get one active owned file","tags":["Files"],"security":[{"bearerApiKey":[]}],"responses":{"200":{"description":"Active file","content":{"application/json":{"schema":{"type":"object","required":["file"],"properties":{"file":{"$ref":"#/components/schemas/File"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Account or scope unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found for this caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Shared account cost-point budget exceeded","headers":{"Retry-After":{"description":"Whole seconds until this account's current fixed window resets.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporary service failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateFileExpiry","summary":"Update an active file's expiry","tags":["Files"],"security":[{"bearerApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["expiry"],"properties":{"expiry":{"$ref":"#/components/schemas/Expiry"}}}}}},"responses":{"200":{"description":"Updated file","content":{"application/json":{"schema":{"type":"object","required":["file"],"properties":{"file":{"$ref":"#/components/schemas/File"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Account or scope unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found for this caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"File state does not permit an expiry update","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Shared account cost-point budget exceeded","headers":{"Retry-After":{"description":"Whole seconds until this account's current fixed window resets.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporary service failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteFile","summary":"Delete an active owned file","tags":["Files"],"security":[{"bearerApiKey":[]}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","required":["deleted","id"],"properties":{"deleted":{"type":"boolean","const":true},"id":{"type":"string"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Account or scope unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found for this caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Shared account cost-point budget exceeded","headers":{"Retry-After":{"description":"Whole seconds until this account's current fixed window resets.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporary service failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/files/{fileId}/finalize":{"post":{"operationId":"finalizeUpload","summary":"Verify and publish a completed session upload","tags":["Files"],"security":[{"bearerApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/FileId"}],"responses":{"200":{"description":"Finalized file","content":{"application/json":{"schema":{"type":"object","required":["file"],"properties":{"file":{"$ref":"#/components/schemas/File"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Account or scope unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found for this caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Upload missing, changed, or no longer finalizable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Shared account cost-point budget exceeded","headers":{"Retry-After":{"description":"Whole seconds until this account's current fixed window resets.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporary service failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/shares/{fileId}":{"get":{"operationId":"inspectShare","summary":"Inspect a live public share","tags":["Public"],"security":[],"parameters":[{"$ref":"#/components/parameters/FileId"}],"responses":{"200":{"description":"Live share metadata","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Resource not found for this caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporary service failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stats":{"get":{"operationId":"getGlobalStats","summary":"Get privacy-safe global statistics","tags":["Public"],"security":[],"responses":{"200":{"description":"Current totals and seven-day trends","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"Temporary service failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"astral_live_KEY_ID.SECRET","description":"Personal Astral API key created at /developers. Never ship it to a browser."}},"parameters":{"FileId":{"name":"fileId","in":"path","required":true,"schema":{"type":"string","pattern":"^(?:[A-Za-z0-9_-]{6}|[A-Za-z0-9_-]{24})$"}}},"schemas":{"Error":{"type":"object","additionalProperties":false,"required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string"}}},"Expiry":{"type":"string","pattern":"^(?:forever|[1-9][0-9]{0,5}[mhd])$","example":"45d","description":"Preset or positive whole-number duration in minutes, hours, or days, capped at 365 days; forever disables automatic expiry and requires Aether or Aether Pro."},"File":{"type":"object","additionalProperties":false,"required":["id","name","mimeType","size","status","openCount","createdAt","expiresAt","shareUrl"],"properties":{"id":{"type":"string","pattern":"^(?:[A-Za-z0-9_-]{6}|[A-Za-z0-9_-]{24})$"},"name":{"type":"string","minLength":1,"maxLength":180},"mimeType":{"type":"string"},"size":{"type":"integer","minimum":1,"maximum":524288000},"status":{"type":"string","const":"ready"},"openCount":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Privacy-safe owner-only count of verified, deduplicated opens."},"lastOpenedAt":{"type":"string","format":"date-time","description":"UTC timestamp of the latest counted open; omitted until the first open."},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"shareUrl":{"type":"string","format":"uri"}}}}}}