# Aperture

> Self-hosted media API for game servers: FiveM, RedM and anything that sends HTTP.

## Machine readable

- OpenAPI 3.1 schema: https://aperture-app.preview.moncompanion.cloud/openapi.yaml

## Endpoints

- `GET /api/v1/status` Introspection: Instance health and identity
- `POST /api/v1/uploads` Uploads: Upload a file
- `POST /api/v1/uploads/base64` Uploads: Upload a base64 payload
- `POST /api/v1/upload-tickets` Uploads: Mint a player upload ticket
- `POST /api/v1/player-uploads/{ticket}` Uploads: Upload with a player ticket
- `GET /api/v1/media` Media: List media
- `GET /api/v1/media/{media}` Media: Retrieve one media
- `PATCH /api/v1/media/{media}` Media: Update metadata or retention
- `DELETE /api/v1/media/{media}` Media: Delete a media
- `GET /api/v1/token` Introspection: Describe the presented token
- `GET /api/v1/usage` Introspection: Hourly usage for the organisation
- `POST /api/v3/file` Compatibility: Compatible v3 upload
- `POST /api/v3/file/base64` Compatibility: Compatible v3 upload, base64
- `POST /api/v2/{kind}` Compatibility: Compatible v2 upload
- `POST /api/{kind}` Compatibility: Compatible legacy API upload
- `POST /lb-upload` Compatibility: LBUpload
- `GET /api/v1/asset-categories` Assets: List asset categories
- `POST /api/v1/asset-categories` Assets: Create an asset category
- `PATCH /api/v1/asset-categories/{category}` Assets: Rename a category or change its rules
- `DELETE /api/v1/asset-categories/{category}` Assets: Delete an empty category
- `GET /api/v1/assets` Assets: List assets
- `GET /api/v1/assets/{category}/{key}` Assets: Retrieve an asset with its full version history
- `POST /api/v1/assets/{category}/{key}` Assets: Upload a new version
- `DELETE /api/v1/assets/{category}/{key}` Assets: Delete an asset
- `POST /api/v1/assets/{category}/{key}/base64` Assets: Upload a new version as base64
- `POST /api/v1/assets/{category}/{key}/rollback` Assets: Serve another version at the stable URL
- `POST /api/v1/assets/{category}/{key}/restore` Assets: Restore a deleted asset
- `POST /api/v1/assets/{category}/{key}/tickets` Assets: Issue a single-use upload ticket
- `POST /api/v1/asset-uploads/{ticket}` Assets: Upload with a ticket
- `DELETE /api/v1/assets/{category}/{key}/versions/{version}` Assets: Delete one version

## Error codes

- `missing_token` (401): No API token was provided. Not retryable.
- `invalid_token` (401): The API token is not valid. Not retryable.
- `token_revoked` (401): This API token has been revoked. Not retryable.
- `ip_not_allowed` (403): This API token is not allowed from this IP address. Not retryable.
- `insufficient_scope` (403): This API token does not carry the scope required for that action. Not retryable.
- `feature_not_enabled` (403): That feature is not enabled for this organization. Not retryable.
- `forbidden` (403): You are not allowed to perform that action. Not retryable.
- `no_file_provided` (422): No file was present in the request. Not retryable.
- `unsupported_media_type` (415): That file type is not accepted. Not retryable.
- `file_too_large` (413): The file exceeds the maximum size allowed for its type. Not retryable.
- `invalid_base64` (422): The base64 payload could not be decoded. Not retryable.
- `invalid_metadata` (422): The metadata field is not valid JSON. Not retryable.
- `corrupt_upload` (422): The uploaded file could not be read as the type it claims to be. Not retryable.
- `quota_exceeded` (413): Storage quota reached for this organization. Not retryable.
- `rate_limited` (429): Too many requests. Slow down and retry after the delay in Retry-After. Retryable.
- `storage_unreachable` (503): The configured storage backend did not answer. Retryable.
- `storage_write_failed` (500): The file could not be written to the storage backend. Retryable.
- `storage_verification_failed` (500): The file was written but did not verify, so it was discarded. Not retryable.
- `media_not_found` (404): No media exists with that identifier. Not retryable.
- `route_not_found` (404): No API route matches that path. Not retryable.
- `method_not_allowed` (405): That HTTP method is not allowed on this route. Not retryable.
- `transcode_failed` (500): The file could not be transcoded. Not retryable.
- `encoder_unavailable` (503): The encoder is not available on this instance. Retryable.
- `server_error` (500): Something went wrong on our side. Retryable.
- `maintenance` (503): The platform is under maintenance. Retry after the delay in Retry-After. Retryable.
- `asset_not_found` (404): No asset exists with that category and key. Not retryable.
- `asset_version_not_found` (404): That asset has no such version. Not retryable.
- `asset_category_not_found` (404): No asset category exists with that slug. Not retryable.
- `asset_category_exists` (409): An asset category with that slug already exists. Not retryable.
- `asset_category_not_empty` (409): The asset category still holds assets. Delete or move them first. Not retryable.
- `asset_rule_violated` (422): The file does not meet the rules of its asset category. Not retryable.
- `asset_version_current` (409): That version is the one the asset currently serves. Roll back to another version first. Not retryable.
- `asset_version_not_ready` (409): That version is still processing or failed, so it cannot be served. Not retryable.
- `upload_ticket_invalid` (401): The upload ticket is unknown, expired or already used. Ask the server for a new one. Not retryable.