API Reference — Storage

Introduction

REST APIs usable via HTTP in any environment. The CLI is also available.

curl https://storage.liteio.dev/files \
  -H "Authorization: Bearer $STORAGE_API_KEY"

Authentication

Create API keys via POST /auth/keys or the dashboard. Provide them as Bearer tokens.

Authorization: Bearer STORAGE_API_KEY

Keys can be scoped to a path prefix (e.g. docs/) and set to expire. Keep keys secret. Never expose in client-side code.

Content types

Send request bodies as JSON with Content-Type: application/json.

GET /files/{path} returns a 302 redirect to a presigned URL by default. Set Accept: application/json to get metadata instead.

Errors

Errors return JSON with a consistent shape:

{
  "error": "not_found",
  "message": "File not found"
}

Code	Error	Meaning
400	`bad_request`	Invalid parameters or body
401	`unauthorized`	Missing or invalid auth
403	`forbidden`	Path not allowed
404	`not_found`	Resource not found
409	`conflict`	Already exists
429	`rate_limited`	Too many requests
500	`internal`	Server error

Files

Retrieve a file

GET /files/{path}

Downloads a file by path. By default returns a 302 redirect to a presigned R2 URL. With Accept: application/json, returns metadata including the presigned URL, file size, content type, and ETag.

Path Parameters

path: string

File path (e.g. docs/report.pdf)

302 Redirect to presigned URL

404 File not found

Retrieve a file

1curl https://storage.liteio.dev/files/:path \
2  -H "Authorization: Bearer $STORAGE_API_KEY"

Retrieve file metadata

HEAD /files/{path}

Returns file metadata in HTTP response headers (Content-Type, Content-Length, ETag) without downloading the file body. Useful for checking if a file exists or getting its size.

Path Parameters

path: string

File path (e.g. docs/report.pdf)

Returns 200

Metadata in headers

404 Not found

Retrieve file metadata

1curl https://storage.liteio.dev/files/:path \
2  -H "Authorization: Bearer $STORAGE_API_KEY"

List files

GET /files

Returns a list of files and folders in the authenticated user's storage. Results are paginated and can be filtered by prefix to list contents of a specific folder.

Query Parameters

prefix: optional string

Folder prefix (e.g. docs/)

limit: optional integer | null

Defaults to 200.

offset: optional integer | null

Defaults to 0.

Returns 200

Directory listing

prefix: string

entries: array of object { name, type, size, ... }

truncated: boolean

List files

1curl https://storage.liteio.dev/files \
2  -H "Authorization: Bearer $STORAGE_API_KEY"

1{
2  "prefix": "string",
3  "entries": [
4    {
5      "name": "string",
6      "type": "string",
7      "size": 0,
8      "updated_at": 0,
9      "tx": 0,
10      "tx_time": 0
11    }
12  ],
13  "truncated": true
14}

Search files

GET /files/search

Searches for files by name across the authenticated user's storage. Supports multi-word queries with relevance scoring. Results are sorted by match quality.

Query Parameters

q: string

Search query

limit: optional integer | null

Defaults to 50.

Returns 200

Search results

query: string

results: array of object { path, name, ... }

Search files

1curl https://storage.liteio.dev/files/search \
2  -H "Authorization: Bearer $STORAGE_API_KEY"

1{
2  "query": "string",
3  "results": [
4    {
5      "path": "string",
6      "name": "string"
7    }
8  ]
9}

Create a folder

POST /files/mkdir

Creates an empty folder marker in storage. The path must end with /. Folders are virtual — they exist as zero-byte objects in R2.

Body Parameters

path: string

Folder path (must end with /)

Returns 200

Folder created

path: string

created: boolean

Create a folder

1curl -X POST https://storage.liteio.dev/files/mkdir \
2  -H "Authorization: Bearer $STORAGE_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{"path":"docs/drafts/"}'

1{
2  "path": "string",
3  "created": true
4}

Move a file

POST /files/move

Moves or renames a file within the authenticated user's storage. Both the source and destination paths must be valid. The file's content and metadata are preserved.

Body Parameters

from: string

to: string

message: optional string

Commit message for the move

Returns 200

Moved

from: string

to: string

tx: integer

time: integer

Move a file

