Documentation

Overview

You reach Lyvyl in two ways: the S3 API for files, and the management API at https://api.lyvyl.xyz for account resources such as buckets, keys and usage. Both accept the same API keys.

Authentication

Create keys on your account page. Each key has an access key ID and a secret, and can be limited to specific buckets or to read-only access. Send the secret to the management API as a bearer token:

List your buckets

curl https://api.lyvyl.xyz/v1/buckets \
  -H "Authorization: Bearer $KEY"

Requests without a valid key receive a 401 response with the unauthorized error code.

S3 clients

Use the endpoint shown on your account page and the region auto. Path-style and virtual-hosted-style addressing both work.

rclone remote

[storage]
type = s3
provider = Other
endpoint = $ENDPOINT
access_key_id = $ACCESS_KEY_ID
secret_access_key = $SECRET
region = auto

aws-cli

aws s3 ls s3://my-site/ --endpoint-url "$ENDPOINT"

Management API

Base URL: https://api.lyvyl.xyz. All responses are JSON encoded as UTF-8.

Endpoint	Description	Key
GET /v1/health	Service health check	No
GET /v1/status	Status of services and regions	No
GET /v1/buckets	List buckets	Yes
POST /v1/buckets	Create a bucket	Yes
DELETE /v1/buckets/{name}	Delete an empty bucket	Yes
GET /v1/keys	List API keys	Yes
GET /v1/usage	Storage and traffic for the current month	Yes

GET /v1/status

{
  "status": "operational",
  "updated_at": "2026-11-14T12:00:00Z",
  "components": [
    { "id": "storage", "name": "Object storage", "status": "operational" }
  ],
  "regions": [
    { "id": "fra1", "name": "Frankfurt", "status": "operational" }
  ]
}

Image URLs

Add these parameters to the URL of any image in a public bucket. Unknown parameters are ignored.

Parameter	Values	Effect
`w`, `h`	1 to 4096	Target width and height in pixels
`fit`	`cover`, `contain`	Crop to fill the box, or fit inside it
`fmt`	`auto`, `avif`, `webp`, `jpeg`	Output format; `auto` picks per browser
`q`	1 to 100	Quality for lossy formats, default 80

Errors

Errors use standard HTTP status codes and a JSON body with a stable code you can match on and a message written for people.

401 Unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key. Send it as: Authorization: Bearer <key>."
  }
}

400 bad_request: the request could not be parsed.
401 unauthorized: the API key is missing or invalid.
403 forbidden: the key has no access to this resource.
404 not_found: the endpoint or resource does not exist.
405 method_not_allowed: the endpoint does not accept that method.
429 rate_limited: too many requests; retry after the time in Retry-After.
500 internal_error: the request failed on our side.

Limits

Management API: 1,200 requests per minute per key.
Single upload: 5 GB. Multipart uploads: up to 10,000 parts and 5 TB.
Object keys: up to 1,024 bytes of UTF-8.