{"openapi":"3.1.0","info":{"contact":{"email":"hi@hedia.com","name":"Hedia ApS","url":"https://hedia.com"},"termsOfService":"https://www.hedia.com/terms-and-conditions","title":"Asset Service API","version":"1.0.0"},"servers":[{"url":"https://asset.hedia.com/api/v1"}],"tags":[{"name":"Assets","description":"Manage assets","externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/operations#assets","description":"Documentation"}}],"paths":{"/assets":{"get":{"summary":"List assets","description":"List user assets created by the current application.","operationId":"listAssets","parameters":[{"$ref":"#/components/parameters/LimitQueryParameter"},{"$ref":"#/components/parameters/OrderQueryParameter"},{"$ref":"#/components/parameters/SkipQueryParameter"},{"$ref":"#/components/parameters/StatusQueryParameter"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssetList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"default":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"accessToken":[]}],"tags":["Assets"],"externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/operations/listAssets","description":"Documentation"}},"post":{"summary":"Create asset","description":"Creates an asset and returns a presigned URL for uploading its associated file. Returns a 422 error if quota limits are exceeded.\n\nTo upload the file, perform a `PUT` request to the returned upload URL with the following headers: `Content-Type`, `Content-Length`, and `x-amz-checksum-sha256`, using the same values as those provided in the asset creation request.\n\nThe file must be uploaded and validated using the complete operation within 60 minutes of asset creation.\n","operationId":"createAsset","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAssetRequestBody"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadableAsset"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"default":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"accessToken":[]},{"trustedServiceWithUser":[]}],"tags":["Assets"],"externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/operations/createAsset","description":"Documentation"}}},"/assets/{assetId}":{"delete":{"summary":"Delete asset","description":"Deletes an asset and its associated file if any.","operationId":"deleteAsset","parameters":[{"$ref":"#/components/parameters/AssetIdPathParameter"},{"$ref":"#/components/parameters/AppIdQueryParameter"}],"responses":{"204":{"$ref":"#/components/responses/NoContent"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"default":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"accessToken":[]},{"trustedServiceWithUser":[]}],"tags":["Assets"],"externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/operations/deleteAsset","description":"Documentation"}},"get":{"summary":"Get asset","description":"Get asset metadata.","operationId":"getAsset","parameters":[{"$ref":"#/components/parameters/AssetIdPathParameter"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Asset"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"default":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"accessToken":[]},{"serviceWithUser":[]}],"tags":["Assets"],"externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/operations/getAsset","description":"Documentation"}},"patch":{"summary":"Update asset","description":"Updates a readable asset metadata. Returns a 422 error if the asset is not readable.","operationId":"updateAsset","parameters":[{"$ref":"#/components/parameters/AssetIdPathParameter"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAssetRequestBody"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadableAsset"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"default":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"accessToken":[]}],"tags":["Assets"],"externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/operations/updateAsset","description":"Documentation"}}},"/assets/{assetId}/complete":{"post":{"summary":"Complete upload","description":"Marks the asset as readable. Returns a 422 error if the associated file has not been uploaded or if the checksum, content type, or size do not match the expected values.\n\nThis operation must be called within 60 minutes of asset creation. After that deadline, the asset is considered expired and will be automatically deleted.\n","operationId":"completeUpload","parameters":[{"$ref":"#/components/parameters/AssetIdPathParameter"},{"$ref":"#/components/parameters/AppIdQueryParameter"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadableAsset"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"default":{"$ref":"#/components/responses/InternalServerError"}},"security":[{"accessToken":[]},{"trustedServiceWithUser":[]}],"tags":["Assets"],"externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/operations/completeUpload","description":"Documentation"}}}},"components":{"securitySchemes":{"accessToken":{"description":"An OAuth2 Access Token.","type":"http","scheme":"bearer","bearerFormat":"JWT"},"serviceWithUser":{"description":"A Service Bearer JSON Web Token with a sub property set to a user ID.","type":"http","scheme":"bearer","bearerFormat":"JWT"},"trustedServiceWithUser":{"description":"A Service Bearer JSON Web Token with a sub property set to a user ID, issued by one of an explicit\nallowlist of trusted services (see server config), not by any service on serviceUrls. Used for write\noperations that are otherwise restricted to accessToken, to allow specific trusted server-side tooling\nto call them without a real OAuth2 client.\n","type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"Limit":{"title":"Limit","type":"number","maximum":100,"minimum":1,"default":10,"$id":"./components/schemas/Limit","externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/components/schemas/Limit","description":"Documentation"}},"Order":{"title":"Order","type":"string","enum":["asc","desc"],"default":"asc","$id":"./components/schemas/Order","externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/components/schemas/Order","description":"Documentation"}},"Skip":{"title":"Skip","type":"number","minimum":0,"default":0,"$id":"./components/schemas/Skip","externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/components/schemas/Skip","description":"Documentation"}},"ReadableAssetStatus":{"title":"Readable Asset Status","description":"The asset is fully uploaded and can be downloaded.","type":"string","const":"readable","$id":"./components/schemas/ReadableAssetStatus","externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/components/schemas/ReadableAssetStatus","description":"Documentation"}},"UploadableAssetStatus":{"title":"Uploadable Asset Status","description":"The asset is awaiting upload completion and cannot be downloaded until the upload process is complete.","type":"string","const":"uploadable","$id":"./components/schemas/UploadableAssetStatus","externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/components/schemas/UploadableAssetStatus","description":"Documentation"}},"AssetStatus":{"title":"Asset Status","description":"The current status of the asset.","default":"readable","oneOf":[{"$ref":"#/components/schemas/ReadableAssetStatus"},{"$ref":"#/components/schemas/UploadableAssetStatus"}],"$id":"./components/schemas/AssetStatus","externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/components/schemas/AssetStatus","description":"Documentation"}},"ProblemDetails":{"title":"Problem Details","description":"A problem details object provides additional information about a problem that occurred during an API request.","type":"object","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type.","examples":["/problems/unauthorized","about:blank"]},"title":{"type":"string","description":"A short, human-readable summary of the problem type.","examples":["Unauthorized"]},"status":{"type":"number","description":"The HTTP status code generated by the origin server for this occurrence of the problem.","examples":[401]},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem.","examples":["You must authenticate and provide the necessary permissions to access this resource. Please check your credentials or token."]}},"required":["type"],"$id":"./components/schemas/ProblemDetails","externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/components/schemas/ProblemDetails","description":"Documentation"}},"AssetId":{"title":"Asset ID","type":"string","format":"uuid","examples":["cf0102d1-3d48-4467-9887-da4d390267c6"],"$id":"./components/schemas/AssetId","externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/components/schemas/AssetId","description":"Documentation"}},"AppId":{"title":"App ID","type":"string","format":"uuid","examples":["3f483b7c-ae82-44ac-94f1-0820861fef29"],"$id":"./components/schemas/AppId","externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/components/schemas/AppId","description":"Documentation"}},"UserId":{"title":"User ID","type":"string","format":"uuid","examples":["3f483b7c-ae82-44ac-94f1-0820861fef29"],"$id":"./components/schemas/UserId","externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/components/schemas/UserId","description":"Documentation"}},"AssetStorageKey":{"title":"Asset Storage Key","description":"The unique storage key for the asset.","type":"string","examples":["3a7cf05d-1416-4dc6-8531-2e18037e7f1f"],"$id":"./components/schemas/AssetStorageKey","externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/components/schemas/AssetStorageKey","description":"Documentation"}},"AssetChecksum":{"title":"Asset Checksum","description":"The base64 encoded, 256-bit SHA256 digest of the asset file.","type":"string","minLength":44,"maxLength":44,"examples":["PMn3M4bMd4BMeNhBEDZNQLYxOa6l0luM+IrDA3pZlpY="],"$id":"./components/schemas/AssetChecksum","externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/components/schemas/AssetChecksum","description":"Documentation"}},"AssetContentType":{"title":"Asset Content Type","description":"The MIME type of the asset file.","type":"string","minLength":1,"maxLength":255,"examples":["application/pdf","image/png"],"$id":"./components/schemas/AssetContentType","externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/components/schemas/AssetContentType","description":"Documentation"}},"AssetFilename":{"title":"Asset Filename","description":"The name of the asset file.","type":"string","minLength":1,"maxLength":255,"examples":["document.pdf","image.png"],"$id":"./components/schemas/AssetFilename","externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/components/schemas/AssetFilename","description":"Documentation"}},"AssetSize":{"title":"Asset Size","description":"The size of the asset file in bytes. Must be a positive integer not exceeding 20 MiB.","type":"integer","minimum":1,"maximum":20971520,"examples":[1024,5242880],"$id":"./components/schemas/AssetSize","externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/components/schemas/AssetSize","description":"Documentation"}},"PresignedUrl":{"title":"Presigned URL","description":"A presigned URL for upload or download operations expiring after 60 minutes.","type":"string","format":"uri","examples":["https://object-storage.hedia.com/bucket/key?X-Amz-Expires=3600&X-Amz-Signature=signature"],"$id":"./components/schemas/PresignedUrl","externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/components/schemas/PresignedUrl","description":"Documentation"}},"Date":{"title":"Date","type":"string","format":"date-time","examples":["2023-10-05T14:48:00.000Z"],"$id":"./components/schemas/Date","externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/components/schemas/Date","description":"Documentation"}},"SecurityPrincipalId":{"title":"Security Principal Id","anyOf":[{"$ref":"#/components/schemas/AppId"},{"$ref":"#/components/schemas/UserId"}],"$id":"./components/schemas/SecurityPrincipalId","externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/components/schemas/SecurityPrincipalId","description":"Documentation"}},"SecurityPrincipalType":{"title":"Security Principal Type","type":"string","enum":["app","system","user"],"$id":"./components/schemas/SecurityPrincipalType","externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/components/schemas/SecurityPrincipalType","description":"Documentation"}},"SecurityPrincipal":{"title":"Security Principal","type":"object","properties":{"id":{"$ref":"#/components/schemas/SecurityPrincipalId"},"type":{"$ref":"#/components/schemas/SecurityPrincipalType"}},"required":["id","type"],"additionalProperties":false,"$id":"./components/schemas/SecurityPrincipal","externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/components/schemas/SecurityPrincipal","description":"Documentation"}},"Created":{"title":"Created","description":"Information about the creation of an entity.","type":"object","properties":{"at":{"$ref":"#/components/schemas/Date"},"by":{"$ref":"#/components/schemas/SecurityPrincipal"}},"required":["at","by"],"additionalProperties":false,"$id":"./components/schemas/Created","externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/components/schemas/Created","description":"Documentation"}},"Updated":{"title":"Updated","description":"Information about the update of an entity.","type":"object","properties":{"at":{"$ref":"#/components/schemas/Date"},"by":{"$ref":"#/components/schemas/SecurityPrincipal"}},"required":["at","by"],"additionalProperties":false,"$id":"./components/schemas/Updated","externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/components/schemas/Updated","description":"Documentation"}},"ReadableAsset":{"title":"Readable Asset","type":"object","properties":{"id":{"$ref":"#/components/schemas/AssetId"},"appId":{"$ref":"#/components/schemas/AppId"},"userId":{"$ref":"#/components/schemas/UserId"},"storageKey":{"$ref":"#/components/schemas/AssetStorageKey"},"checksum":{"$ref":"#/components/schemas/AssetChecksum"},"contentType":{"$ref":"#/components/schemas/AssetContentType"},"filename":{"$ref":"#/components/schemas/AssetFilename"},"size":{"$ref":"#/components/schemas/AssetSize"},"status":{"$ref":"#/components/schemas/ReadableAssetStatus"},"downloadUrl":{"$ref":"#/components/schemas/PresignedUrl"},"created":{"$ref":"#/components/schemas/Created"},"updated":{"$ref":"#/components/schemas/Updated"}},"required":["id","appId","userId","storageKey","checksum","contentType","filename","size","status","downloadUrl","created"],"additionalProperties":false,"$id":"./components/schemas/ReadableAsset","externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/components/schemas/ReadableAsset","description":"Documentation"}},"UploadableAsset":{"title":"Uploadable Asset","type":"object","properties":{"id":{"$ref":"#/components/schemas/AssetId"},"appId":{"$ref":"#/components/schemas/AppId"},"userId":{"$ref":"#/components/schemas/UserId"},"storageKey":{"$ref":"#/components/schemas/AssetStorageKey"},"checksum":{"$ref":"#/components/schemas/AssetChecksum"},"contentType":{"$ref":"#/components/schemas/AssetContentType"},"filename":{"$ref":"#/components/schemas/AssetFilename"},"size":{"$ref":"#/components/schemas/AssetSize"},"status":{"$ref":"#/components/schemas/UploadableAssetStatus"},"uploadUrl":{"$ref":"#/components/schemas/PresignedUrl"},"created":{"$ref":"#/components/schemas/Created"},"updated":{"$ref":"#/components/schemas/Updated"}},"required":["id","appId","userId","storageKey","checksum","contentType","filename","size","status","uploadUrl","created"],"additionalProperties":false,"$id":"./components/schemas/UploadableAsset","externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/components/schemas/UploadableAsset","description":"Documentation"}},"Asset":{"title":"Asset","type":"object","oneOf":[{"$ref":"#/components/schemas/ReadableAsset"},{"$ref":"#/components/schemas/UploadableAsset"}],"$id":"./components/schemas/Asset","externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/components/schemas/Asset","description":"Documentation"}},"AssetList":{"title":"Asset List","description":"List of assets","type":"array","items":{"$ref":"#/components/schemas/Asset"},"$id":"./components/schemas/AssetList","externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/components/schemas/AssetList","description":"Documentation"}},"CreateAssetRequestBody":{"title":"Create Asset Request Body","type":"object","properties":{"appId":{"description":"The app to attribute this asset to. Only used (and required) when authenticating with the\n`trustedServiceWithUser` security scheme, which has no app of its own. Ignored when\nauthenticating with `accessToken`, whose own app is used instead.\n","$ref":"#/components/schemas/AppId"},"checksum":{"$ref":"#/components/schemas/AssetChecksum"},"contentType":{"$ref":"#/components/schemas/AssetContentType"},"filename":{"$ref":"#/components/schemas/AssetFilename"},"size":{"$ref":"#/components/schemas/AssetSize"}},"required":["checksum","contentType","filename","size"],"additionalProperties":false,"$id":"./components/schemas/CreateAssetRequestBody","externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/components/schemas/CreateAssetRequestBody","description":"Documentation"}},"UpdateAssetRequestBody":{"title":"Update Asset Request Body","type":"object","properties":{"contentType":{"$ref":"#/components/schemas/AssetContentType"},"filename":{"$ref":"#/components/schemas/AssetFilename"}},"additionalProperties":false,"$id":"./components/schemas/UpdateAssetRequestBody","externalDocs":{"url":"https://developer.hedia.com/services/asset/api/v1/components/schemas/UpdateAssetRequestBody","description":"Documentation"}}},"parameters":{"LimitQueryParameter":{"name":"limit","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Limit"}},"OrderQueryParameter":{"name":"order","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Order"}},"SkipQueryParameter":{"name":"skip","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Skip"}},"StatusQueryParameter":{"name":"status","in":"query","required":false,"schema":{"$ref":"#/components/schemas/AssetStatus"}},"AssetIdPathParameter":{"name":"assetId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/AssetId"}},"AppIdQueryParameter":{"name":"appId","in":"query","description":"The app the asset is expected to belong to. Only used (and required) when authenticating with the\n`trustedServiceWithUser` security scheme, which has no app of its own — used to keep the operation\napp-scoped for that scheme, the same as it already is for `accessToken`. Ignored when authenticating\nwith `accessToken`, whose own app is used instead.\n","required":false,"schema":{"$ref":"#/components/schemas/AppId"}}},"responses":{"InternalServerError":{"description":"Internal Server Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"BadRequest":{"description":"Bad Request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"Unauthorized":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"UnprocessableEntity":{"description":"Unprocessable Entity","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"NotFound":{"description":"Not Found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"NoContent":{"description":"No Content"}}},"externalDocs":{"url":"https://developer.hedia.com/","description":"Documentation"}}