1curl -X POST https://storage.liteio.dev/files/move \
2  -H "Authorization: Bearer $STORAGE_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{"from":"string","to":"string","message":"string"}'

1{
2  "from": "string",
3  "to": "string",
4  "tx": 0,
5  "time": 0
6}

Delete a file

DELETE /files/{path}

Permanently deletes a file or folder. For folders (paths ending with /), recursively deletes all contents. This action cannot be undone.

Path Parameters

path: string

File path (e.g. docs/report.pdf)

Returns 200

Delete result

deleted: integer

tx: integer

time: integer

Delete a file

1curl -X DELETE https://storage.liteio.dev/files/:path \
2  -H "Authorization: Bearer $STORAGE_API_KEY"

1{
2  "deleted": 0,
3  "tx": 0,
4  "time": 0
5}

Retrieve storage stats

GET /files/stats

Returns aggregate storage statistics for the authenticated user, including total file count and total bytes used.

Returns 200

Usage

files: integer

bytes: integer

Retrieve storage stats

1curl https://storage.liteio.dev/files/stats \
2  -H "Authorization: Bearer $STORAGE_API_KEY"

1{
2  "files": 0,
3  "bytes": 0
4}

View event log

GET /files/log

Query Parameters

path: optional string

Filter events by file path

since_tx: optional integer | null

Return events after this tx number

limit: optional integer | null

Defaults to 50.

Returns 200

Event log

events: array of object { tx, action, path, ... }

View event log

1curl https://storage.liteio.dev/files/log \
2  -H "Authorization: Bearer $STORAGE_API_KEY"

1{
2  "events": [
3    {
4      "tx": 0,
5      "action": "string",
6      "path": "string",
7      "size": 0,
8      "msg": "string",
9      "ts": 0
10    }
11  ]
12}

Uploads

Create an upload

POST /files/uploads

Initiates a file upload by generating a presigned PUT URL. Upload the file directly to this URL using an HTTP PUT request, then call Complete an upload to index it in the database.

Body Parameters

path: string

content_type: optional string

Returns 200

Presigned upload URL

url: string

content_type: string

expires_in: integer

Create an upload

1curl -X POST https://storage.liteio.dev/files/uploads \
2  -H "Authorization: Bearer $STORAGE_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{"path":"docs/report.pdf","content_type":"string"}'

1{
2  "url": "string",
3  "content_type": "string",
4  "expires_in": 0
5}

Complete an upload

POST /files/uploads/complete

Confirms a file upload after the file has been uploaded to the presigned URL. Verifies the object exists in R2 and indexes it in the database with its metadata.

Body Parameters

path: string

message: optional string

Commit message

Returns 200

File metadata

path: string

size: integer

tx: integer

time: integer

Complete an upload

1curl -X POST https://storage.liteio.dev/files/uploads/complete \
2  -H "Authorization: Bearer $STORAGE_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{"path":"string","message":"string"}'

1{
2  "path": "string",
3  "name": "string",
4  "size": 0,
5  "tx": 0,
6  "time": 0
7}

Create a multipart upload

POST /files/uploads/multipart

Initiates a multipart upload for large files. Returns presigned URLs for each part. Upload parts in parallel for faster transfers, then call Complete a multipart upload.

Body Parameters

path: string

content_type: optional string

part_count: optional integer

Returns 200

Multipart upload initiated

upload_id: string

key: string

content_type: string

part_urls: array of string

expires_in: integer

Create a multipart upload

1curl -X POST https://storage.liteio.dev/files/uploads/multipart \
2  -H "Authorization: Bearer $STORAGE_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{"path":"string","content_type":"string","part_count":0}'

1{
2  "upload_id": "string",
3  "key": "string",
4  "content_type": "string",
5  "part_urls": ["string"],
6  "expires_in": 0
7}

Complete a multipart upload

POST /files/uploads/multipart/complete

Finalizes a multipart upload by assembling all uploaded parts into a single object. You must provide the ETag returned from each part upload.

Body Parameters

path: string

upload_id: string

parts: array of object { part_number, etag, ... }

message: optional string

Commit message

Returns 200

Upload completed

path: string

size: integer

tx: integer

time: integer

Complete a multipart upload

1curl -X POST https://storage.liteio.dev/files/uploads/multipart/complete \
2  -H "Authorization: Bearer $STORAGE_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{"path":"string","upload_id":"string","parts":[{"part_number":0,"etag":"string"}],"message":"string"}'

1{
2  "path": "string",
3  "name": "string",
4  "size": 0,
5  "tx": 0,
6  "time": 0
7}

Abort a multipart upload

POST /files/uploads/multipart/abort

Cancels an in-progress multipart upload and cleans up any parts that have already been uploaded.

Body Parameters

path: string

upload_id: string

Returns 200

Upload aborted

aborted: boolean

Abort a multipart upload

1curl -X POST https://storage.liteio.dev/files/uploads/multipart/abort \
2  -H "Authorization: Bearer $STORAGE_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{"path":"string","upload_id":"string"}'

1{
2  "aborted": true
3}

Share a file

POST /files/share

Creates a temporary, public share link for a file. The link expires after the specified TTL (default 1 hour, maximum 7 days). Anyone with the link can download the file.

Body Parameters

path: string

ttl: optional integer

Seconds (default 3600, max 604800)

Returns 201

Share link created

url: string

token: string

expires_at: integer

ttl: integer

Share a file

1curl -X POST https://storage.liteio.dev/files/share \
2  -H "Authorization: Bearer $STORAGE_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{"path":"string","ttl":0}'

1{
2  "url": "string",
3  "token": "string",
4  "expires_at": 0,
5  "ttl": 0
6}

Access a shared file

GET /s/{token}

Accesses a file using a share token created via Share a file. Returns a 302 redirect to a presigned R2 URL for downloading. No authentication is required.

Path Parameters

token: string

Share token

302 Redirect to presigned R2 URL

Returns 401

Invalid or expired token

error: string

message: string

Access a shared file

1curl https://storage.liteio.dev/s/:token

Authentication

Request a magic link

POST /auth/magic-link

Sends a passwordless sign-in link to the provided email address. The link is single-use and expires after 15 minutes. A generic response is always returned to prevent email enumeration.

Body Parameters

email: string

cf-turnstile-response: optional string

Turnstile token (browser clients)

Returns 200

Magic link sent

message: string

Returns 400

Bad request

error: string

message: string

Returns 403

Bot check failed

error: string

message: string

Returns 409

Conflict

error: string

message: string

Returns 429

Rate limited

error: string

message: string

Returns 500

Email delivery failed

error: string

message: string

Request a magic link

1curl -X POST https://storage.liteio.dev/auth/magic-link \
2  -H "Content-Type: application/json" \
3  -d '{"email":"you@email.com","cf-turnstile-response":"string"}'

1{
2  "message": "string"
3}

Register an account

POST /auth/register

Creates a new account with an Ed25519 public key for cryptographic signature-based authentication. The actor name must be 1-64 characters, alphanumeric with hyphens and underscores.

Body Parameters

actor: string

type: optional human or agent

Defaults to human.

public_key: string

Base64 Ed25519 public key

Returns 201

Created

actor: string

type: string

Returns 400

Bad request

error: string

message: string

Returns 409

Actor already exists

error: string

message: string

Returns 429

Rate limited

error: string

message: string

1curl -X POST https://storage.liteio.dev/auth/register \
2  -H "Content-Type: application/json" \
3  -d '{"actor":"alice","type":"human","public_key":"string"}'

1{
2  "actor": "string",
3  "type": "string"
4}

Create a challenge

POST /auth/challenge

Issues a cryptographic nonce for Ed25519 signature verification. The challenge expires after 5 minutes. Sign the nonce with your private key and submit via Verify a signature.

Body Parameters

actor: string

Returns 200

Challenge issued

challenge_id: string

nonce: string

expires_at: integer

Returns 400

Bad request

error: string

message: string

Returns 404

Actor not found

error: string

message: string

Returns 429

Rate limited

error: string

message: string

Create a challenge

1curl -X POST https://storage.liteio.dev/auth/challenge \
2  -H "Content-Type: application/json" \
3  -d '{"actor":"alice"}'

1{
2  "challenge_id": "string",
3  "nonce": "string",
4  "expires_at": 0
5}

Verify a signature

POST /auth/verify

Verifies an Ed25519 signature of the challenge nonce and issues a session token. The session token can be used as a Bearer token for authenticated requests.

Body Parameters

challenge_id: string

actor: string

signature: string

Base64 Ed25519 signature of the nonce

Returns 200

Session token

token: string

actor: string

expires_at: integer

Returns 400

Bad request

error: string

message: string

Returns 401

Invalid signature

error: string

message: string

Returns 404

Challenge not found

error: string

message: string

Returns 429

Rate limited

error: string

message: string

Verify a signature

1curl -X POST https://storage.liteio.dev/auth/verify \
2  -H "Content-Type: application/json" \
3  -d '{"challenge_id":"string","actor":"string","signature":"string"}'

1{
2  "token": "string",
3  "actor": "string",
4  "expires_at": 0
5}

Log out

POST /auth/logout

Invalidates the current session token. Accepts the token from either the Authorization header or a session cookie.

Returns 200

ok: boolean

Log out

1curl -X POST https://storage.liteio.dev/auth/logout

1{
2  "ok": true
3}

API Keys

Create an API key

POST /auth/keys

Creates a new API key for programmatic access. The key token is returned exactly once in the response — store it securely, as it cannot be retrieved again.

Body Parameters

Defaults to .

prefix: optional string

Restrict to paths starting with this prefix Defaults to .

expires_in: optional integer

Seconds until expiry

Returns 201

API key (token shown once)

id: string

token: string

Store securely — not shown again

prefix: string

expires_at: integer | null

Returns 429

Rate limited

error: string

message: string

Create an API key

1curl -X POST https://storage.liteio.dev/auth/keys \
2  -H "Authorization: Bearer $STORAGE_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{"name":"deploy-bot","prefix":"string","expires_in":0}'

1{
2  "id": "string",
3  "token": "string",
4  "name": "string",
5  "prefix": "string",
6  "expires_at": 0
7}

List API keys

GET /auth/keys

Returns all API keys for the authenticated user. Key tokens (secrets) are never included in the response — only metadata like name, prefix scope, and expiry.

Returns 200

API keys

keys: array of object { id, name, prefix, ... }

List API keys

1curl https://storage.liteio.dev/auth/keys \
2  -H "Authorization: Bearer $STORAGE_API_KEY"

1{
2  "keys": [
3    {
4      "id": "string",
5      "name": "string",
6      "prefix": "string",
7      "expires_at": 0,
8      "created_at": 0
9    }
10  ]
11}

Delete an API key

DELETE /auth/keys/{id}

Permanently revokes an API key. Any requests using this key will immediately start returning 401 Unauthorized.

Path Parameters

id: string

Returns 200

Deleted

deleted: boolean

Returns 404

Not found

error: string

message: string

Delete an API key

1curl -X DELETE https://storage.liteio.dev/auth/keys/:id \
2  -H "Authorization: Bearer $STORAGE_API_KEY"

1{
2  "deleted": true
3}

Storage API

Introduction

Authentication

Content types

Errors

Retrieve a file

Path Parameters

Retrieve file metadata

Path Parameters

Returns 200

List files

Query Parameters

Returns 200

Search files

Query Parameters

Returns 200

Create a folder

Body Parameters

Returns 200

Move a file

Body Parameters

Returns 200

Delete a file

Path Parameters

Returns 200

Retrieve storage stats

Returns 200

View event log

Query Parameters

Returns 200

Create an upload

Body Parameters

Returns 200

Complete an upload

Body Parameters

Returns 200

Create a multipart upload

Body Parameters

Returns 200

Complete a multipart upload

Body Parameters

Returns 200

Abort a multipart upload

Body Parameters

Returns 200

Share a file

Body Parameters

Returns 201

Access a shared file

Path Parameters

Returns 401

Request a magic link

Body Parameters

Returns 200

Returns 400

Returns 403

Returns 409

Returns 429

Returns 500

Register an account

Body Parameters

Returns 201

Returns 400

Returns 409

Returns 429

Create a challenge

Body Parameters

Returns 200

Returns 400

Returns 404

Returns 429

Verify a signature

Body Parameters

Returns 200

Returns 400

Returns 401

Returns 404

Returns 429

Log out

Returns 200